Systematic Debugging
Source: obra/superpowers
Overview
This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
4-Phase Debugging Process
Phase 1: Reproduce
Before fixing, reliably reproduce the issue.
Reproduction Steps
- [Exact step to reproduce]
- [Next step]
- [Expected vs actual result]
Reproduction Rate
- Always (100%)
- Often (50-90%)
- Sometimes (10-50%)
- Rare (<10%)
Phase 2: Isolate
Narrow down the source.
Isolation Questions
- When did this start happening?
- What changed recently?
- Does it happen in all environments?
- Can we reproduce with minimal code?
- What's the smallest change that triggers it?
Phase 3: Understand
Find the root cause, not just symptoms.
Root Cause Analysis
The 5 Whys
- Why: [First observation]
- Why: [Deeper reason]
- Why: [Still deeper]
- Why: [Getting closer]
- Why: [Root cause]
Phase 4: Fix & Verify
Fix and verify it's truly fixed.
Fix Verification
- Bug no longer reproduces
- Related functionality still works
- No new issues introduced
- Test added to prevent regression
Debugging Checklist
Before Starting
- Can reproduce consistently
- Have minimal reproduction case
- Understand expected behavior
During Investigation
- Check recent changes (git log)
- Check logs for errors
- Add logging if needed
- Use debugger/breakpoints
After Fix
- Root cause documented
- Fix verified
- Regression test added
- Similar code checked
Common Debugging Commands
Recent changes
git log --oneline -20 git diff HEAD~5
Search for pattern
grep -r "errorPattern" --include="*.ts"
Check logs
pm2 logs app-name --err --lines 100
Anti-Patterns
❌ Random changes - "Maybe if I change this..." ❌ Ignoring evidence - "That can't be the cause" ❌ Assuming - "It must be X" without proof ❌ Not reproducing first - Fixing blindly ❌ Stopping at symptoms - Not finding root cause