Systematic Debugging Skill
Overview
This skill provides a structured four-phase debugging framework emphasizing root cause discovery before attempting fixes. Core principle: "Random fixes waste time and create new bugs. Quick patches mask underlying issues."
Quick Start
- Investigate - Gather evidence, reproduce consistently
- Analyze - Compare with working patterns
- Hypothesize - Form and test specific theories
- Implement - Fix with test coverage
When to Use
- Bug reports requiring investigation
- Test failures with unclear causes
- Production incidents
- Performance regressions
- Integration failures
- Any debugging that requires more than 5 minutes
The Four Phases
Phase 1: Root Cause Investigation
Objective: Understand the problem completely before attempting any fix.
Steps:
- Examine error messages thoroughly
- Reproduce the issue consistently
- Review recent changes (commits, configs, dependencies)
- Gather diagnostic evidence (logs, traces, metrics)
- For multi-component systems, add instrumentation at each boundary
Questions to answer:
- What exactly is failing?
- When did it start failing?
- What changed recently?
- Can I reproduce it reliably?
Phase 2: Pattern Analysis
Objective: Find working examples and understand differences.
Steps:
- Locate working examples in the codebase
- Compare against reference implementations completely
- Identify differences systematically
- Understand all dependencies
Key comparisons:
- Working vs. broken code paths
- Expected vs. actual behavior
- Known good state vs. current state
Phase 3: Hypothesis and Testing
Objective: Form and validate theories before changing code.
Steps:
- Formulate a specific hypothesis
- Design a test for the hypothesis
- Test with minimal changes (one variable at a time)
- Verify results before proceeding
Hypothesis format: "The bug occurs because [condition] when [trigger], which causes [symptom]."
Phase 4: Implementation
Objective: Fix the root cause with proper verification.
Steps:
- Create a failing test case reproducing the bug
- Implement a single fix addressing the root cause
- Verify the test passes
- Verify no other tests broke
- Document the fix
Critical Safeguards
Hard Stop Rule
If >= 3 fixes fail: STOP and question the architecture.
When multiple fixes fail, the issue indicates deeper structural problems requiring discussion rather than continued symptom-patching.
Red Flags (Restart Process)
- Proposing solutions before investigation
- Attempting multiple simultaneous fixes
- Assuming without verification
- Skipping reproduction step
- "It should work" without evidence
Debugging Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Shotgun debugging | Random changes hoping something works | Systematic investigation |
| Printf debugging only | Incomplete picture | Structured instrumentation |
| Blame the framework | Avoids understanding | Verify framework behavior |
| "Works on my machine" | Environment assumptions | Document exact repro steps |
| Quick patch | Hides root cause | Find and fix actual cause |
Instrumentation Strategies
Logging Strategy
1. Entry/exit of suspected functions
2. Input/output values at boundaries
3. State changes at key points
4. Timing information for performance issuesBoundary Tracing
For multi-component systems:
[Input] -> [Component A] -> [Component B] -> [Output]
^ ^ ^ ^
| | | |
Check 1 Check 2 Check 3 Check 4Add verification at each boundary to isolate failure point.
Best Practices
Do
- Reproduce before investigating
- Document investigation steps
- Test one hypothesis at a time
- Write regression test for every bug fix
- Share findings with team
- Update documentation when environment-related
Don't
- Jump to conclusions
- Make multiple changes at once
- Fix symptoms instead of causes
- Skip the hypothesis step
- Merge fixes without tests
- Ignore intermittent failures
Error Handling
| Situation | Action |
|---|---|
| Cannot reproduce | Gather more context, check environment differences |
| Multiple potential causes | Isolate and test each separately |
| Fix breaks other things | Revert, investigate dependencies |
| Root cause unclear after investigation | Escalate, add more instrumentation |
Metrics
| Metric | Target | Description |
|---|---|---|
| First-fix success rate | >80% | Fixes that resolve issue first time |
| Regression rate | <5% | Bug fixes causing new bugs |
| Investigation time ratio | >60% | Time spent investigating vs. coding |
| Documentation rate | 100% | Bugs documented with root cause |
Debugging Checklist
- Issue reproduced consistently
- Recent changes reviewed
- Error messages fully understood
- Working comparison found
- Hypothesis documented
- Single-variable test performed
- Root cause identified
- Failing test written
- Fix implemented
- All tests pass
- Fix documented
Related Skills
- tdd-obra - Test-first development
- writing-plans - Plan implementations
- code-reviewer - Code quality review
Version History
- 1.0.0 (2026-01-19): Initial release adapted from obra/superpowers