--- name: systematic-debugging description: | Root-cause a bug before touching a fix: reproduce, isolate, form and test a hypothesis, confirm the cause, then fix and verify. Stops guess-driven patching. For persistent, intermittent, or "already tried a few things" bugs. --- # Systematic Debugging Trigger phrases: "debug", "root cause", "why is this failing", "intermittent bug", "can't reproduce", "is broken", "crashes" One rule holds the whole skill together: **no fix without a confirmed root cause.** A patch that makes the symptom disappear without a proven cause is not a fix — it's a coin flip that hides the bug until it returns somewhere worse. This skill is the discipline that turns "try things until it works" into "understand, then change one thing." > **Kit adaptation (local, .claude/):** Distinct from `iterate` (a self-correction loop over a *task*) and `reflect` > (meta-review of an approach) — this skill is for a *defect*. §4 Prohibitions apply; a fix still goes through the > project's review/test gates. Don't disable a test or a gate to make a symptom pass (that is masking, not fixing). ## The loop (do them in order — skipping a step is why bugs come back) 1. **Reproduce** — a reliable, minimal repro. Can't reproduce → that IS the first problem; see `references/techniques.md` (intermittent/heisenbug). 2. **Isolate** — shrink the surface until the failure is in the smallest possible slice (bisect commits, halve the input, disable half the system). 3. **Hypothesize** — state ONE falsifiable cause: "X fails because Y." Write it down. A vague hunch is not a hypothesis. 4. **Test the hypothesis** — the cheapest observation that would *disprove* it (a log, a breakpoint, a probe). If it survives, you have the cause; if not, back to 3. 5. **Confirm the root cause** — you can explain the full chain symptom←…←cause, and you can turn the bug on and off by touching the cause. 6. **Fix** — the smallest change at the cause (not the symptom). Consider what else shares that cause. 7. **Verify** — the original repro now passes, a regression test locks it, and nothing nearby broke. ## Checklist - [ ] Reliable repro captured (exact steps/input/env) - [ ] Failure isolated to the smallest slice - [ ] One falsifiable hypothesis written down - [ ] Hypothesis tested by observation (not by applying a fix and seeing) - [ ] Root cause confirmed (can toggle the bug via the cause; full chain explained) - [ ] Fix at the cause + regression test added - [ ] Original repro passes; no new failures ## Anti-patterns (each is guess-driven patching wearing a disguise) - **Shotgun debugging** — changing several things at once; now you can't tell what mattered. One change at a time. - **Symptom patching** — a `try/catch`, a null-guard, a retry that swallows the failure without explaining it. - **"It works now"** without knowing *why* it broke — the bug is dormant, not dead. - **Blaming the environment/flake** before isolating — sometimes true, but only *after* step 2, never as the first move. - **Deleting/skipping the failing test** to go green — that is masking; the gate exists to catch exactly this. --- ## Techniques by symptom Bisecting (git + input + system), instrumentation vs. debugger, intermittent/heisenbugs (timing, state, ordering, resource), the hypothesis log, and when to stop and ask for a second pair of eyes: **`references/techniques.md`**. ## Invariant rules 1. **No fix without a confirmed root cause** — the one rule; everything else serves it. 2. **One change at a time** — isolate cause and effect; never shotgun. 3. **Fix the cause, not the symptom** — a guard that hides the failure is not a fix. 4. **Lock it with a regression test** — the repro becomes a test so it can't silently return. 5. **Never mask to go green** — don't disable a test/gate/assertion to make the symptom pass.