charleswiltgen 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_runloopvsanr_main_thread_blockacross 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 XCTApplicationLaunchMetricregression test,MXAppLaunchMetricfield 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 trapping with
BUG IN CLIENT OF LIBDISPATCH— EXC_BREAKPOINT (SIGTRAP) on arm64, EXC_BAD_INSTRUCTION on Intel - 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
--timeoutand--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
- 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
- Multiple grouped hang reports from Sentry/ASC (corpus, not single file)? →
axiom-shipping (skills/production-triage.md)+triage-analyzer
- Slowdown when multiple async operations complete at once? → Cross-route to
axiom-concurrency(callback contention, not profiling) - Slow app launch / slow first frame / launch regression / slow after push tap? → app-launch
- Battery drain (know the symptom)? → energy-diag
- Battery drain (need API reference)? → energy-ref
- Battery drain (general)? → energy
- 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)
- Profile with GUI (Instruments)? → performance-profiling
- Profile with CLI (xctrace)? → xctrace-ref
- Run automated profile now? → performance-profiler agent
- General slow/lag? → performance-profiling 14a. Slow GRDB/SQLite queries (EXPLAIN QUERY PLAN, index design, cursors)? → See axiom-data (skills/grdb-performance.md)
- 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? → See axiom-build (skills/lldb.md)
- Need exact LLDB command syntax? → See axiom-build (skills/lldb-ref.md)
- Timer stops during scrolling? → timer-patterns (RunLoop mode)
- EXC_BREAKPOINT (SIGTRAP) crash with DispatchSourceTimer —
BUG IN CLIENT OF LIBDISPATCH? → timer-patterns (4 crash patterns) - Choosing between Timer, DispatchSourceTimer, Combine timer, async timer? → timer-patterns
- Need timer API syntax/lifecycle? → timer-patterns-ref
- Code review for outdated Swift patterns? → swift-modern
- Claude generating legacy APIs (DateFormatter, CGFloat, DispatchQueue)? → swift-modern
- Need to see runtime console output before profiling? → axiom-tools (skills/xclog-ref.md) or
/axiom-console - Have an
.ips, MetricKit, or legacy.crashtext file to symbolicate/triage? → axiom-tools (skills/xcsym-ref.md) or/axiom-analyze-crash
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. |
| "Launch feels slow — I'll trim some startup code" | Launch has 3 phases (pre-main / main→first frame / extended) and a watchdog. app-launch tells you which phase to profile, with measurement hygiene so the number means something. |
| "Launch is fine, it's fast on my phone" | Measure on your oldest supported device with a Release build. app-launch has the full hygiene checklist — newest-device numbers hide the regression. |
| "Resume from the app switcher is slow too" | Resume isn't a launch — never measure it as one. app-launch distinguishes cold/warm/hot/notification and how to reproduce each. |
| "Too many frameworks — I'll just statically link everything" | Static copies the library into every binary that links it (app + each extension), duplicates its global state, and breaks on Obj-C categories without -ObjC. app-launch has the static/dynamic/mergeable tradeoff and the DYLD_PRINT_STATISTICS check that tells you whether pre-main is even your problem. |
| "UI locks up when network requests finish — that's slow" | Multiple callbacks completing at thread contention = concurrency issue. Cross-route to axiom-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-build (skills/lldb.md) has the commands. |
| "I can't see what the app is logging" | xclog captures print() + os_log from the simulator with structured JSON. /axiom-console. |
| "I'll hand-parse this .ips JSON to see the top frame" | xcsym parses, discovers dSYMs, symbolicates, and categorizes in one call — structured JSON with pattern_tag. /axiom-analyze-crash. |
| "I'll just use Timer.scheduledTimer, it's simpler" | Timer stops during scrolling (.default mode), retains its target (leak). timer-patterns has the decision tree. |
| "DispatchSourceTimer crashed but it's intermittent, let's ship" | DispatchSourceTimer has 4 crash patterns that are ALL deterministic. timer-patterns diagnoses which one. |
| "Claude already knows modern Swift" | Claude defaults to pre-5.5 patterns (Date(), CGFloat, filter().count). swift-modern has the correction table. |
| "MetricKit is that old MX delegate API" | The 27 cycle rebuilt it: MetricManager AsyncSequence streams, typed metrics, per-state aggregation. metrickit-ref Part 1 has the new surface. |
| "My field metrics are one blended average, can't tell which screen is slow" | StateReporting splits every metric by app state you define (per-tab, per-experiment). metrickit-ref Part 1. |
| "No single function is hot, so the profile is useless" | Scattered overhead (dynamic dispatch, retain/release, existentials) hides in flame graphs. Top Functions mode merges it. 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" → 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_BREAKPOINT (SIGTRAP) crash in my timer code — BUG IN CLIENT OF LIBDISPATCH"
→ 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