| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, 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.
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
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 them. 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 — Add diagnostic logging at each component boundary. Run once to see WHERE it breaks. Then investigate that specific component.
-
Trace data flow — Where does the bad value originate? What called this with bad input? 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 — Read reference implementation COMPLETELY. Don't skim.
- Identify differences — What's different between working and broken? List every difference.
- Understand dependencies — What settings, config, environment does this need?
