Systematic Debugging
Quick Reference
For detailed patterns and troubleshooting, see:
- DEBUG-PATTERNS.md - Multi-component diagnostics, data flow tracing, hypothesis testing
- TROUBLESHOOTING.md - Red flags, common mistakes, architectural issues
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
When to Use
Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures.
Use ESPECIALLY when:
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
The Four Phases
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?
- If not reproducible → gather more data, don't guess
Check Recent Changes
- Git diff, recent commits
- New dependencies, config changes
Gather Evidence (see DEBUG-PATTERNS.md for multi-component systems)
Trace Data Flow - Where does bad value originate?
Phase 2: Pattern Analysis
- Find working examples in same codebase
- Compare against references - read COMPLETELY
- Identify ALL differences between working and broken
- Understand dependencies and assumptions
Phase 3: Hypothesis and Testing
- Form Single Hypothesis - "I think X is root cause because Y"
- Test Minimally - SMALLEST possible change, one variable
- Verify - Did it work? If not, form NEW hypothesis (don't stack fixes)
Phase 4: Implementation
- Create Failing Test Case - MUST have before fixing
- Implement Single Fix - ONE change, no bundled improvements
- Verify Fix - Tests pass, no regressions
If Fix Doesn't Work:
- Count fixes attempted
- If < 3: Return to Phase 1
- If ≥ 3: STOP and question architecture (see TROUBLESHOOTING.md)
Quick Reference Table
| Phase |
Key Activities |
Success Criteria |
| 1. Root Cause |
Read errors, reproduce, check changes, gather evidence |
Understand WHAT and WHY |
| 2. Pattern |
Find working examples, compare |
Identify differences |
| 3. Hypothesis |
Form theory, test minimally |
Confirmed or new hypothesis |
| 4. Implementation |
Create test, fix, verify |
Bug resolved, tests pass |
1---2name: systematic-debugging3description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions4---56# Systematic Debugging78## Quick Reference910For detailed patterns and troubleshooting, see:11- [DEBUG-PATTERNS.md](DEBUG-PATTERNS.md) - Multi-component diagnostics, data flow tracing, hypothesis testing12- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Red flags, common mistakes, architectural issues1314## The Iron Law1516```17NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST18```1920If you haven't completed Phase 1, you cannot propose fixes.2122**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.2324## When to Use2526Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures.2728**Use ESPECIALLY when:**29- Under time pressure (emergencies make guessing tempting)30- "Just one quick fix" seems obvious31- You've already tried multiple fixes3233## The Four Phases3435### Phase 1: Root Cause Investigation3637**BEFORE attempting ANY fix:**38391. **Read Error Messages Carefully**40 - Don't skip past errors or warnings41 - Read stack traces completely42 - Note line numbers, file paths, error codes43442. **Reproduce Consistently**45 - Can you trigger it reliably?46 - If not reproducible → gather more data, don't guess47483. **Check Recent Changes**49 - Git diff, recent commits50 - New dependencies, config changes51524. **Gather Evidence** (see DEBUG-PATTERNS.md for multi-component systems)53545. **Trace Data Flow** - Where does bad value originate?5556### Phase 2: Pattern Analysis57581. Find working examples in same codebase592. Compare against references - read COMPLETELY603. Identify ALL differences between working and broken614. Understand dependencies and assumptions6263### Phase 3: Hypothesis and Testing64651. **Form Single Hypothesis** - "I think X is root cause because Y"662. **Test Minimally** - SMALLEST possible change, one variable673. **Verify** - Did it work? If not, form NEW hypothesis (don't stack fixes)6869### Phase 4: Implementation70711. **Create Failing Test Case** - MUST have before fixing722. **Implement Single Fix** - ONE change, no bundled improvements733. **Verify Fix** - Tests pass, no regressions7475**If Fix Doesn't Work:**76- Count fixes attempted77- If < 3: Return to Phase 178- If ≥ 3: STOP and question architecture (see TROUBLESHOOTING.md)7980## Quick Reference Table8182| Phase | Key Activities | Success Criteria |83|-------|---------------|------------------|84| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |85| **2. Pattern** | Find working examples, compare | Identify differences |86| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |87| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
martin-janci