by obra
A disciplined approach to bugs, test failures, and unexpected behavior. Use when debugging issues to ensure root cause investigation before attempting fixes. Prevents symptom-focused solutions that create additional complications.
The systematic-debugging skill enables AI agents like Claude and ChatGPT to a disciplined approach to bugs, test failures, and unexpected behavior. use when debugging issues to ensure root cause investigation before attempting fixes. prevents symptom-focused solutions that create additional complications.
# Systematic Debugging
A disciplined approach to technical problem-solving across bugs, test failures, and unexpected behavior.
## Core Principle
**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
Symptom-focused solutions create additional complications rather than solving underlying issues.
## Four Required Phases
### Phase 1: Root Cause Investigation
1. Carefully examine error messages
2. Reproduce issues consistently
3. Review recent changes
4. Gather diagnostic evidence
For multi-component systems, add diagnostic instrumentation at each boundary to identify where failures occur.
### Phase 2: Pattern Analysis
1. Identify working examples
2. Compare against references completely
3. Document all differences
4. Understand dependencies
### Phase 3: Hypothesis and Testing
1. Form specific hypotheses
2. Test with minimal changes
3. Verify results before proceeding
### Phase 4: Implementation
1. Create failing test cases
2. Implement single fixes addressing root causes
3. Verify solutions work
**Critical safeguard:** If three or more fixes fail, question the architecture rather than continuing attempts.
## Red Flags
These indicate deviation from the process:
- Proposing solutions before tracing data flow
- Attempting multiple fixes simultaneously
- "One more fix attempt" after two prior failures
- Skipping reproduction steps
- Not examining error messages carefully
## Real-World Results
Systematic approaches resolve issues in 15-30 minutes versus 2-3 hours for random-fix approaches.
First-time fix rates: 95% (systematic) vs 40% (random).
## Debugging Checklist
Before proposing any fix:
- [ ] Error message fully examined
- [ ] Issue reproduced consistently
- [ ] Recent changes reviewed
- [ ] Root cause identified (not just symptoms)
- [ ] Hypothesis formed and documented
- [ ] Test case created
Only after all checks pass should implementation begin.