| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes |
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.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
The Four Phases
Phase 1: Root Cause Investigation
- Read Error Messages Carefully - don't skip past errors
- Reproduce Consistently - can you trigger it reliably?
- Check Recent Changes - git diff, recent commits
- Gather Evidence in Multi-Component Systems - add diagnostic instrumentation
- Trace Data Flow - where does bad value originate?
Phase 2: Pattern Analysis
- Find Working Examples in same codebase
- Compare Against References - read reference completely
- Identify Differences between working and broken
- Understand Dependencies
Phase 3: Hypothesis and Testing
- Form Single Hypothesis - be specific
- Test Minimally - one variable at a time
- Verify Before Continuing - worked? Phase 4. Didn't? New hypothesis.
Phase 4: Implementation
- Create Failing Test Case - simplest possible reproduction
- Implement Single Fix - one change at a time
- Verify Fix - test passes, no other tests broken
- If fix doesn't work after 3 attempts: STOP and question architecture
Red Flags
"Quick fix for now", "Just try changing X", "Multiple changes at once" - all mean STOP.
Quick Reference
| Phase | Key Activities | Success Criteria |
|---|
| 1. Root Cause | Read errors, reproduce, check changes | 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 |
