troubleshootlisted

# troubleshoot — root cause, not symptom The fast fix that doesn't understand the bug just moves it. This skill refuses to patch a symptom until the root cause is proven, and writes the lesson back so the next session doesn't relearn it. ## Steps 1. **Read the Spine.** Load `context.md` (architecture + language), `conventions.md` (test/debug commands), and `decisions/` — has this surface bitten us before? A prior ADR may already hold the answer. 2. **Reproduce first.** Get a reliable, minimal repro. If you can't reproduce it, you can't confirm a fix — gather more evidence before guessing. 3. **Investigate.** Follow the evidence: read the failing path, logs, recent diffs, and state. Narrow the surface methodically. No speculative edits. 4. **Hypothesize.** State a single falsifiable hypothesis about the *root* cause, then confirm it with evidence before changing anything. **Iron law: no fix without a confirmed root cause.** 5. **Pin it with a test.** Write a failing test that reproduces the bug (RED). This is the proof of the cause and the guard against regression. 6. **Fix at the root.** Make the minimal change that addresses the cause, not the symptom. Confirm the test goes GREEN and the original repro is gone. 7. **Record in the Spine.** Write the root cause and fix to `journal.md`. If the failure mode is a durable lesson, add an ADR in `.spine/decisions/NNNN-title.md` so it's remembered. Hand off to `verify` to confirm against criteria. ##