Systematic Debugging

Systematic Debugging

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION

Why: Random fixes waste time, create new bugs, mask real issues.

When to Use

ANY technical issue: bugs, test failures, performance problems, build issues.

ESPECIALLY when:

• Under time pressure
• "Quick fix" seems obvious
• Tried multiple fixes already
• Don't fully understand issue

Four Phases (MUST complete in order)

Phase 1: Root Cause Investigation

BEFORE any fix:

1. Read errors completely - Don't skip stack traces
2. Reproduce consistently - Exact steps, reliable trigger
3. Check recent changes - Git diff, dependencies, config
4. Gather evidence - Add diagnostic logging at component boundaries
5. Trace data flow - Where does bad value originate?

Multi-component systems:

# Add logging at EACH layer
echo "=== Layer 1: Input ===" && log_input
echo "=== Layer 2: Processing ===" && log_process
echo "=== Layer 3: Output ===" && log_output
# Run ONCE to see WHERE it breaks

Phase 2: Pattern Analysis

1. Find working examples - Similar code that works
2. Compare references - Read completely, don't skim
3. Identify differences - Every difference matters
4. Understand dependencies - Config, environment, assumptions

Phase 3: Hypothesis & Testing

1. Form hypothesis - "I think X causes Y because Z"
2. Test minimally - Smallest change, one variable
3. Verify - Worked? → Phase 4. Didn't work? → New hypothesis
4. When uncertain - Say "I don't understand X"

Phase 4: Implementation

1. Create failing test - Automated if possible
2. Implement single fix - Address root cause only
3. Verify - Tests pass, issue resolved, no new breakage

If fix doesn't work:

• Fixes tried < 3: Return to Phase 1
• Fixes tried ≥ 3: STOP - Question architecture
  • Pattern might be fundamentally wrong
  • Discuss with human before more fixes

Red Flags - STOP & Follow Process

Catch yourself thinking:

• "Quick fix now, investigate later"
• "Just try X and see"
• "Skip the test, manually verify"
• "Probably X, let me fix"
• "One more fix" (after 2+)
• "Each fix reveals new problems"

ALL → Return to Phase 1

Common Excuses

Quick Reference

Real Impact

• Systematic: 15-30 min to fix
• Random: 2-3 hours thrashing
• First-time success: 95% vs 40%

---

Complete guide: read .claude/​skills/​workflows/​systematic-debugging/​SKILL.md (original 296 lines)