| name | debug |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Enforces root cause investigation before fixing. No guessing, no shotgun debugging. Hard stop after 3 failed hypotheses. Use when: tests fail, errors appear, behavior doesn't match expectations, or something "just broke."
|
| version | 1.0.0 |
Debug
The Rule
No fixes without root cause investigation. If you can't explain WHY it's broken, you can't fix it. You're just guessing.
The Loop
Phase 1: Investigate
- Collect symptoms: what fails, when, error messages, stack traces
- Read the relevant code (not just the error line, the surrounding context)
- Check
git log for recent changes in affected files
- Reproduce the issue. If you can't reproduce it, you can't verify a fix.
Phase 2: Pattern match
Does this look familiar?
| Pattern | Typical signal |
|---|
| Race condition | Intermittent, timing-dependent, works in debug mode |
| Nil/null propagation | Crashes on missing data, works with full records |
| State corruption | Works first time, breaks on retry or concurrent use |
| Integration failure | Works locally, breaks with external service |
| Config drift | Works in one environment, not another |
| Stale cache | Works after restart, breaks after time passes |
| Off-by-one | Works for most inputs, fails at boundaries |
| Import/dependency | Works in isolation, breaks when composed |
Phase 3: Hypothesize and test
- Form a hypothesis: "I think X is happening because Y"
- Design a test: add targeted logging, write a minimal reproduction, or add an assertion
- Run it. Does the evidence support the hypothesis?
3-strike rule: If 3 hypotheses fail, STOP. You're probably wrong about the problem space. Step back and:
- Re-read the code from scratch
- Check your assumptions (is the data what you think it is?)
- Widen the scope (is the bug actually in the file you're looking at?)
- Ask for help
Phase 4: Fix with minimum force
- Fix the root cause only. Smallest diff possible.
- Write a regression test that fails without the fix
- Don't fix adjacent issues in the same change
Phase 5: Verify
- Reproduce the original issue. Confirm it's gone.
- Run the full test suite
- Confirm the regression test passes
Escalation
If you've been through the loop 3+ times across multiple attempts and the bug persists, this isn't a bug. It's an architecture problem. Stop fixing symptoms and start asking: is the design wrong?
Output Format
When reporting a fix:
Symptom: [what was observed]
Root cause: [why it happened]
Fix: [what changed]
Evidence: [how we confirmed]
Regression: [test that prevents recurrence]
Rationalization Prevention
| Thought | Reality |
|---|
| "I think I know what this is, let me just fix it" | You thought you knew last time too. Investigate first. |
| "It's probably just a typo" | Confirm it's a typo before "fixing" it. |
| "Let me try a few things" | That's shotgun debugging. Form a hypothesis first. |
| "This worked before, something must have changed" | Great. git log will show you what changed. Start there. |
