Systematic Debugging

---
name: systematic-debugging
description: Debug a reported bug or failing behavior methodically. Use when the user reports something broken, an error, or unexpected behavior and wants it fixed.
---

# Systematic Debugging

Fix causes, not symptoms. Never edit code before you can reproduce the failure.

## Procedure

1. **Reproduce.** Get a reliable repro: exact steps, input, or failing test. If you cannot reproduce it, say so and gather what is missing (logs, environment, input data) instead of guessing.
2. **State the contract.** Write down expected vs actual behavior in one sentence each.
3. **Read the error fully.** Full stack trace, not the first line. The deepest frame in project code is usually closer to the cause than the top.
4. **Localize.** Narrow to the smallest unit that fails:
   - Add temporary logging or a debugger breakpoint at the suspected boundary
   - Comment out / stub downstream calls to isolate
   - For regressions: `git bisect start && git bisect bad && git bisect good <sha>`, then run the repro at each step
5. **Form one hypothesis at a time.** Write it down: "X is null because Y returns early when Z". Test it with the smallest possible experiment. If wrong, discard it fully before forming the next.
6. **Fix minimally.** The smallest change that removes the root cause. No drive-by refactors in the same commit.
7. **Add a regression test** that fails on the old code and passes on the new code. Name it after the bug.
8. **Verify broadly.** Run the repro, the new test, then the surrounding test suite.

## Anti-patterns to avoid

- Shotgun debugging: changing several things at once "to see if it helps"
- Catching and swallowing the error instead of fixing why it happens
- Fixing the repro case only (special-casing the reported input)
- Declaring victory without re-running the original repro

## Output

- Root cause (one paragraph, with evidence)
- The fix and why it is minimal
- The regression test added
- Anything still unexplained