Use when ANY beta tester reports a crash, ANY crash appears in Organizer or App Store Connect, crash logs need symbolication, app was killed without crash report, or you need to triage TestFlight feedback
/plugin marketplace add CharlesWiltgen/Axiom/plugin install axiom@axiom-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Systematic workflow for investigating TestFlight crashes and reviewing beta feedback using Xcode Organizer. Core principle: Understand the crash before writing any fix — 15 minutes of triage prevents hours of debugging.
0x100abc123) → Go to Symbolication WorkflowNot all terminations produce crash reports. Check for:
pageOuts value0x8badf00d ("ate bad food")→ See Terminations Without Crash Reports
→ See Feedback Triage Workflow
Window → Organizer (or ⌘⇧O from Xcode)
┌─────────────────────────────────────────────────────────────────┐
│ [Toolbar: Time Period ▼] [Version ▼] [Product ▼] [Release ▼] │
├──────────┬──────────────────────────┬───────────────────────────┤
│ Sidebar │ Crashes List │ Inspector │
│ │ │ │
│ • Crashes│ ┌─────────────────────┐ │ Distribution Graph │
│ • Energy │ │ syncFavorites crash │ │ ┌─────────────────────┐ │
│ • Hang │ │ 21 devices • 7 today│ │ │ ▄ ▄▄▄ v2.0 │ │
│ • Disk │ └─────────────────────┘ │ │ ▄▄▄▄▄ v2.0.1 │ │
│ Feedback │ ┌─────────────────────┐ │ └─────────────────────┘ │
│ │ │ Another crash... │ │ │
│ │ └─────────────────────┘ │ Device Distribution │
│ │ │ OS Distribution │
│ ├──────────────────────────┤ │
│ │ Log View │ [Feedback Inspector] │
│ │ (simplified crash view) │ Shows tester feedback │
│ │ │ for selected crash │
└──────────┴──────────────────────────┴───────────────────────────┘
| Feature | What It Does |
|---|---|
| Speedy Delivery | TestFlight crashes delivered moments after occurrence (not daily) |
| Year of History | Filter crashes by time period, see monthly trends |
| Product Filter | Filter by App Clip, watch app, extensions, or main app |
| Version Filter | Drill down to specific builds |
| Release Filter | Separate TestFlight vs App Store crashes |
| Share Button | Share crash link with team members |
| Feedback Inspector | See tester comments for selected crash |
Crashes in the list show badges indicating origin:
| Badge | Meaning |
|---|---|
| App Clip | Crash from your App Clip |
| Watch | Crash from watchOS companion |
| Extension | Crash from share extension, widget, etc. |
| (none) | Main iOS app |
Before diving into code, ask yourself these questions (from WWDC):
→ Check the inspector's graph area on the right → Graph legend shows which versions are affected → Look for when the crash first appeared
→ Use the Release filter in toolbar → Select "Release" to see App Store crashes only → Select "TestFlight" for beta crashes only
→ Open the Feedback Inspector (right panel) → Check for tester comments describing their actions → Context clues: network state, battery level, disk space
When a crash has associated TestFlight feedback, you'll see a feedback icon in the crashes list. Click it to open the Feedback Inspector.
Each feedback entry shows:
| Field | Why It Matters |
|---|---|
| Version/Build | Confirms exact build tester was running |
| Device model | Device-specific crashes (older devices, specific screen sizes) |
| Battery level | Low battery can affect app behavior |
| Available disk | Low disk can cause write failures |
| Network type | Cellular vs WiFi, connectivity issues |
| Tester comment | Their description of what happened |
Example insight from WWDC: A tester commented "I was going through a tunnel and hit the favorite button. A few seconds later, it crashed." This revealed a network timeout issue — the crash occurred because a 10-second timeout was too short for poor network conditions.
Crash reports show raw memory addresses until matched with dSYM files (debug symbol files). Xcode handles this automatically when:
In Organizer, look at the stack trace:
| What You See | Status |
|---|---|
0x0000000100abc123 | Unsymbolicated — needs dSYM |
MyApp.ViewController.viewDidLoad() + 45 | Symbolicated — ready to analyze |
| System frames symbolicated, app frames not | Partially symbolicated — missing your dSYM |
If automatic symbolication failed:
# 1. Find the crash's build UUID (shown in crash report header)
# Look for "Binary Images" section, find your app's UUID
# 2. Find matching dSYM
mdfind "com_apple_xcode_dsym_uuids == YOUR-UUID-HERE"
# 3. If not found, check Archives
ls ~/Library/Developer/Xcode/Archives/
# 4. Symbolicate a specific address
xcrun atos -arch arm64 \
-o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
-l 0x100000000 \
0x0000000100abc123
| Symptom | Cause | Fix |
|---|---|---|
| System frames OK, app frames hex | Missing dSYM for your app | Find dSYM in Archives folder, or re-archive with symbols |
| Nothing symbolicated | UUID mismatch between crash and dSYM | Verify UUIDs match; rebuild exact same commit |
| "No such file" from atos | dSYM not in Spotlight index | Run mdimport /path/to/MyApp.dSYM |
| Can't find dSYM anywhere | Archived without symbols | Enable "Debug Information Format = DWARF with dSYM" in build settings |
# Verify dSYM exists after archive
ls ~/Library/Developer/Xcode/Archives/YYYY-MM-DD/MyApp*.xcarchive/dSYMs/
# Verify UUID matches
dwarfdump --uuid MyApp.app.dSYM
| Field | What It Tells You |
|---|---|
| Exception Type | Category of crash (EXC_BAD_ACCESS, EXC_CRASH, etc.) |
| Exception Codes | Specific error (KERN_INVALID_ADDRESS = null pointer) |
| Termination Reason | Why the system killed the process |
| Crashed Thread | Which thread died (Thread 0 = main thread) |
| Application Specific Information | Often contains the actual error message |
| Binary Images | Loaded frameworks (helps identify third-party culprits) |
The crashed thread's stack trace reads top to bottom:
Thread 0 Crashed:
0 libsystem_kernel.dylib __pthread_kill + 8 ← System code
1 libsystem_pthread.dylib pthread_kill + 288 ← System code
2 libsystem_c.dylib abort + 128 ← System code
3 MyApp ViewController.loadData() ← YOUR CODE (start here)
4 MyApp ViewController.viewDidLoad()
5 UIKitCore -[UIViewController _loadView]
Start at frame 3 — the first frame in your code. Work down to understand the call chain.
Exception Type: EXC_BAD_ACCESS (SIGSEGV)
Exception Codes: KERN_INVALID_ADDRESS at 0x0000000000000010
Thread 0 Crashed:
0 MyApp 0x100abc123 UserManager.currentUser.getter + 45
1 MyApp 0x100abc456 ProfileViewController.viewDidLoad() + 123
2 UIKitCore 0x1a2b3c4d5 -[UIViewController loadView] + 89
Translation:
EXC_BAD_ACCESS with KERN_INVALID_ADDRESS = Tried to access invalid memory0x10 = Very low address, almost certainly nil dereferencecurrentUser.getter = Accessing a property that was nilProfileViewController.viewDidLoad() = During view setupLikely cause: Force-unwrapping an optional that was nil, or accessing a deallocated object.
What it means: Accessed memory that doesn't belong to you.
Common causes in Swift:
| Pattern | Example | Fix |
|---|---|---|
| Force-unwrap nil | user!.name | Use guard let or if let |
| Deallocated object | Accessing self in escaped closure after dealloc | Use [weak self] |
| Array out of bounds | array[index] where index >= count | Check bounds first |
| Uninitialized pointer | C interop with bad pointer | Validate pointer before use |
// Before (crashes if user is nil)
let name = user!.name
// After (safe)
guard let user = user else {
logger.warning("User was nil in ProfileViewController")
return
}
let name = user.name
What it means: App deliberately terminated itself.
Common causes:
| Pattern | Clue in Crash Report |
|---|---|
fatalError() / preconditionFailure() | Your assertion message in Application Specific Info |
| Uncaught Objective-C exception | NSException type and reason in report |
| Swift runtime error | "Fatal error: ..." message |
| Deadlock detected | dispatch_sync onto current queue |
Debug tip: Look at "Application Specific Information" section — it usually contains the actual error message.
What it means: Main thread was blocked too long and the system killed your app.
Time limits:
| Context | Limit |
|---|---|
| App launch | ~20 seconds |
| Background task | ~10 seconds |
| App going to background | ~5 seconds |
Common causes:
// Before (blocks main thread — will trigger watchdog)
let data = try Data(contentsOf: largeFileURL)
processData(data)
// After (offload to background)
Task.detached {
let data = try Data(contentsOf: largeFileURL)
await MainActor.run {
self.processData(data)
}
}
What it means: System terminated your app to free memory. No crash report — just gone.
Symptoms:
pageOuts value in reportInvestigation:
Common fixes:
autoreleasepool for batch processingWhen users report "the app just closed" but you find no crash:
The Terminations Organizer (separate from Crashes) shows trends of app terminations that aren't programming crashes:
Window → Organizer → Terminations (in sidebar)
| Termination Category | What It Means |
|---|---|
| Launch timeout | App took too long to launch |
| Memory limit | Hit system memory ceiling |
| CPU limit (background) | Too much CPU while backgrounded |
| Background task timeout | Background task exceeded time limit |
Key insight: Compare termination rates against previous versions to find regressions. A spike in memory terminations after a release indicates a memory leak or increased footprint.
Apps can be terminated in background for:
If no reports exist:
MetricKit crash diagnostics are now delivered on the next app launch (not aggregated daily). This gives you faster access to crash data.
import MetricKit
class MetricsManager: NSObject, MXMetricManagerSubscriber {
static let shared = MetricsManager()
func startListening() {
MXMetricManager.shared.add(self)
}
func didReceive(_ payloads: [MXMetricPayload]) {
// Process performance metrics
}
func didReceive(_ payloads: [MXDiagnosticPayload]) {
for payload in payloads {
// Crash diagnostics — delivered on next launch
if let crashDiagnostics = payload.crashDiagnostics {
for crash in crashDiagnostics {
// Process crash diagnostic
print("Crash: \(crash.callStackTree)")
}
}
// Hang diagnostics
if let hangDiagnostics = payload.hangDiagnostics {
for hang in hangDiagnostics {
print("Hang duration: \(hang.hangDuration)")
}
}
}
}
}
When to use MetricKit vs Organizer:
| Use Case | Tool |
|---|---|
| Quick triage of TestFlight crashes | Organizer (faster, visual) |
| Programmatic crash analysis | MetricKit |
| Custom crash reporting integration | MetricKit |
| Termination trends across versions | Terminations Organizer |
Basic interpretation:
Here's a crash report from my iOS app. Help me understand:
1. What type of crash is this?
2. Where in my code did it crash?
3. What's the likely cause?
[paste full crash report]
With context (better results):
My TestFlight app crashed. Here's what I know:
- User was [describe action, e.g., "tapping the save button"]
- iOS version: [from crash report]
- Device: [from crash report]
Crash report:
[paste full crash report]
The relevant code is in [file/class name]. Help me understand the cause.
| Include | Why |
|---|---|
| Full crash report | Partial reports lose context |
| What user was doing | Helps narrow down code paths |
| Relevant code snippets | If you know the crash area |
| iOS version and device | Some crashes are device/OS specific |
Xcode Organizer (recommended): Window → Organizer → Select app → Feedback tab
App Store Connect: My Apps → [App] → TestFlight → Feedback
| Component | Description |
|---|---|
| Screenshot | What the user saw (often the most valuable part) |
| Text comment | User's description of the issue |
| Device/OS | iPhone model and iOS version |
| App version | Which TestFlight build |
| Timestamp | When submitted |
| Category | Action |
|---|---|
| 🐛 Bug | Investigate, file issue, prioritize fix |
| 💡 Feature request | Add to backlog if valuable |
| ❓ Unclear | Can't act without more context |
| ✅ Working as intended | May indicate UX confusion |
If feedback is unclear and the tester is reachable:
Pressure: Important stakeholder, no evidence, tempted to dismiss with "works for me"
Correct approach:
Response template:
"I've checked our crash reports and don't see crashes matching your description yet. To help investigate: (1) Could you confirm you're running the TestFlight version? (2) What exactly happens — does the app close suddenly, freeze, or show an error? (3) What were you doing right before? This will help me find the issue."
Why this matters: "Works for me" destroys trust. Investigate thoroughly before dismissing.
Pressure: Time pressure, tempted to guess at fix based on code changes
Correct approach:
Why this matters: Rushed guesses often introduce new bugs or miss the real issue. 15 minutes of proper triage prevents hours of misdirected debugging.
Pressure: Tempted to ignore it or make random changes hoping it helps
Correct approach:
func suspectFunction() {
logger.debug("Entering suspectFunction, state: \(debugDescription)")
defer { logger.debug("Exiting suspectFunction") }
// ... existing code ...
}
Why this matters: Understanding beats guessing. Logging beats speculation. It's okay to say "I need more information" rather than shipping a random change.
| Action | Shortcut |
|---|---|
| Open Organizer | ⌘⇧O (from Xcode) |
| Refresh | ⌘R |
| Code | Meaning |
|---|---|
KERN_INVALID_ADDRESS | Null pointer / bad memory access |
KERN_PROTECTION_FAILURE | Memory protection violation |
0x8badf00d | Watchdog timeout (main thread blocked) |
0xdead10cc | Deadlock detected |
0xc00010ff | Thermal event (device too hot) |
| Section | Contains |
|---|---|
| Header | App info, device, OS, date |
| Exception Information | Crash type and codes |
| Termination Reason | Why system killed the process |
| Triggered by Thread | Which thread crashed |
| Application Specific | Error messages, assertions |
| Thread Backtraces | Stack traces for all threads |
| Binary Images | Loaded frameworks and addresses |
WWDC: 2018-414, 2020-10076, 2020-10078, 2020-10081, 2021-10203, 2021-10258
Docs: /xcode/diagnosing-issues-using-crash-reports-and-device-logs, /xcode/examining-the-fields-in-a-crash-report, /xcode/adding-identifiable-symbol-names-to-a-crash-report, /xcode/identifying-the-cause-of-common-crashes, /xcode/identifying-high-memory-use-with-jetsam-event-reports
Skills: axiom-memory-debugging, axiom-xcode-debugging, axiom-swift-concurrency
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.