systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
When & Why to Use This Skill
This Claude skill implements a rigorous four-phase systematic debugging framework designed to eliminate guesswork in software development. By enforcing a 'root cause first' protocol, it guides users through detailed investigation, pattern analysis, and hypothesis testing to ensure technical issues, test failures, and unexpected behaviors are resolved at their source rather than just masking symptoms.
Use Cases
- Case 1: Resolving complex or cryptic test failures where the error message doesn't immediately reveal the underlying logic flaw.
- Case 2: Troubleshooting intermittent 'heisenbugs' or non-deterministic behavior by gathering evidence and tracing data flow systematically.
- Case 3: Breaking the cycle of failed 'quick fixes' in high-pressure situations by enforcing a disciplined hypothesis-testing phase.
- Case 4: Analyzing performance regressions or build failures by comparing broken states against known working patterns and references.
- Case 5: Validating architectural assumptions when standard debugging attempts fail, helping to identify if a deeper redesign is required.
| name | systematic-debugging |
|---|---|
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions |
| context | fork |
Systematic Debugging
Quick Reference
For detailed patterns and troubleshooting, see:
- DEBUG-PATTERNS.md - Multi-component diagnostics, data flow tracing, hypothesis testing
- TROUBLESHOOTING.md - Red flags, common mistakes, architectural issues
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
When to Use
Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures.
Use ESPECIALLY when:
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
The Four Phases
Phase 1: Root Cause Investigation
BEFORE attempting ANY fix:
Read Error Messages Carefully
- Don't skip past errors or warnings
- Read stack traces completely
- Note line numbers, file paths, error codes
Reproduce Consistently
- Can you trigger it reliably?
- If not reproducible → gather more data, don't guess
Check Recent Changes
- Git diff, recent commits
- New dependencies, config changes
Gather Evidence (see DEBUG-PATTERNS.md for multi-component systems)
Trace Data Flow - Where does bad value originate?
Phase 2: Pattern Analysis
- Find working examples in same codebase
- Compare against references - read COMPLETELY
- Identify ALL differences between working and broken
- Understand dependencies and assumptions
Phase 3: Hypothesis and Testing
- Form Single Hypothesis - "I think X is root cause because Y"
- Test Minimally - SMALLEST possible change, one variable
- Verify - Did it work? If not, form NEW hypothesis (don't stack fixes)
Phase 4: Implementation
- Create Failing Test Case - MUST have before fixing
- Implement Single Fix - ONE change, no bundled improvements
- Verify Fix - Tests pass, no regressions
If Fix Doesn't Work:
- Count fixes attempted
- If < 3: Return to Phase 1
- If ≥ 3: STOP and question architecture (see TROUBLESHOOTING.md)
Quick Reference Table
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |