Cursor MCP Tool Boundary

The xclog, xcsym, and xcprof examples below are reference syntax, not executable commands for Cursor. Map each subcommand to the same-named MCP tool—for example, xclog launch to axiom_xclog_launch, xcsym crash to axiom_xcsym_crash, and xcprof record to axiom_xcprof_record—and preserve its arguments as structured fields. Do not run a bare helper binary. If a required MCP tool is unavailable, stop and report that the Axiom MCP integration is missing; do not fall back to a same-named executable.

Performance

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

Cursor Subagent Routing

Delegate to the appropriate Cursor subagent when this router calls for a specialized auditor.

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) → See skills/memory-debugging.md

• Systematic leak diagnosis
• 5 common leak patterns
• Instruments workflows
• deinit not called

Memory leak scan → Delegate to the memory-auditor subagent or /axiom-audit memory (5-phase semantic audit: maps resource ownership, detects 6 leak patterns, reasons about missing cleanup, correlates compound risks, scores lifecycle health)

Memory leaks (Objective-C blocks) → See skills/objc-block-retain-cycles.md

• Block retain cycles
• Weak-strong pattern
• Network callback leaks

Performance Profiling

Performance profiling (GUI) → See skills/performance-profiling.md

• Time Profiler (CPU), incl. Top Functions mode for scattered overhead (OS27)
• Allocations (memory growth)
• Core Data profiling (N+1 queries)
• Decision trees for tool selection
• Instruments 27 Run Comparisons, Swift executors instrument, Foundation Models instrument; Xcode 27 Organizer (Storage/hitches metrics, Metric Goals, Generate Recommendations)

Automated profiling (CLI) → See skills/xctrace-ref.md

• 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

Compare two traces / detect regressions → See skills/trace-comparison.md or /axiom-compare-traces

• Did this change slow down a hot path? Function-level CPU-share deltas
• CI gating with xcprof compare --fail-on-regression (non-zero exit)
• Regressions vs improvements, severity ranking, exit-code semantics

Hang/Freeze Issues

App hangs or freezes → See skills/hang-diagnostics.md

• 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

Corpus/aggregate hang triage (Sentry, ASC) → axiom-shipping (skills/production-triage.md) + triage-analyzer agent

