Systematic Debugging
Iron Law
"NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"
Attempting to fix symptoms without understanding causes wastes time and creates new problems.
Phase 1: Root Cause Investigation
- Read error messages and stack traces CAREFULLY
- Reproduce the issue consistently
- Examine recent changes via
git diff and git log
- Add diagnostic logging at component boundaries
- Trace data flow through the system
Output: "The failure occurs at [location] because [specific reason]"
Phase 2: Pattern Analysis
- Find WORKING examples in the codebase
- Study reference implementations completely
- Compare differences between working and broken code
- Map dependencies and assumptions
Output: "Working code does X, broken code does Y, the difference is Z"
Phase 3: Hypothesis Testing
- Form SPECIFIC hypothesis: "I think X causes Y because Z"
- Test with MINIMAL changes (one thing at a time)
- If fix fails, REVERT before trying another
Critical: After 3 failed attempts, STOP. Question if the architecture is fundamentally flawed.
Phase 4: Implementation
- Write a FAILING test that reproduces the bug
- Implement SINGLE fix addressing root cause
- Verify test now passes
- Verify all other tests still pass
Red Flags (STOP immediately)
- Proposing fixes before understanding the issue
- Making multiple simultaneous changes
- Third fix attempt failed → architecture review needed
$ARGUMENTS