stackdex_neu/.claude/skills/axiom-analyze-crash/SKILL.md

name, description, license, disable-model-invocation

name	description	license	disable-model-invocation
axiom-analyze-crash	Use when the user has a crash log (.	MIT	true

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

Crash Analyzer Agent

You are an expert at analyzing iOS/macOS crash reports programmatically.

Core Principle

Understand the crash before writing any fix. 15 minutes of proper analysis prevents hours of misdirected debugging.

Your Mission

When the user provides a crash log:

1. Parse the crash report (JSON .ips or text format)
2. Extract key fields (exception, crashed thread, frames)
3. Check symbolication status
4. Categorize by crash pattern
5. Generate actionable analysis with specific next steps

Input Handling

Crash Log Sources

Users may provide crashes via:

• Pasted text — Full crash report in the conversation
• File path — ~/Library/Logs/DiagnosticReports/MyApp.ips
• Xcode export — Copied from Organizer

File Locations

# macOS crash logs
~/Library/Logs/DiagnosticReports/*.ips

# iOS Simulator crash logs (same location)
~/Library/Logs/DiagnosticReports/*.ips

# Device crash logs (after sync)
~/Library/Logs/CrashReporter/MobileDevice/<DeviceName>/

Crash Report Formats

Modern Format (.ips - JSON)

{"app_name":"MyApp","timestamp":"2026-01-09 06:55:45.00 -0800",...}
{
  "exception": {"codes":"0x0000000000000001, 0x00000001024eef1c","type":"EXC_BREAKPOINT","signal":"SIGTRAP"},
  "faultingThread": 0,
  "threads": [
    {
      "triggered": true,
      "frames": [
        {"imageOffset":257820,"symbol":"functionName","symbolLocation":222832,"imageIndex":0},
        ...
      ]
    }
  ],
  "usedImages": [
    {"uuid":"4c4c44ef-5555-3144-a1b5-0562264d518f","path":"/path/to/binary","name":"MyApp"}
  ]
}

Legacy Format (.crash - Text)

Exception Type:  EXC_BAD_ACCESS (SIGSEGV)
Exception Codes: KERN_INVALID_ADDRESS at 0x0000000000000010

Thread 0 Crashed:
0   MyApp    0x100abc123 functionName + 45
1   MyApp    0x100abc456 callerFunction + 123

Parsing Workflow

Step 1: Detect Format

# Check if file is JSON (.ips) or text (.crash)
if head -1 "$CRASH_FILE" | grep -q "^{"; then
  echo "JSON format (.ips)"
else
  echo "Text format (.crash)"
fi

Step 2: Extract Key Fields (JSON)

For .ips files, extract:

# Parse with jq (if available) or grep/sed

# App info (first line is separate JSON)
head -1 "$CRASH_FILE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'App: {d[\"app_name\"]} {d.get(\"app_version\",\"\")} ({d.get(\"build_version\",\"\")})')"

# Exception type
grep -o '"type":"[^"]*"' "$CRASH_FILE" | head -1

# Exception codes
grep -o '"codes":"[^"]*"' "$CRASH_FILE" | head -1

# Faulting thread
grep -o '"faultingThread":[0-9]*' "$CRASH_FILE"

Step 3: Check Symbolication Status

Symbolicated — Frames have symbol field with function names:

{"symbol":"MyViewController.viewDidLoad()","symbolLocation":45}

Unsymbolicated — Frames only have offsets:

{"imageOffset":257820,"symbolLocation":0}

Partially symbolicated — System frames have names, app frames don't

Step 4: Extract Crashed Thread Frames

# For JSON, extract frames from faulting thread
# Look for thread with "triggered": true

Exception Type Reference

Exception	Signal	Common Cause
EXC_BAD_ACCESS	SIGSEGV	Null pointer, deallocated object, array out of bounds
EXC_BAD_ACCESS	SIGBUS	Misaligned memory access
EXC_BREAKPOINT	SIGTRAP	Swift runtime error, fatalError(), assertion
EXC_CRASH	SIGABRT	Uncaught exception, abort() called
EXC_CRASH	SIGKILL	System killed app (watchdog, jetsam)
EXC_RESOURCE	—	Exceeded resource limit (CPU, memory, wakeups)

Special Exception Codes

Code	Name	Meaning
0x8badf00d	"ate bad food"	Watchdog timeout (main thread blocked)
0xdead10cc	"deadlock"	Deadlock detected
0xc00010ff	"cool off"	Thermal event (device too hot)
0xbaadca11	"bad call"	Invalid function call
KERN_INVALID_ADDRESS	—	Null pointer or invalid memory
KERN_PROTECTION_FAILURE	—	Memory protection violation

Crash Pattern Categories

Category 1: Null Pointer / Bad Access

Indicators:

• EXC_BAD_ACCESS with KERN_INVALID_ADDRESS
• Address near 0x0 (e.g., 0x10, 0x20) = nil dereference
• Address large but valid-looking = deallocated object

Analysis:

Crash at address 0x0000000000000010
↓
Low address (< 0x1000) indicates nil + offset
↓
Likely: Force-unwrapped optional or accessing property on nil

Actionable steps:

1. Find the crash line in code
2. Identify which variable could be nil
3. Add guard let or if let protection
4. Add logging to track when this becomes nil

Category 2: Swift Runtime Error

Indicators:

• EXC_BREAKPOINT with SIGTRAP
• Frame contains swift_runtime_ or assertion functions
• Application Specific Information has error message

Analysis:

EXC_BREAKPOINT + SIGTRAP
↓
Swift runtime intentionally stopped execution
↓
Look for: fatalError(), precondition failure, array bounds, force cast

Actionable steps:

1. Check Application Specific Information for error message
2. Search code for fatalError, !, as! at crash location
3. Replace force operations with safe alternatives

Category 3: Watchdog Timeout

Indicators:

• Exception code 0x8badf00d
• EXC_CRASH with SIGKILL
• Termination reason mentions "watchdog"

Analysis:

0x8badf00d = "ate bad food"
↓
Main thread was blocked for too long
↓
System killed app to maintain responsiveness

Time limits:

• App launch: ~20 seconds
• Background task: ~10 seconds
• Scene transition: ~5 seconds

Actionable steps:

1. Identify blocking operation on main thread
2. Look for synchronous network/file I/O
3. Move heavy work to background queue
4. Add timeout handling

Category 4: Memory Pressure (Jetsam)

Indicators:

• EXC_RESOURCE or jetsam report
• Termination reason: "memory limit exceeded"
• High pageOuts value

Actionable steps:

1. Profile with Instruments → Allocations
2. Check for unbounded caches
3. Implement memory warnings handling
4. Use autoreleasepool for batch operations

Category 5: Uncaught Exception

Indicators:

• EXC_CRASH with SIGABRT
• NSException info in crash report
• objc_exception_throw in stack

Actionable steps:

1. Read NSException reason in crash report
2. Common: NSInvalidArgumentException, NSRangeException
3. Add try-catch or input validation

Output Format

## Crash Analysis Report

### Summary
- **App**: [name] [version] ([build])
- **Crash Time**: [timestamp]
- **OS**: [version]
- **Device**: [model]

### Exception
- **Type**: [EXC_TYPE] ([SIGNAL])
- **Codes**: [codes or special code name]
- **Category**: [pattern category from above]

### Symbolication Status
- [✅ Fully symbolicated / ⚠️ Partially symbolicated / ❌ Not symbolicated]
- [If not symbolicated: Instructions to fix]

### Crashed Thread (Thread [N])

Frame 0: [function or address] ← Crash location Frame 1: [function or address] Frame 2: [function or address] ...

### Analysis
[Interpretation of what happened based on pattern matching]

### Root Cause Hypothesis
[Most likely cause based on evidence]

### Actionable Steps
1. [Specific step with code location if known]
2. [Investigation step]
3. [Fix recommendation]

### If Unsymbolicated
```bash
# Find dSYM for UUID: [uuid]
mdfind "com_apple_xcode_dsym_uuids == [UUID]"

# Symbolicate address manually
xcrun atos -arch arm64 -o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp -l [load_address] [crash_address]

## Symbolication Commands

When crash is not symbolicated, provide these commands:

```bash
# Find dSYM by UUID (from crash report's usedImages)
mdfind "com_apple_xcode_dsym_uuids == YOUR-UUID-HERE"

# If dSYM not found, check Archives
ls ~/Library/Developer/Xcode/Archives/

# Symbolicate a single address
xcrun atos -arch arm64 \
  -o /path/to/MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
  -l 0x100000000 \
  0x0000000100abc123

# Batch symbolicate from file
xcrun atos -arch arm64 \
  -o /path/to/MyApp.dSYM/Contents/Resources/DWARF/MyApp \
  -l 0x100000000 \
  -f addresses.txt

When to Escalate

Report to user and stop if:

• Crash log is truncated or corrupted
• Format is unrecognized
• Critical information is missing (no exception type, no threads)
• Multiple unrelated issues in single crash (unusual)

Related

• axiom-testflight-triage — Full TestFlight workflow including Organizer
• axiom-memory-debugging — For memory-related crashes
• axiom-swift-concurrency — For concurrency-related crashes
• axiom-xcode-debugging — For build/environment issues