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) → $axiom-memory-debugging
- Systematic leak diagnosis
- 5 common leak patterns
- Instruments workflows
- deinit not called
Memory leak scan → Launch memory-auditor agent or /axiom:audit memory (6 common patterns: timers, observers, closures, delegates, view callbacks, PhotoKit)
Memory leaks (Objective-C blocks) → $axiom-objc-block-retain-cycles
- Block retain cycles
- Weak-strong pattern
- Network callback leaks
Performance Profiling
Performance profiling (GUI) → $axiom-performance-profiling
- Time Profiler (CPU)
- Allocations (memory growth)
- Core Data profiling (N+1 queries)
- Decision trees for tool selection
Automated profiling (CLI) → $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 → $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 → $axiom-energy
- Power Profiler workflow
- Subsystem diagnosis (CPU/GPU/Network/Location/Display)
- Anti-pattern fixes
- Background execution optimization
Symptom-based diagnosis → $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 → $axiom-energy-ref
- Complete WWDC code examples
- Timer, network, location efficiency
- BGContinuedProcessingTask (iOS 26)
- MetricKit setup
Energy scan → Launch energy-auditor agent or /axiom:audit energy (8 anti-patterns: timer abuse, polling, continuous location, animation leaks, background mode misuse, network inefficiency, GPU waste, disk I/O)
Swift Performance
Swift performance optimization → $axiom-swift-performance
- Value vs reference types, copy-on-write
- ARC overhead, generic specialization
- Collection performance
Swift performance scan → Launch swift-performance-analyzer agent or /axiom:audit swift-performance (unnecessary copies, ARC overhead, unspecialized generics, collection inefficiencies, actor isolation costs, memory layout)
MetricKit Integration
MetricKit API reference → $axiom-metrickit-ref
- MXMetricPayload parsing
- MXDiagnosticPayload (crashes, hangs)
- Field performance data collection
- Integration with crash reporting
Runtime State Inspection
LLDB interactive debugging → $axiom-lldb
- Set breakpoints, inspect variables at runtime
- Crash reproduction from crash logs
- Thread state analysis for hangs
- Swift value inspection (po vs v)
LLDB command reference → $axiom-lldb-ref
- Complete command syntax
- Breakpoint recipes
- Expression evaluation patterns
Decision Tree
- Memory climbing + UI stutter/jank? → memory-debugging FIRST (memory pressure causes GC pauses that drop frames), then performance-profiling if memory is fixed but stutter remains
- Memory leak (Swift)? → memory-debugging
- Memory leak (Objective-C blocks)? → objc-block-retain-cycles
- App hang/freeze — is UI completely unresponsive (can't tap, no feedback)?
- YES → hang-diagnostics (busy vs blocked diagnosis)
- NO, just slow → performance-profiling (Time Profiler)
- First launch only? → Also check for synchronous I/O or lazy initialization in hang-diagnostics
- Slowdown when multiple async operations complete at once? → Cross-route to
axiom-ios-concurrency(callback contention, not profiling) - Battery drain (know the symptom)? → energy-diag
- Battery drain (need API reference)? → energy-ref
- Battery drain (general)? → energy
- MetricKit setup/parsing? → metrickit-ref
- Profile with GUI (Instruments)? → performance-profiling
- Profile with CLI (xctrace)? → xctrace-ref
- Run automated profile now? → performance-profiler agent
- General slow/lag? → performance-profiling
- Want proactive memory leak scan? → memory-auditor (Agent)
- Want energy anti-pattern scan? → energy-auditor (Agent)
- Want Swift performance audit (ARC, generics, collections)? → swift-performance-analyzer (Agent)
- Need to inspect variable/thread state at runtime? → axiom-lldb
- Need exact LLDB command syntax? → axiom-lldb-ref
Anti-Rationalization
| Thought | Reality |
|---|---|
| "I know it's a memory leak, let me find it" | Memory leaks have 6 patterns. memory-debugging diagnoses the right one in 15 min vs 2 hours. |
| "I'll just run Time Profiler" | Wrong Instruments template wastes time. performance-profiling selects the right tool first. |
| "Battery drain is probably the network layer" | Energy issues span 8 subsystems. energy skill diagnoses the actual cause. |
| "App feels slow, I'll optimize later" | Performance issues compound. Profiling now saves exponentially more time later. |
| "It's just a UI freeze, probably a slow API call" | Freezes have busy vs blocked causes. hang-diagnostics has a decision tree for both. |
| "Memory is climbing AND scrolling stutters — two separate bugs" | Memory pressure causes GC pauses that drop frames. Fix the leak first, then re-check scroll performance. |
| "It only freezes on first launch, must be loading something" | First-launch hangs have 3 patterns: synchronous I/O, lazy initialization, main thread contention. hang-diagnostics diagnoses which. |
| "UI locks up when network requests finish — that's slow" | Multiple callbacks completing at once = main thread contention = concurrency issue. Cross-route to ios-concurrency. |
| "I'll just add print statements to debug this" | Print-debug cycles cost 3-5 min each (build + run + reproduce). An LLDB breakpoint costs 30 seconds. axiom-lldb has the commands. |
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: $axiom-memory-debugging
User: "I have a memory leak but deinit isn't being called"
→ Invoke: $axiom-memory-debugging
User: "My app feels slow, where do I start?"
→ Invoke: $axiom-performance-profiling
User: "My Objective-C block callback is leaking"
→ Invoke: $axiom-objc-block-retain-cycles
User: "My app drains battery quickly"
→ Invoke: $axiom-energy
User: "Users say the device gets hot when using my app"
→ Invoke: $axiom-energy-diag
User: "What's the best way to implement location tracking efficiently?"
→ Invoke: $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: $axiom-xctrace-ref
User: "I need headless profiling for CI/CD"
→ Invoke: $axiom-xctrace-ref
User: "My app hangs sometimes"
→ Invoke: $axiom-hang-diagnostics
User: "The UI freezes and becomes unresponsive"
→ Invoke: $axiom-hang-diagnostics
User: "Main thread is blocked, how do I diagnose?"
→ Invoke: $axiom-hang-diagnostics
User: "How do I set up MetricKit?"
→ Invoke: $axiom-metrickit-ref
User: "How do I parse MXMetricPayload?"
→ Invoke: $axiom-metrickit-ref
User: "Scan my code for memory leaks"
→ Invoke: memory-auditor agent
User: "Check my app for battery drain issues"
→ Invoke: energy-auditor agent
User: "Audit my Swift code for performance anti-patterns"
→ Invoke: swift-performance-analyzer agent
User: "How do I inspect this variable in the debugger?"
→ Invoke: $axiom-lldb
User: "What's the LLDB command for conditional breakpoints?"
→ Invoke: $axiom-lldb-ref
User: "I need to reproduce this crash in the debugger"
→ Invoke: $axiom-lldb
User: "My list scrolls slowly and memory keeps growing"
→ Invoke: $axiom-memory-debugging first, then $axiom-performance-profiling if stutter remains
User: "App freezes for a few seconds on first launch then works fine"
→ Invoke: $axiom-hang-diagnostics
User: "UI locks up when multiple API calls return at the same time"
→ Cross-route: $axiom-ios-concurrency (callback contention)