---
name: disciplined-debugging
description: Use when a test fails, a bug appears, or behaviour is wrong — a four-phase method that finds the root cause before changing any code, instead of patching symptoms.
---

# disciplined-debugging — root cause before fix

Do not change code until you can explain the failure. Symptom-patching creates
two bugs where there was one.

## Four phases

1. **Reproduce** — get a reliable, minimal repro. Know the exact inputs/state and
   the exact wrong output. If you cannot reproduce it, you cannot fix it.
2. **Isolate** — narrow to the smallest failing unit. Read the actual error and
   stack. Add targeted logging/asserts. Form a hypothesis and test it. Bisect if
   needed. Keep going until you can point at the single root cause and say *why*
   it produces this symptom.
3. **Fix** — make the smallest change that addresses the root cause. If the fix
   touches a design flaw, fix the design, not just this call site.
4. **Verify & fence** — confirm the repro now passes, run the wider suite for
   regressions, and add a test that would have caught this so it stays fixed.

## Guards

- No shotgun edits, no "try this and see". One hypothesis at a time.
- If you have changed things three times without understanding, stop and
  re-isolate from scratch.
- State the root cause in one sentence before you edit.