Debug Mode
Systematic bug investigation and resolution.
Core Approach
"Don't guess. Form hypotheses. Test them."
The 4-Phase Process
Phase 1: Assessment π
Goal: Understand and reproduce
- What is the expected behavior?
- What is the actual behavior?
- Can you reliably reproduce?
- What changed recently?
Key Questions:
- When did this start happening?
- Does it happen consistently or intermittently?
- What are the exact inputs that trigger it?
- What error messages or symptoms appear?
Phase 2: Investigation π¬
Goal: Isolate and trace
- Trace execution from entry point
- Identify where expected diverges from actual
- Form hypotheses about root cause
- Test hypotheses systematically
Techniques:
- Add strategic logging/prints
- Use debugger breakpoints
- Simplify inputs to minimal reproduction
- Check boundary conditions
Phase 3: Resolution π§
Goal: Fix minimally and verify
- Implement the smallest fix that addresses root cause
- Don't fix symptoms, fix the disease
- Add regression test
- Verify fix doesn't break other things
If fix doesn't work:
- Count: How many fixes attempted?
- If < 3: Return to Phase 1, re-analyze with new information
- If β₯ 3: STOP. Question your understanding of the system.
Phase 4: Quality β
Goal: Prevent recurrence
- Add test covering the bug
- Document if the cause was non-obvious
- Consider if similar bugs exist elsewhere
- Clean up debug code
Debugging Checklist
- [ ] **Reproduced**: Can trigger bug consistently
- [ ] **Isolated**: Know which component is failing
- [ ] **Root Cause**: Understand WHY it fails
- [ ] **Fixed**: Minimal change addresses cause
- [ ] **Tested**: Regression test added
- [ ] **Clean**: Debug code removed
Hypothesis Template
**Hypothesis**: [What you think is wrong]
**Test**: [How you'll verify]
**Result**: [What happened]
**Conclusion**: [Confirmed/Rejected/Needs more info]
Common Root Causes
| Symptom | Often Caused By |
|---|---|
| Works locally, fails in CI | Environment differences, missing deps |
| Intermittent failure | Race condition, timing, external dependency |
| Wrong output | Logic error, wrong variable, off-by-one |
| Crash/exception | Null/None access, type mismatch, missing data |
| Performance issue | N+1 queries, missing index, memory leak |
Rationalization Prevention
| Excuse | Reality |
|---|---|
| "I'll just add a quick fix" | Quick fixes hide root cause. Follow Phase 1 first. |
| "It's probably X" | "Probably" isn't evidence. Test the hypothesis. |
| "This is too simple to debug formally" | Simple bugs waste the most time when undiagnosed. |
| "I've tried 3 things, might as well try a 4th" | STOP. Return to Phase 1. Re-analyze with new info. |
| "It works now, not sure why" | If you don't know why it works, it will break again. |
Red Flags - STOP and Re-Assess
- Adding a 3rd fix attempt without returning to Phase 1
- Saying "should work now" without verification
- Fixing a symptom because root cause is unclear
- Skipping reproduction because "I know what's wrong"
- Multiple hypotheses being tested simultaneously
Debug Report Format
## Debug Report
### Bug Summary
- **Expected**: [what should happen]
- **Actual**: [what happens instead]
- **Severity**: [critical/high/medium/low]
### Reproduction
1. [Step to reproduce]
2. [Step to reproduce]
3. [Observe bug]
**Minimal reproduction**: [simplest case that triggers bug]
### Investigation
| Hypothesis | Test | Result |
| ---------- | -------------- | -------------------------- |
| [theory] | [what I tried] | β
Confirmed / β Rejected |
### Root Cause
[What's actually wrong and why]
### Fix Applied
- **File**: `path/to/file.py`
- **Change**: [what was modified]
- **Why**: [how this fixes the root cause]
### Verification
- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] Regression test added: `test_name`
- [ ] No debug code left behind
### Prevention
[How to prevent similar bugs in the future]