axiom-hang-diagnostics

# Hang Diagnostics

Systematic diagnosis and resolution of app hangs. A hang occurs when the main thread is blocked for more than 1 second, making the app unresponsive to user input.

## Red Flags — Check This Skill When

| Symptom | This Skill Applies |
|---------|-------------------|
| App freezes briefly during use | Yes — likely hang |
| UI doesn't respond to touches | Yes — main thread blocked |
| "App not responding" system dialog | Yes — severe hang |
| Xcode Organizer shows hang diagnostics | Yes — field hang reports |
| MetricKit MXHangDiagnostic received | Yes — aggregated hang data |
| Animations stutter or skip | Maybe — could be hitch, not hang |
| App feels slow but responsive | No — performance issue, not hang |

## What Is a Hang

A **hang** is when the main runloop cannot process events for more than 1 second. The user taps, but nothing happens.

```
User taps → Main thread busy/blocked → Event queued → 1+ second delay → HANG
```

**Key distinction**: The main thread handles ALL user input. If it's busy or blocked, the entire UI freezes.

### Hang vs Hitch vs Lag

| Issue | Duration | User Experience | Tool |
|-------|----------|-----------------|------|
| **Hang** | >1 second | App frozen, unresponsive | Time Profiler, System Trace |
| **Hitch** | 1-3 frames (16-50ms) | Animation stutters | Animation Hitches instrument |
| **Lag** | 100-500ms | Feels slow but responsive | Time Profiler |

**This skill covers hangs.** For hitches, see `axiom-swiftui-performance`. For general lag, see `axiom-performance-profiling`.

## The Two Causes of Hangs

Every hang has one of two root causes:

### 1. Main Thread Busy

The main thread is doing work instead of processing events.

**Subcategories**:

| Type | Example | Fix |
|------|---------|-----|
| **Proactive work** | Pre-computing data user hasn't requested | Lazy initialization, compute on demand |
| **Irrelevant work** | Processing all notifications, not just relevant ones | Filter notifications, targeted o