Systematic Debugging

The Four Phases

Complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully

   • Don't skip past errors or warnings
   • Read stack traces completely
   • Note line numbers, file paths, error codes

2. Reproduce Consistently

   • Can you trigger it reliably?
   • What are the exact steps?
   • If not reproducible → gather more data, don't guess

3. Check Recent Changes

   • Git diff, recent commits
   • New dependencies, config changes
   • Environmental differences

4. Gather Evidence in Multi-Component Systems

   • Log what enters/exits each component boundary
   • Don't guess which component fails — prove it

5. Form Hypothesis

   • Based on evidence, not intuition
   • Must be falsifiable
   • "I think X because evidence Y shows Z"

Phase 2: Verify Hypothesis

• Design a test that would DISPROVE your hypothesis
• Run it. If hypothesis survives, proceed.
• If disproved: back to Phase 1 with new evidence

Phase 3: Fix

• Fix the ROOT CAUSE, not the symptom
• Minimal change — don't refactor while debugging
• One fix at a time

Phase 4: Verify Fix

• Original bug no longer reproduces
• No new failures introduced
• Run full test suite
• Document what happened and why

Red Flags — STOP

Model Routing

For complex multi-system bugs, consider dispatching the debugger agent (Sonnet) which has full tool access for systematic investigation.

Integration

• magic-powers:verification-before-completion — verify fix before claiming done
• magic-powers:test-driven-development — write regression test for the bug