By name: systematic-debugging description: Four-phase debugging methodology for finding and fixing bugs. Use when debugging issues, investigating errors, fixing crashes, or troubleshooting problems. context: fork agent: Explore
Systematic Debugging
A structured approach to finding and fixing bugs in any codebase.
The Four Phases
Reproduce → Isolate → Identify → Fix → Verify
Phase 1: Reproduce
Goal: Reliably trigger the bug
Steps
Get the exact symptoms
- What error message appears?
- What behavior is wrong?
- What behavior is expected?
Find reproduction steps
- What inputs trigger it?
- What state is required?
- Is it consistent or intermittent?
Create minimal reproduction
- Smallest test case that fails
- Remove unrelated code/data
- Document exact steps
Phase 2: Isolate
Goal: Narrow down where the bug occurs
Techniques
Binary Search
Cut the problem space in half repeatedly.
Add Logging
log("Login handler called", email)
log("User found", user.id if user else None)
log("Password check", password_matches)
Check Recent Changes
git log --oneline -20
git bisect start
Phase 3: Identify
Goal: Find the root cause
Ask "Why?" Five Times
- Why does login fail? → Password check returns false
- Why does password check return false? → Hash comparison doesn't match
- Why doesn't hash match? → Comparing plain text to hash
- Why comparing plain to hash? → Password isn't hashed before comparison
- Why isn't password hashed? → Missing hash call in auth service
Phase 4: Fix & Verify
Goal: Fix the bug and prove it's fixed
- Write a test first - Test that fails without fix
- Make the minimal change - Fix only the bug
- Verify reproduction test passes
- Check for regressions - All existing tests pass
Debugging Checklist
## Bug: [Description]
### Reproduction
- [ ] Can reproduce consistently
- [ ] Have minimal test case
### Isolation
- [ ] Narrowed to specific area
- [ ] Identified failing component
### Identification
- [ ] Found root cause
- [ ] Can explain why it happens
### Fix
- [ ] Test written that catches bug
- [ ] Minimal fix implemented
- [ ] All tests pass
- [ ] No regressions