| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior — enforces root cause investigation before proposing fixes. |
Systematic Debugging
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Phase 1: Root Cause Investigation
BEFORE attempting ANY fix:
- Read error messages carefully — full stack traces, line numbers, error codes. Don't skip past them.
- Reproduce consistently — can you trigger it reliably? Exact steps? Every time?
- Check recent changes —
git diff, recent commits, new dependencies, config changes.
- Gather evidence in multi-component systems — add diagnostic logging at EACH component boundary. Run once to find WHERE it breaks. Then investigate that component.
- Trace data flow — where does the bad value originate? Keep tracing up until you find the source. Fix at source, not at symptom.
Phase 2: Pattern Analysis
- Find working examples — locate similar working code in the same codebase.
- Compare against references — if implementing a pattern, read the reference COMPLETELY.
- Identify differences — what's different between working and broken? List every difference.
- Understand dependencies — what settings, config, environment does this need?
Phase 3: Hypothesis and Testing
- Form single hypothesis — "I think X is the root cause because Y." Be specific.
- Test minimally — smallest possible change. One variable at a time.
- Verify before continuing — worked? Phase 4. Didn't work? New hypothesis. Don't pile fixes.
Phase 4: Implementation
- Create failing test — simplest reproduction. Automated. MUST have before fixing.
- Implement single fix — ONE change. No "while I'm here" improvements.
- Verify fix — test passes? Other tests still pass?
- If 3+ fixes failed — STOP. Question the architecture. This is NOT a failed hypothesis — this is a wrong architecture. Escalate to the user.
Red Flags — STOP and Return to Phase 1
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- Proposing solutions before tracing data flow
- "One more fix attempt" after 2+ failures
- Each fix reveals a new problem in a different place
Quick Reference
| Phase | Key Activities | Done when |
|---|
| 1. Root Cause | Read errors, reproduce, check changes, trace data | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Differences identified |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |