| name | systematic-debugging |
| description | Structured 4-phase debugging process. Use when a bug is unclear, a fix has failed twice, or you're stuck on a problem instead of guessing randomly. |
| triggers | ["/debug","debug this","investigate this bug","find the root cause","why is this broken"] |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, TodoWrite, Agent |
| user-invocable | true |
Systematic Debugging
Iron rule: NO fixes without root cause investigation first.
Guessing at fixes creates new bugs. Follow the 4 phases in order.
Phase 1: Reproduce and Investigate
- Read the error carefully — full message, stack trace, exit codes
- Reproduce consistently — find the exact steps that trigger the bug
- Check recent changes —
git log --oneline -10 and git diff for what changed
- Trace the data flow — follow the data backward from the error to its origin
- Add diagnostic logging at boundary layers if the flow is unclear
Output of this phase: A clear statement of what happens vs what should happen, and where in the code the divergence starts.
Phase 2: Pattern Analysis
- Find working examples — is there similar code that works? What's different?
- Compare working vs broken — document every difference
- Map dependencies — what does the broken code depend on? Are those dependencies healthy?
- Check assumptions — is the data shaped the way you think? Are types correct? Are env vars set?
Output of this phase: A list of differences and suspicious areas.
Phase 3: Hypothesis and Testing
- Formulate a specific hypothesis — "The bug happens because X returns Y when it should return Z"
- Test one variable at a time — change only one thing per attempt
- Verify with evidence — don't assume a fix worked, run the reproduction steps again
- If the hypothesis is wrong — go back to Phase 1 with new information, don't guess again
Critical rule: After 3 failed fix attempts, stop. The problem is likely architectural, not a simple bug. Reassess the approach entirely instead of attempting fix #4.
Phase 4: Fix and Verify
- Write a failing test that reproduces the bug (TDD)
- Apply a single, targeted fix — minimal change
- Run the test — confirm it passes
- Run the full test suite — confirm no regressions
- Remove diagnostic logging added in Phase 1
- Commit with a clear message explaining the root cause
git commit -m "fix: [what was fixed]
Root cause: [why it was broken]
Fix: [what was changed and why]"
Red Flags — Restart from Phase 1
- You're proposing a fix before tracing the data flow
- You're changing multiple things at once
- Each fix reveals a new problem elsewhere
- You're wrapping code in try/catch to hide errors
- You're adding workarounds instead of fixing root causes
Anti-Patterns
| Bad | Good |
|---|
| "Let me try adding a null check" | "Let me trace where this null comes from" |
| Changing 3 things at once | Changing 1 thing, testing, then deciding next |
| "It works now" (without understanding why) | "It works because X was causing Y" |
| Suppressing the error | Fixing the source of the error |
| Googling the error and copy-pasting a fix | Understanding the error, then finding a solution |
When to Escalate
Ask the user for help when:
- You've exhausted 3 hypotheses and none were correct
- The bug involves external services you can't inspect
- The fix requires an architectural decision (not a code fix)
- Reproduction depends on specific data or environment you don't have access to
