axiom-background-processing-diag

# Background Processing Diagnostics

Symptom-based troubleshooting for background task issues.

**Related skills**: `axiom-background-processing` (patterns, checklists), `axiom-background-processing-ref` (API reference)

---

## Symptom 1: Task Never Runs

Handler never called despite successful `submit()`.

### Quick Diagnosis (5 minutes)

```
Task never runs?
│
├─ Step 1: Check Info.plist (2 min)
│  ├─ BGTaskSchedulerPermittedIdentifiers contains EXACT identifier?
│  │  └─ NO → Add identifier, rebuild
│  ├─ UIBackgroundModes includes "fetch" or "processing"?
│  │  └─ NO → Add required mode
│  └─ Identifiers case-sensitive match code?
│     └─ NO → Fix typo, rebuild
│
├─ Step 2: Check registration timing (2 min)
│  ├─ Registered in didFinishLaunchingWithOptions?
│  │  └─ NO → Move registration before return true
│  └─ Registration before first submit()?
│     └─ NO → Ensure register() precedes submit()
│
└─ Step 3: Check app state (1 min)
   ├─ App swiped away from App Switcher?
   │  └─ YES → No background until user opens app
   └─ Background App Refresh disabled in Settings?
      └─ YES → Enable or inform user
```

### Time-Cost Analysis

| Approach | Time | Success Rate |
|----------|------|--------------|
| Check Info.plist + registration | 5 min | 70% (catches most issues) |
| Add console logging | 15 min | 90% |
| LLDB simulate launch | 5 min | 95% (confirms handler works) |
| Random code changes | 2+ hours | Low |

### LLDB Quick Test

Verify handler is correctly registered:

```lldb
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.yourapp.refresh"]
```

If breakpoint hits → Registration correct, issue is scheduling/system factors.
If nothing happens → Registration broken.

---

## Symptom 2: Task Terminates Unexpectedly

Handler called but work doesn't complete before termination.

### Quick Diagnosis (5 minutes)

```
Task terminates early?
│
├─ Step 1: Check expiration handler (1 min)
│  ├─ Expiration handl