• Multiple grouped hang reports from an aggregator, not a single .ips file
• Classify anr_idle_runloop vs anr_main_thread_block across the corpus
• Flag suspension/idle-runloop false-positives (the #1 hang by user count is often noise)
• Cluster into root-cause families and rank by impact

App Launch

Slow app launch → See skills/app-launch.md

• Slow first frame, frozen first screen, launch regression in Organizer
• Launch-phase model (pre-main / main→first frame / extended launch)
• Cold vs warm vs hot/resume vs notification launch — how to reproduce each
• App Launch instrument workflow, dyld Activity, measurement hygiene
• Pre-main fixes: linkage strategy (static vs dynamic vs mergeable, MERGED_BINARY_TYPE/MERGEABLE_LIBRARY), +load, main-thread deferral, priority inversion
• XCTApplicationLaunchMetric regression test, MXAppLaunchMetric field histograms, custom "app is interactive" signpost
• Push-notification launch path (tap→first pixel / tap→interactive targets)

Energy Issues

Battery drain, high energy → See skills/energy.md

• Power Profiler workflow
• Subsystem diagnosis (CPU/GPU/Network/Location/Display)
• Anti-pattern fixes
• Background execution optimization

Symptom-based diagnosis → See skills/energy-diag.md

• "App at top of Battery Settings"
• "Device gets hot"
• "Background battery drain"
• Time-cost analysis for each path

API reference with code → See skills/energy-ref.md

• Complete WWDC code examples
• Timer, network, location efficiency
• BGContinuedProcessingTask (iOS 26)
• MetricKit setup

Energy scan → Delegate to the energy-auditor subagent or /axiom-audit energy (8 anti-patterns: timer abuse, polling, continuous location, animation leaks, background mode misuse, network inefficiency, GPU waste, disk I/O)

Timer Safety

Timer crash patterns (DispatchSourceTimer) → See axiom-integration (skills/timer-patterns.md)

• 4 crash scenarios causing EXC_BAD_INSTRUCTION
• RunLoop mode gotcha (Timer stops during scroll)
• SafeDispatchTimer wrapper
• Timer vs DispatchSourceTimer decision

Timer API reference → See axiom-integration (skills/timer-patterns-ref.md)

• Timer, DispatchSourceTimer, Combine, AsyncTimerSequence APIs
• Lifecycle diagrams
• Platform availability

Swift Performance

Swift performance optimization → See skills/swift-performance.md

• Value vs reference types, copy-on-write
• ARC overhead, generic specialization
• Collection performance

Swift performance scan → Delegate to the swift-performance-analyzer subagent or /axiom-audit swift-performance (unnecessary copies, ARC overhead, unspecialized generics, collection inefficiencies, actor isolation costs, memory layout)

Modern Swift idioms → See axiom-swift (skills/swift-modern.md)

• Outdated API patterns (Date(), CGFloat, DateFormatter)
• Foundation modernization (URL.documentsDirectory, FormatStyle)
• Claude-specific hallucination corrections

MetricKit Integration

MetricKit API reference → See skills/metrickit-ref.md

• New Swift-first API (OS27): MetricManager AsyncSequence streams, typed MetricResult metrics (incl. Metal frame rate, storage), typed diagnostics with termination categories, launch-task tracking
• Per-state metrics (StateReporting framework, OS27): split hitch/hang/memory metrics by tab, mode, or experiment
• Crash reporter extensions (CrashReportExtension framework, OS27): process crashes at crash time with in-extension symbolication (Part 10)
• MXMetricPayload / MXDiagnosticPayload parsing (legacy, iOS 13–26)
• Field performance data collection
• Integration with crash reporting

Runtime Console Capture

Capture simulator console output → /axiom-console

• Capture print(), os_log(), Logger output from simulator
• Structured JSON with level, subsystem, category
• Bounded collection with --timeout and --max-lines
• Filter by subsystem or regex

Runtime State Inspection

LLDB interactive debugging → See axiom-build (skills/lldb.md)

• 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 → See axiom-build (skills/lldb-ref.md)

• Complete command syntax
• Breakpoint recipes
• Expression evaluation patterns

Decision Tree

1. 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
2. Memory leak (Swift)? → memory-debugging
3. Memory leak (Objective-C blocks)? → objc-block-retain-cycles
4. 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
   • Multiple grouped hang reports from Sentry/ASC (corpus, not single file)? → axiom-shipping (skills/production-triage.md) + triage-analyzer
5. Slowdown when multiple async operations complete at once? → Cross-route to axiom-concurrency (callback contention, not profiling)
6. Slow app launch / slow first frame / launch regression / slow after push tap? → app-launch
7. Battery drain (know the symptom)? → energy-diag
8. Battery drain (need API reference)? → energy-ref
9. Battery drain (general)? → energy
10. MetricKit setup/parsing? → metrickit-ref 10a. Metrics split by app state (per-tab hitch rate, experiment arms) or StateReporting? → metrickit-ref (Part 1) 10b. Profiling agentic/LLM features (Foundation Models instrument, token metrics)? → performance-profiling, then axiom-ai 10c. Building a crash reporter extension (process crashes at crash time)? → metrickit-ref (Part 10)
11. Profile with GUI (Instruments)? → performance-profiling
12. Profile with CLI (xctrace)? → xctrace-ref
13. Run automated profile now? → performance-profiler agent
14. General slow/lag? → performance-profiling 14a. Slow GRDB/SQLite queries (EXPLAIN QUERY PLAN, index design, cursors)? → See axiom-data (skills/grdb-performance.md)
15. Want proactive memory leak scan? → memory-auditor (Agent)
16. Want energy anti-pattern scan? → energy-auditor (Agent)
17. Want Swift performance audit (ARC, generics, collections)? → swift-performance-analyzer (Agent)
18. Need to inspect variable/thread state at runtime? → See axiom-build (skills/lldb.md)
19. Need exact LLDB command syntax? → See axiom-build (skills/lldb-ref.md)
20. Timer stops during scrolling? → timer-patterns (RunLoop mode)
21. EXC_BAD_INSTRUCTION crash with DispatchSourceTimer? → timer-patterns (4 crash patterns)
22. Choosing between Timer, DispatchSourceTimer, Combine timer, async timer? → timer-patterns
23. Need timer API syntax/lifecycle? → timer-patterns-ref
24. Code review for outdated Swift patterns? → swift-modern
25. Claude generating legacy APIs (DateFormatter, CGFloat, DispatchQueue)? → swift-modern
26. Need to see runtime console output before profiling? → axiom-tools (skills/xclog-ref.md) or /axiom-console
27. Have an .ips, MetricKit, or legacy .crash text file to symbolicate/triage? → axiom-tools (skills/xcsym-ref.md) or /axiom-analyze-crash

Anti-Rationalization

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" → See skills/memory-debugging.md

User: "I have a memory leak but deinit isn't being called" → See skills/memory-debugging.md

User: "My app feels slow, where do I start?" → See skills/performance-profiling.md

User: "My Objective-C block callback is leaking" → See skills/objc-block-retain-cycles.md

User: "My app drains battery quickly" → See skills/energy.md

User: "Users say the device gets hot when using my app" → See skills/energy-diag.md

User: "What's the best way to implement location tracking efficiently?" → See skills/energy-ref.md

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

User: "How do I run xctrace from the command line?" → See skills/xctrace-ref.md

User: "I need headless profiling for CI/CD" → See skills/xctrace-ref.md

User: "My app hangs sometimes" → See skills/hang-diagnostics.md

User: "The UI freezes and becomes unresponsive" → See skills/hang-diagnostics.md

User: "Main thread is blocked, how do I diagnose?" → See skills/hang-diagnostics.md

User: "Triage my Sentry hangs" / "Which ANR reports are real blocks?" → See axiom-shipping (skills/production-triage.md) + triage-analyzer agent (or /axiom-triage sentry)

User: "My app takes 3 seconds to launch" → See skills/app-launch.md

User: "Xcode Organizer says my launch time regressed" → See skills/app-launch.md

User: "How do I reduce pre-main / dyld time?" → See skills/app-launch.md

User: "Should I use mergeable libraries / statically link my frameworks?" → See skills/app-launch.md

User: "App is slow to come up after tapping a push notification" → See skills/app-launch.md

User: "How do I write a launch performance test?" → See skills/app-launch.md

User: "How do I set up MetricKit?" → See skills/metrickit-ref.md

User: "How do I parse MXMetricPayload?" → See skills/metrickit-ref.md

User: "How do I use the new MetricManager / migrate off MXMetricManager?" → See skills/metrickit-ref.md (Part 1)

User: "Can I get hitch metrics per tab or per experiment?" → See skills/metrickit-ref.md (Part 1, StateReporting)

User: "How do I profile my Foundation Models / agentic feature?" → See skills/performance-profiling.md (Foundation Models instrument), then axiom-ai

User: "How do I compare two Instruments runs to verify a fix?" → See skills/performance-profiling.md (Run Comparisons) or skills/trace-comparison.md (CLI/CI)

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: See axiom-build (skills/lldb.md)

User: "What's the LLDB command for conditional breakpoints?" → Invoke: See axiom-build (skills/lldb-ref.md)

User: "I need to reproduce this crash in the debugger" → Invoke: See axiom-build (skills/lldb.md)

User: "My list scrolls slowly and memory keeps growing" → See skills/memory-debugging.md first, then skills/performance-profiling.md if stutter remains

User: "App freezes for a few seconds on first launch then works fine" → See skills/hang-diagnostics.md

User: "UI locks up when multiple API calls return at the same time" → Cross-route: /skill axiom-concurrency (callback contention)

User: "My timer stops when the user scrolls" → Read: axiom-integration (skills/timer-patterns.md)

User: "EXC_BAD_INSTRUCTION crash in my timer code" → Read: axiom-integration (skills/timer-patterns.md)

User: "Should I use Timer or DispatchSourceTimer?" → Read: axiom-integration (skills/timer-patterns.md)

User: "How do I create an AsyncTimerSequence?" → Read: axiom-integration (skills/timer-patterns-ref.md)

User: "Review my Swift code for outdated patterns" → Invoke: See axiom-swift (skills/swift-modern.md)

User: "Is there a more modern way to do this?" → Invoke: See axiom-swift (skills/swift-modern.md)

User: "What is the app logging? I need to see console output" → Invoke: /axiom-console

User: "Capture the simulator logs while I reproduce this bug" → Invoke: /axiom-console