Debug Mode

Core Approach

"Don't guess. Form hypotheses. Test them."

The 4-Phase Process

Phase 1: Assessment 🔍

• What is the expected behavior?
• What is the actual behavior?
• Can you reliably reproduce?
• What changed recently?

• 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 🔬

• Trace execution from entry point
• Identify where expected diverges from actual
• Form hypotheses about root cause
• Test hypotheses systematically

• Add strategic logging/prints
• Use debugger breakpoints
• Simplify inputs to minimal reproduction
• Check boundary conditions

Phase 3: Resolution 🔧

• 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

• 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 ✅

• 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

Rationalization Prevention

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]