/axiom-performance

name: axiom-performance
description: Use when an Apple-platform app feels slow, memory grows, battery drains, or ANY performance issue needs diagnosing. Covers memory leaks, profiling, Instruments workflows, retain cycles, optimization.
license: MIT

Performance

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

**Bundled tools on Claude Code:** if `command -v <tool>` finds nothing (hooks off or `--bare`), use `<plugin-root>/tools/<tool>` in place of the bare name; `<plugin-root>` is two levels above this skill's `Base directory for this skill:` path.

<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit --> > **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the > matching Codex skill instead — same procedure, no Claude Code agent required. > > Available: `axiom-analyze-swift-performance`, `axiom-audit-energy`, `axiom-audit-memory`. > > The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run. <!-- AXIOM_AUDITOR_INLINE_END -->

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** → `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-performance`

• 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` (Claude Code only)

• 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** → `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 ref