@tyroneross/build-loop 0.30.3

package/skills/debugging-memory/references/incident-documentation.md

@@ -0,0 +1,280 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Incident Documentation Guide
+
+Complete guide to documenting debugging incidents for effective future retrieval.
+
+## Incident Structure
+
+Each incident contains these fields:
+
+### Identification
+
+```json
+{
+  "incident_id": "INC_20241225_143052_abc1",
+  "timestamp": 1735135852000,
+  "session_id": "SESSION_1735135800000_xyz"
+}
+```
+
+- **incident_id**: Auto-generated, format `INC_YYYYMMDD_HHMMSS_random`
+- **timestamp**: Unix timestamp of when incident was stored
+- **session_id**: Links to the debugging session that produced this fix
+
+### Symptom
+
+```json
+{
+  "symptom": "Search results not displaying after typing in the search box",
+  "symptom_type": "ui"
+}
+```
+
+- **symptom**: User-facing description of what went wrong
+- **symptom_type**: Category (ui, api, logic, crash, performance, build)
+
+**Writing effective symptoms:**
+- Describe observable behavior
+- Include context (what action triggered it)
+- Avoid implementation details
+- Keep it searchable
+
+### Root Cause
+
+```json
+{
+  "root_cause": {
+    "description": "The debounce hook was resetting the search query on every keystroke because the dependency array included a reference-unstable callback. Each render created a new callback reference, triggering the debounce reset.",
+    "file": "src/hooks/useDebounce.ts",
+    "line_range": [15, 28],
+    "code_snippet": "const debouncedValue = useMemo(() => {...}, [value, callback])",
+    "category": "react-hooks",
+    "confidence": 0.95
+  }
+}
+```
+
+- **description**: Detailed technical explanation (minimum 50 characters)
+- **file**: Primary file where the bug existed
+- **line_range**: Affected line numbers
+- **code_snippet**: Relevant code (helps future matching)
+- **category**: Technical category (react-hooks, api, config, dependency, logic)
+- **confidence**: How certain the diagnosis is (0.0-1.0)
+
+**Root cause quality checklist:**
+- Explains WHY the bug occurred, not just WHERE
+- Includes enough detail to understand without reading the code
+- References specific code patterns or concepts
+- Assigns appropriate confidence based on certainty
+
+### Fix
+
+```json
+{
+  "fix": {
+    "approach": "Wrapped the callback in useCallback to stabilize the reference, then updated the debounce hook's dependency array to only include the memoized callback.",
+    "changes": [
+      {
+        "file": "src/hooks/useDebounce.ts",
+        "lines_changed": 8,
+        "change_type": "modify",
+        "summary": "Added useCallback wrapper and updated dependencies"
+      },
+      {
+        "file": "src/components/SearchBar.tsx",
+        "lines_changed": 3,
+        "change_type": "modify",
+        "summary": "Memoized the search handler callback"
+      }
+    ],
+    "pattern_used": null,
+    "time_to_fix": 25
+  }
+}
+```
+
+- **approach**: High-level description of the solution
+- **changes**: Array of file changes with details
+- **pattern_used**: Pattern ID if an existing pattern was applied
+- **time_to_fix**: Minutes spent (helps estimate similar bugs)
+
+### Verification
+
+```json
+{
+  "verification": {
+    "status": "verified",
+    "regression_tests_passed": true,
+    "user_journey_tested": true,
+    "tests_run": ["search.test.ts", "debounce.test.ts"],
+    "success_criteria_met": true
+  }
+}
+```
+
+- **status**: verified | partial | unverified
+- **regression_tests_passed**: Existing tests still pass
+- **user_journey_tested**: Manual testing of the affected feature
+- **tests_run**: Specific test files executed
+- **success_criteria_met**: Bug no longer reproducible
+
+### Quality Gates
+
+```json
+{
+  "quality_gates": {
+    "guardian_validated": true,
+    "tested_e2e": false,
+    "tested_from_ui": true,
+    "security_reviewed": false,
+    "architect_reviewed": false
+  }
+}
+```
+
+Optional validation checkpoints for higher-stakes fixes.
+
+### Tags
+
+```json
+{
+  "tags": ["react", "hooks", "useMemo", "debounce", "search"],
+  "files_changed": ["src/hooks/useDebounce.ts", "src/components/SearchBar.tsx"],
+  "agent_used": "coder"
+}
+```
+
+- **tags**: Searchable keywords for categorization
+- **files_changed**: All modified files
+- **agent_used**: Which Claude agent fixed this
+
+## Quality Scoring
+
+The memory system calculates a quality score (0-100%) based on:
+
+| Component | Weight | Criteria |
+|-----------|--------|----------|
+| Root Cause | 30% | Description length, confidence, file reference |
+| Fix | 30% | Approach detail, change documentation |
+| Verification | 20% | Status, tests run, criteria met |
+| Documentation | 20% | Tags, files listed, agent noted |
+
+**Quality targets:**
+- 75%+: Excellent - highly reliable for future matching
+- 50-74%: Good - useful but may need verification
+- <50%: Fair - stored but lower priority in results
+
+## How Claude Code Stores Incidents
+
+Claude Code should **directly write JSON files** to store incidents. No CLI command needed.
+
+### Step-by-Step
+
+**1. Create directory (if needed):**
+```bash
+mkdir -p .claude/memory/incidents
+```
+
+**2. Generate incident ID:**
+```
+INC_YYYYMMDD_HHMMSS_xxxx
+```
+Example: `INC_20241231_143052_a7b2` where:
+- `20241231` = date (Dec 31, 2024)
+- `143052` = time (14:30:52)
+- `a7b2` = 4 random alphanumeric chars
+
+**3. Write JSON file:**
+```
+.claude/memory/incidents/INC_20241231_143052_a7b2.json
+```
+
+**4. Include required fields:**
+```json
+{
+  "incident_id": "INC_20241231_143052_a7b2",
+  "timestamp": 1735654252000,
+  "symptom": "Description of the bug",
+  "root_cause": {
+    "description": "Technical explanation",
+    "file": "path/to/file.ts",
+    "category": "logic",
+    "confidence": 0.85
+  },
+  "fix": {
+    "approach": "How it was fixed",
+    "changes": []
+  },
+  "tags": ["searchable", "keywords"],
+  "quality_score": 0.75
+}
+```
+
+### When to Store
+
+- **After fixing a bug** - Immediately document while context is fresh
+- **After debugging session** - Even if fix wasn't found, document the investigation
+- **After pattern identified** - If you notice recurring issues
+
+### Workflow Example
+
+```
+1. Bug reported: "Search not working"
+2. Search memory via `debugger search` MCP tool: "search not working"
+3. Found match? → Apply fix
+   No match? → Investigate and fix
+4. Store via `debugger store` MCP tool (or write JSON to .claude/memory/incidents/INC_xxx.json)
+5. Future searches will find this incident
+```
+
+## Storage Modes
+
+### Local Mode (default)
+
+Incidents stored in project's `.claude/memory/incidents/`:
+- Project-specific context
+- Doesn't pollute other projects
+- Best for project-specific bugs
+
+### Shared Mode
+
+Incidents stored in `.build-loop/issues/`:
+- Cross-project learning
+- Common patterns accessible everywhere
+- Best for reusable solutions
+
+Set via environment:
+```bash
+export CLAUDE_MEMORY_MODE=shared
+```
+
+## Retrieval Strategy
+
+When searching for matches, the system:
+
+1. **Pattern match first** (90% confidence threshold)
+2. **Incident search** (70% confidence threshold)
+3. **Keyword similarity** using Jaccard scoring
+4. **Temporal weighting** - prefer recent incidents (90-day window)
+
+Higher quality incidents rank higher in results.
+
+## Interactive Documentation
+
+Use interactive mode for guided documentation:
+
+```typescript
+import { storeIncident } from '<coding-debugger-package>';
+
+await storeIncident(incident, {
+  interactive: true,
+  validate_schema: true
+});
+```
+
+The system prompts for:
+- Missing required fields
+- Short descriptions that need expansion
+- Verification status confirmation
+- Tag suggestions based on symptom

