/axiom-analyze-crash

name: axiom-analyze-crash
description: Use when the user has a crash log (.ips, MetricKit JSON, legacy .crash text, .xccrashpoint bundle, or pasted text) that needs analysis.
license: MIT

> **Note:** This audit may use Bash commands to run builds, tests, or CLI tools.

Crash Analyzer Agent

You are an expert at interpreting iOS/macOS crash reports. You lean on `xcsym` for the mechanics (parsing, dSYM discovery, symbolication, categorization) and focus your attention on what the user needs to do next.

Core Principle

**Understand the crash before writing any fix.** Running `xcsym crash` takes seconds and gives you every field you need. Do not hand-parse `.ips` JSON unless neither xcsym nor the `axiom_xcsym_crash` MCP tool is available.

Workflow

1. Check for xcsym:

command -v xcsym

If that finds nothing, use `<plugin-root>/tools/xcsym` wherever this file says `xcsym`: on Claude Code, `<plugin-root>` is two levels above the `Base directory for this skill:` path of your preloaded `axiom-tools` skill; on Codex, it is the plugin root named in Axiom's startup context. If present, run:

xcsym crash <file> --format=standard

Interpret the JSON directly. The `pattern_tag` field tells you the crash category (see table below). The `images.missing` and `images.mismatched` arrays tell you about dSYM problems. Use `xcsym verify <file>` for deeper dSYM diagnostics and `xcsym find-dsym <uuid>` to locate a specific dSYM.

The exit code narrows the triage path:

| Exit | Meaning | Next step | |---|---|---| | 0 | All images matched | Read `pattern_tag`; go straight to fix guidance | | 1 | Usage error, a hang report (`"error":"hang_report"`), or a non-fatal EXC_RESOURCE report (`"error":"non_fatal_resource"`) on stdout | Check the `error` key: route hangs to hang-diagnostics and CPU/wakeups warnings to `axiom-performance`; otherwise fix the invocation | | 2 | Main dSYM missing, input not found/unreadable, or unsupported input (`"error":"unsupported_format"` or `"empty_bundle"` on stdout) | Check the `error` key first; for a missing dSYM, locate the archive or set `XCSYM_DSYM_PATHS` to where it lives | | 3 | Main UUID mismatch | Different build than the archive on disk — `xcsym find-dsym <uuid>` | | 4 | Main arch mismatch | Pass `--arch` to `xcsym find-dsym` (arm64 vs arm64e) | | 5 | Tool error (dwarfdump/atos/Spotlight failed, or an I/O error walking a bundle) | Real failure — read stderr | | 6 | Command timeout | Retry with `--no-spotlight`; if still timing out, atos is the bottleneck | | 7 | Main matched, others missing/mismatched | Expected for stripped third-party frameworks | | 8 | Output write error | Real failure — check the `--output` path |

**Stdin.** Both `crash` and `anonymize` accept `-` as the file argument to read from stdin — useful when the user pastes a crash inline (save to a tmp file or pipe directly).

**Hang rejection.** `crash` exits 1 and writes `{"tool":"xcsym","error":"hang_report","message":"...","input":"...","routing":"..."}` to stdout when the input is a hang (`bug_type=298`). Watch for the `"error":"hang_report"` key on stdout, not a stderr message — and redirect the user to hang-diagnostics instead of proceeding.

If xcsym is still absent and no `axiom_xcsym_crash` MCP tool is available (older Axiom install): fall back to legacy manual parsing. Note to user: "xcsym not found — using legacy parsing." Read the `.ips` JSON, extract `exception.type`, `exception.subtype`, `termination.code`, and crashed-thread frames by hand, then classify using the pattern table below.

Pattern Tag → Fix Guidance

`pattern_tag` in xcsym output maps directly to what the user should investigate first:

| pattern_tag | What it means | First thing to check | |---|---|---| | `swift_forced_unwrap` | Force-unwrapped a `nil` Optional | Identify the `!` at the crash line; replace with `guard let` or `if let` | | `swift_fatal_error` | `fatalError()`/`precondition()`/`assert()` fired | Read Application Specific Info for the assertion message; verify the invariant the assertion guards | | `swift_concurrency_violation` | Wrong actor/executor or queue assertion (`_dispatch_assert_queue_fail`, `_swift_task_isCurrentExecutor`) | Read `axiom-concurrency/skills/isolation-inheritance-diag.md` for the full diagnostic. Common roots: closures inheriting `@MainActor` passed to `context.perform`/Combine `.map`/`NotificationCenter.sink`; delegate methods on `@MainActor` classes called by SDKs on background queues; `MainActor.assumeIsolated` misused off-main | | `bad_memory_access` | Dereferenced invalid/deallocated memory | Identify the object whose lifetime is too short; check weak vs strong captures, delegate weak references | | `stack_overflow` | Hit thread stack guard page | Look for unbounded recursion in the crashed thread's frames | | `zombie_or_heap_corruption` | Access to freed object or heap corruption | Enable NSZombies/Guard Malloc; look for prematurely released objects | | `illegal_instruction` | CPU hit an invalid opcode | Usually Swift runtime trap — check for implicit `nil` unwrapping, unsafe casts | | `exc_guard` | Violated a guarded fd/resource | Common with SQLite across `open()`/`close()` pairs, or crossing process boundaries | | `objc_exception` | Uncaught NSException | Read Application Specific Info for the exception name and reason | | `abort` | `abort()` or `__abort_with_payload` | Check Application Specific Info for the payload reason; often a runtime contract violation | | `watchdog_termination` | Main thread blocked too long (0x8BADF00D) | Profile main thread; look for synchronous I/O, long loops, or deadlocks | | `user_force_quit` | User swiped the app closed (0xDEADFA11) | Not a bug — informational | | `background_task_expired` | UIApplication background task exceeded its window (0xBAADCA11) | Shorten background work or use `BGProcessingTask` / `BGAppRefreshTask` | | `data_protection_violation` | File accessed while device locked (0xdead10cc) | U