kienbui1995 Systematic Debugging
Overview
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
When to Use
Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues.
Use ESPECIALLY when:
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- You don't fully understand the issue
The Four Phases
Complete each phase before proceeding to the next.
Phase 1: Root Cause Investigation
BEFORE attempting ANY fix:
Read Error Messages Carefully
- Don't skip past errors or warnings
- Read stack traces completely
- Note line numbers, file paths, error codes
Reproduce Consistently
- Can you trigger it reliably?
- What are the exact steps?
- If not reproducible → gather more data, don't guess
Check Recent Changes
- Git diff, recent commits
- New dependencies, config changes
- Environmental differences
Gather Evidence in Multi-Component Systems
- Log what enters/exits each component boundary
- Don't guess which component fails — prove it
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
| Thought | Reality |
|---|---|
| "Let me just try this" | That's guessing, not debugging |
| "It's probably X" | Probably ≠ evidence |
| "Quick fix, then investigate" | Quick fixes become permanent |
| "I've seen this before" | Similar ≠ same. Verify. |
| "Let me change multiple things" | One change at a time |
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