package/skills/debugging-memory/references/ios-notification-alarm-playbook.md

@@ -0,0 +1,300 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# iOS Notification / Alarm Diagnostic Playbook
+
+Domain reference for diagnosing "the alarm doesn't fire" on iOS apps that use `UNUserNotificationCenter` for timed completion alerts (Pomodoro timers, meditation apps, fasting trackers, sleep alarms, anything with a scheduled future notification).
+
+Source: build-loop run on a sample timer app (2026-04-26). Single high-confidence root cause; the playbook generalizes the diagnostic moves.
+
+## Smoking-gun pattern
+
+> Notification scheduled ONLY at background transition + unconditionally cancelled on every foreground return.
+
+If the codebase has both of these, several normal user flows leave nothing armed. Before doing anything else, search for these two patterns; if both exist, you have your root cause in under 60 seconds.
+
+```bash
+grep -n "scheduleTimedNotification\|scheduleCompletion" --include="*.swift" -r .
+grep -n "removeAllPendingNotificationRequests\|cancelScheduled" --include="*.swift" -r .
+```
+
+If schedule sites are inside `applicationDidEnterBackground`, `scenePhase == .background`, or a single `handleBackgroundTransition`, **and** cancel sites run on every foreground return without checking timer state, file the finding as `KNOWN_FIX` against `INC_IOS_ALARM_SCHEDULE_TIMING`.
+
+## Hypothesis tree (8 priorities)
+
+When the smoking-gun pattern doesn't apply, descend in this order. Stop at the first confirmed cause.
+
+1. **Schedule timing** — Where is `UNUserNotificationCenterAdd` actually called? If the only call site is a background-transition hook, force-quit / fast suspend / foreground-only sessions never arm.
+2. **Foreground cancel** — Is `removePendingNotificationRequests` called unconditionally on foreground? After fixing #1, this is the new bug.
+3. **Authorization timing** — When is `requestAuthorization` invoked? If "after first completion," the first session runs unauthorized and silently fails to deliver.
+4. **Identifier collisions** — Are multiple call sites adding requests with different UUIDs? Cancellation by-identifier won't catch them; the OS may dedupe or the app may leak pending requests.
+5. **Trigger interval** — Is `timeInterval` ever 0 or negative (clock skew, timer overshoot)? `UNTimeIntervalNotificationTrigger` requires `> 0`.
+6. **Sound asset path** — Is the chime asset actually copied into `Bundle.main`? `UNNotificationSound(named:)` silently falls back to no sound if the file isn't found.
+7. **Delegate registration** — Is `UNUserNotificationCenter.current().delegate` set, and does `willPresent` return `[.banner, .sound]`? If not, foreground delivery is invisible.
+8. **Interruption level + Focus** — Is `interruptionLevel = .timeSensitive` set, and is the iOS Time Sensitive entitlement active? Without it, Focus modes suppress the banner.
+
+## Parallel-investigator decomposition
+
+For "alarm doesn't fire," dispatch 3 concurrent investigators. None share state.
+
+| Investigator | Scope | Files / Symbols |
+|---|---|---|
+| **Timer architecture** | Where is the notification scheduled, where is it cancelled, what other paths affect lifetime | `*TimerEngine*.swift`, `*Notification*.swift`, every `scheduleCompletion` / `cancelScheduled*` call site |
+| **Audio + haptic routing** | Foreground completion path, AVAudioSession config, ringer-bypass, CoreHaptics fallbacks | `*AudioService*.swift`, `AudioSessionManager*`, `playChime`, `UINotificationFeedbackGenerator`, `CHHapticEngine` |
+| **Lifecycle + cancel** | scenePhase transitions, app delegate hooks, force-quit handling, ActiveSessionRecovery | `SampleTimerApp+iOS.swift` or `App+iOS.swift`, `applicationWillTerminate`, `scenePhase.onChange`, recovery code |
+
+## Symbol search lists
+
+Run these in any iOS project as a starting cluster.
+
+```bash
+# Notification lifecycle
+grep -rn "UNUserNotificationCenter\|UNTimeIntervalNotificationTrigger\|UNNotificationRequest" --include="*.swift" .
+grep -rn "removePendingNotificationRequests\|removeAllPendingNotificationRequests" --include="*.swift" .
+
+# Authorization
+grep -rn "requestAuthorization\|getNotificationSettings\|UNAuthorizationStatus" --include="*.swift" .
+
+# Foreground completion path
+grep -rn "willPresent\|UNNotificationPresentationOptions\|interruptionLevel" --include="*.swift" .
+
+# Audio routing
+grep -rn "AVAudioSession\|AVAudioPlayer\|AudioServicesPlaySystemSound" --include="*.swift" .
+
+# Haptics
+grep -rn "CHHapticEngine\|UINotificationFeedbackGenerator\|UIImpactFeedbackGenerator" --include="*.swift" .
+
+# Lifecycle
+grep -rn "scenePhase\|applicationDidEnterBackground\|applicationWillTerminate" --include="*.swift" .
+```
+
+## File anti-patterns to flag
+
+Treat the presence of any of these as a high-priority finding.
+
+| Anti-pattern | Where it bites |
+|---|---|
+| `removeAllPendingNotificationRequests()` called outside reset/teardown | Wipes unrelated app notifications, masks identifier mistakes, blocks per-session debugging |
+| Schedule call inside `if scenePhase == .background` only | Force-quit, fast suspend, foreground-only sessions go unarmed |
+| Foreground transition unconditionally calls `cancelScheduledNotifications()` | Lock-then-quick-unlock cancels the alarm while the timer is still running |
+| `requestAuthorization` invoked after first session completion | First session is silent; user-perceived "alarm broken" |
+| `AVAudioPlayer` chime with no fallback to `.default` | Missing or corrupted bundled asset = silent foreground completion |
+| `UNNotificationSound(named: "chime.caf")` without `Bundle.main.url(forResource:withExtension:)` check | Silent fail at delivery time, no log |
+| Single delegate impl on a multi-platform target without `#if os(...)` for `badgeSetting`, `UIImpactFeedbackGenerator`, etc. | watchOS / macOS build breaks; or worse, runtime crashes |
+| `UIBackgroundModes: [audio]` to keep the timer "alive" | App Store rejection; not the fix |
+
+## Verification matrix (15-state iPhone)
+
+Tier the matrix by what each state actually exercises. **Sim-verifiable** runs in `xcrun simctl`; **real-device** needs hardware.
+
+| # | Scenario | Expected | Sim | Device |
+|---|---|---|---|---|
+| 1 | Foreground tick to zero | banner + sound + haptic | sound | haptic |
+| 2 | Background then zero | banner + sound while locked | ✅ | ✅ |
+| 3 | Locked then zero | lock-screen banner + sound | ✅ | ✅ |
+| 4 | Force-quit then zero | banner still fires | ✅ | ✅ |
+| 5 | Pause → resume → zero | fires at new endDate | ✅ | ✅ |
+| 6 | Reset mid-session | no banner | ✅ | ✅ |
+| 7 | Scrub: bg → fg → bg → zero | banner fires once | ✅ | ✅ |
+| 8 | Focus mode allowed | banner fires | ✅ | ✅ |
+| 9 | Focus mode blocked | banner suppressed (expected) | ✅ | ✅ |
+| 10 | Silent switch on | sound through (AVAudioSession.playback) | n/a | device-only |
+| 11 | DND on | banner suppressed unless Critical Alerts | n/a | device-only |
+| 12 | Permissions: notDetermined | first Start triggers prompt | ✅ | ✅ |
+| 13 | Permissions: denied | no banner, no crash, log warns | ✅ | ✅ |
+| 14 | Backgrounded > 90 min | recovery flow | ✅ | ✅ |
+| 15 | Watch session running concurrently | iPhone alarm independent | partial | ✅ |
+
+## Diagnostic logging template
+
+Every iOS notification fix should ship with structured logging on day 1, not as a follow-up. Recommended subsystem and category:
+
+```swift
+import os.log
+
+enum AlertDiagnostics {
+    private static let logger = Logger(
+        subsystem: Bundle.main.bundleIdentifier ?? "com.example",
+        category: "alert-diag"
+    )
+    static func scheduled(identifier: String, afterSeconds: Int, source: String) { /* ... */ }
+    static func cancelled(identifier: String, source: String) { /* ... */ }
+    static func cancelSkipped(reason: String, source: String) { /* ... */ }
+    static func scenePhase(_ phase: String) { /* ... */ }
+    static func dumpAuthSettings() { /* ... */ }
+    static func dumpPendingRequests(reason: String) { /* ... */ }
+}
+```
+
+Filter Console.app on `subsystem:com.example category:alert-diag` to read the trail. The `[alert-diag]` prefix and `id=...` tokens make grep one-shot.
+
+## Verdict templates
+
+When this playbook applies, use one of the following incident IDs.
+
+- `INC_IOS_ALARM_SCHEDULE_TIMING` — schedule call site only at background transition
+- `INC_IOS_ALARM_UNCONDITIONAL_CANCEL` — foreground cancel runs while timer still active
+- `INC_IOS_ALARM_AUTH_LATE` — requestAuthorization after first completion
+- `INC_IOS_ALARM_CHIME_MISSING` — bundled audio asset not in Bundle.main
+- `INC_IOS_ALARM_FOCUS_BLOCKED` — interruption level missing or Focus suppressing
+
+## Confidence
+
+This playbook is built from one canonical incident (sample timer app, 2026-04-26). Promote to "pattern" status (`PTN_IOS_ALARM_*`) once 3+ incidents share the smoking-gun signature.
+
+---
+
+## Multi-alert identifier-set pattern
+
+Added 2026-04-26 (sample timer app build 72) when alert customization landed: count, persistence (re-fire every N seconds), and backup escalation expanded the per-transition notification stack from 1 request to up to ~10. The schedule and cancel paths must agree on the identifier set or the cancel will silently leak requests.
+
+### The bug pattern this prevents
+
+> User changes alert count from 3 to 1 mid-session. Pause cancels with the legacy single-identifier `[timerCompletionIdentifier]`. The other two requests survive. Pomodoro fires three notifications during a paused session — exactly the failure mode persistence+backup were trying to avoid.
+
+The same shape appears whenever a feature changes the cardinality or naming of pending requests (persistence toggles, A/B sound tests, multi-stage celebrations). The cancel path is written first against a smaller cardinality, then someone bumps the cardinality on the schedule side without updating cancel.
+
+### The rule
+
+**Schedule and cancel must call a single identifier-set generator function, parameterized by the same inputs.** Any feature that adds requests to a session bumps the cardinality through that one function, and both sides update for free.
+
+```swift
+static func pomodoroNotificationIdentifiers(sessionTag: String, config: AlertConfig) -> [String] {
+    var ids: [String] = [timerCompletionIdentifier] // legacy single id, always cleared
+    let prefix = "\(timerCompletionIdentifier).tag.\(sessionTag)"
+    for i in 0..<max(1, min(3, config.count)) {
+        ids.append("\(prefix).alert.\(i)")
+    }
+    if config.persistenceEnabled {
+        let n = min(6, max(0, config.persistenceMaxSec / max(15, config.persistenceIntervalSec)))
+        for j in 0..<n { ids.append("\(prefix).persist.\(j)") }
+    }
+    return ids
+}
+```
+
+`scheduleCompletion(...)` calls this and adds requests under each id. `cancelScheduledCompletion(config:sessionTag:source:)` calls the same function and passes the array to `removePendingNotificationRequests(withIdentifiers:)`. The legacy bare identifier stays in the set forever so a clean upgrade absorbs any in-flight build-71 request.
+
+### Caller responsibility
+
+The caller (TimerEngine) remembers `armedSessionTag` and `armedConfig` at schedule time and passes them back at cancel time:
+
+```swift
+private func armCompletionStack(...) {
+    let config = alertSettings.config(forBreak: forBreak)
+    let tag = currentSessionTag(forBreak: forBreak)
+    armedSessionTag = tag
+    armedConfig = config
+    delegate?.scheduleTimedNotificationWithConfig(..., config: config, sessionTag: tag, ...)
+}
+
+private func cancelCompletionStack(source: String) {
+    if let tag = armedSessionTag, let config = armedConfig {
+        delegate?.cancelScheduledNotificationsWithConfig(config: config, sessionTag: tag, source: source)
+    } else {
+        delegate?.cancelScheduledNotifications(source: source) // legacy fallback
+    }
+    armedSessionTag = nil
+    armedConfig = nil
+}
+```
+
+`sessionTag` is derived from `phaseStartDate` so re-arming during a phase keeps the same tag (idempotent replace), but a new phase gets a fresh tag (so the prior phase's stack is not accidentally cancelled by a subsequent cancel call).
+
+### Diagnostics
+
+Log the full identifier list, not the count alone, on every schedule and cancel. `[alert-diag] schedule-stack ids=[a,b,c,...] cfg-count=3 persist=true` is greppable; "scheduled 3 notifications" is not.
+
+### Smoking gun for the bug
+
+`getPendingNotificationRequests` returns N entries after a "cancel everything" lifecycle hook (pause, reset, foreground-not-running). The fix is always: route the cancel through the same generator the schedule used.
+
+---
+
+## iOS Local Network discovery checklist
+
+Added 2026-04-26 (sample timer app build 72) when "Listener failed: NWError -65569 DefunctConnection" appeared in Profile → Nearby Devices. iOS Local Network has three independent failure modes; check them in this order.
+
+### 1. Plist stack (one-time setup, easy to forget)
+
+```xml
+<!-- Info.plist for iOS, INFOPLIST_KEY_* in xcconfig/project.yml for macOS -->
+<key>NSLocalNetworkUsageDescription</key>
+<string>Why your app needs the local network — user-readable, shown in the system permission prompt.</string>
+<key>NSBonjourServices</key>
+<array>
+  <string>_yourapp._tcp</string>
+</array>
+```
+
+If `NSLocalNetworkUsageDescription` is missing, iOS 14+ kills the listener on creation and the user never sees a permission prompt — so they cannot grant access. Symptom is identical to "permission denied". The service type in `NSBonjourServices` MUST match the string passed to `NWBrowser` and `NWListener.Service(type:)` exactly. A typo silently produces empty browser results.
+
+### 2. NWListener / NWBrowser retain rule
+
+Listener and browser must be retained as instance properties:
+
+```swift
+final class LocalNetworkSync {
+    private var listener: NWListener?  // strong reference required
+    private var browser: NWBrowser?
+}
+```
+
+A local `let listener = try NWListener(...)` inside a function is destroyed at scope exit. The mDNSResponder XPC connection drops with it, the user sees nothing, and the bug presents as "no devices found" with no error path.
+
+### 3. Distinguish -65569 (transient) from -65570 (permission)
+
+| Code   | NWError shape         | Meaning                             | Action                          |
+|--------|-----------------------|-------------------------------------|---------------------------------|
+| -65569 | `.dns(-65569)`        | DefunctConnection — mDNSResponder XPC dropped (wifi change, simulator quirk, suspension) | Restart with bounded backoff |
+| -65570 | `.dns(-65570)`        | Permission denied / not granted     | Show "Open Settings" — DO NOT restart |
+
+The historical fix of "show NWError.localizedDescription" surfaces both as raw jargon. Map them:
+
+```swift
+nonisolated private static func isPermissionDenied(_ error: NWError) -> Bool {
+    if case .dns(let code) = error, Int(code) == -65570 { return true }
+    return false
+}
+```
+
+UI translation: -65569 should say "Searching… reconnecting after a network change." (recoverable). -65570 should show a permission card with an Open Settings button (`UIApplication.openSettingsURLString`).
+
+### 4. Restart-on-defunct backoff
+
+`.failed(-65569)` on a retained listener requires recreation — the existing `NWListener` instance is permanently dead. Bounded backoff prevents battery drain on a permanently broken environment:
+
+```swift
+private static let restartDelaysSec: [Double] = [1.0, 3.0, 8.0]
+private var listenerRestartAttempts: Int = 0
+
+private func scheduleListenerRestart() {
+    let delay = Self.restartDelaysSec[min(listenerRestartAttempts, Self.restartDelaysSec.count - 1)]
+    listenerRestartAttempts += 1
+    Task { @MainActor [weak self] in
+        try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
+        guard let self, self.isActive, !self.permissionDenied else { return }
+        self.listener?.cancel()
+        self.listener = nil
+        self.startListener()
+    }
+}
+```
+
+Reset `listenerRestartAttempts = 0` on `.ready` so a successful restart re-enables fast retry on the next failure. **Suspend restart while `permissionDenied` is true** — there is no point restarting a listener the system is going to kill again until the user grants permission.
+
+### 5. Smoking gun signatures
+
+| Symptom                                                                | Cause                                |
+|------------------------------------------------------------------------|--------------------------------------|
+| Listener fails on first launch, no permission prompt ever shown        | Missing `NSLocalNetworkUsageDescription` |
+| Browser results always empty despite peers running                     | Service type mismatch between Plist and code |
+| Listener works in foreground, dies after backgrounding                 | Listener stored in a local, not retained |
+| -65569 appears intermittently after wifi changes / app resume          | Normal — needs restart-on-defunct backoff |
+| -65570 with no in-Settings entry for the app                           | Plist string was added after first launch — uninstall/reinstall to retrigger |
+
+### Incident IDs
+
+- `INC_IOS_LOCAL_NETWORK_DEFUNCT` — -65569 with no restart logic
+- `INC_IOS_LOCAL_NETWORK_PLIST` — missing usage description or Bonjour service entry
+- `INC_IOS_LOCAL_NETWORK_RETAIN` — listener/browser destroyed at scope exit
+- `INC_IOS_LOCAL_NETWORK_PERMISSION_UI` — raw NWError shown to user instead of actionable Open Settings prompt