iOS Performance Router

You MUST use this skill for ANY performance issue including memory leaks, slow execution, battery drain, or profiling.

When to Use

Use this router when: - App feels slow or laggy - Memory usage grows over time - Battery drains quickly - Device gets hot during use - High energy usage in Battery Settings - Diagnosing performance with Instruments - Memory leaks or retain cycles - App crashes with memory warnings

Routing Logic

Memory Issues

Memory leaks (Swift) → /skill axiom-memory-debugging - Systematic leak diagnosis - 5 common leak patterns - Instruments workflows - deinit not called

Memory leaks (Objective-C blocks) → /skill axiom-objc-block-retain-cycles - Block retain cycles - Weak-strong pattern - Network callback leaks

Performance Profiling

Performance profiling (GUI) → /skill axiom-performance-profiling - Time Profiler (CPU) - Allocations (memory growth) - Core Data profiling (N+1 queries) - Decision trees for tool selection

Automated profiling (CLI) → /skill axiom-xctrace-ref - Headless xctrace profiling - CI/CD integration patterns - Command-line trace recording - Programmatic trace analysis

Run automated profile → Use performance-profiler agent or /axiom:profile - Records trace via xctrace - Exports and analyzes data - Reports findings with severity

Hang/Freeze Issues

App hangs or freezes → /skill axiom-hang-diagnostics - UI unresponsive for >1 second - Main thread blocked (busy or waiting) - Decision tree: busy vs blocked diagnosis - Time Profiler vs System Trace selection - 8 common hang patterns with fixes - Watchdog terminations

Energy Issues

Battery drain, high energy → /skill axiom-energy - Power Profiler workflow - Subsystem diagnosis (CPU/GPU/Network/Location/Display) - Anti-pattern fixes - Background execution optimization

Symptom-based diagnosis → /skill axiom-energy-diag - "App at top of Battery Settings" - "Device gets hot" - "Background battery drain" - Time-cost analysis for each path

API reference with code → /skill axiom-energy-ref - Complete WWDC code examples - Timer, network, location efficiency - BGContinuedProcessingTask (iOS 26) - MetricKit setup

MetricKit Integration

MetricKit API reference → /skill axiom-metrickit-ref - MXMetricPayload parsing - MXDiagnosticPayload (crashes, hangs) - Field performance data collection - Integration with crash reporting

Decision Tree

User reports performance issue
  ├─ Memory?
  │  ├─ Swift code? → memory-debugging
  │  └─ Objective-C blocks? → objc-block-retain-cycles
  │
  ├─ Hang/Freeze (UI unresponsive >1 second)?
  │  └─ YES → hang-diagnostics
  │
  ├─ Energy/Battery?
  │  ├─ Know the symptom? → energy-diag
  │  ├─ Need API reference? → energy-ref
  │  └─ General battery drain? → energy
  │
  ├─ MetricKit setup/parsing?
  │  └─ YES → metrickit-ref
  │
  ├─ Want to profile?
  │  ├─ GUI workflow? → performance-profiling
  │  ├─ CLI/automation? → xctrace-ref
  │  ├─ Run profile now? → performance-profiler agent
  │  └─ Unsure → performance-profiling
  │
  └─ General slow/lag? → performance-profiling

Critical Patterns

Memory Debugging (memory-debugging): - 6 leak patterns: timers, observers, closures, delegates, view callbacks, PhotoKit - Instruments workflows - Leak vs caching distinction

Performance Profiling (performance-profiling): - Time Profiler for CPU bottlenecks - Allocations for memory growth - Core Data SQL logging for N+1 queries - Self Time vs Total Time

Energy Optimization (energy): - Power Profiler subsystem diagnosis - 8 anti-patterns: timers, polling, location, animations, background, network, GPU, disk - Audit checklists by subsystem - Pressure scenarios for deadline resistance

Example Invocations

User: "My app's memory usage keeps growing" → Invoke: /skill axiom-memory-debugging

User: "I have a memory leak but deinit isn't being called" → Invoke: /skill axiom-memory-debugging

User: "My app feels slow, where do I start?" → Invoke: /skill axiom-performance-profiling

User: "My Objective-C block callback is leaking" → Invoke: /skill axiom-objc-block-retain-cycles

User: "My app drains battery quickly" → Invoke: /skill axiom-energy

User: "Users say the device gets hot when using my app" → Invoke: /skill axiom-energy-diag

User: "What's the best way to implement location tracking efficiently?" → Invoke: /skill axiom-energy-ref

User: "Profile my app's CPU usage" → Use: performance-profiler agent (or /axiom:profile)

User: "How do I run xctrace from the command line?" → Invoke: /skill axiom-xctrace-ref

User: "I need headless profiling for CI/CD" → Invoke: /skill axiom-xctrace-ref

User: "My app hangs sometimes" → Invoke: /skill axiom-hang-diagnostics

User: "The UI freezes and becomes unresponsive" → Invoke: /skill axiom-hang-diagnostics

User: "Main thread is blocked, how do I diagnose?" → Invoke: /skill axiom-hang-diagnostics

User: "How do I set up MetricKit?" → Invoke: /skill axiom-metrickit-ref

User: "How do I parse MXMetricPayload?" → Invoke: /skill axiom-metrickit-ref