systematic-debugging
Scannednpx machina-cli add skill vudovn/antigravity-kit/systematic-debugging --openclawSystematic 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
1. [Exact step to reproduce]
2. [Next step]
3. [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
1. Why: [First observation]
2. Why: [Deeper reason]
3. Why: [Still deeper]
4. Why: [Getting closer]
5. 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
Source
git clone https://github.com/vudovn/antigravity-kit/blob/main/.agent/skills/systematic-debugging/SKILL.mdView on GitHub Overview
This skill provides a structured approach to debugging to avoid guessing and ensure problems are understood before solving. It uses a 4-phase process: Reproduce, Isolate, Understand (root cause with the 5 Whys), and Fix & Verify, supported by a lightweight checklist and evidence-focused commands.
How This Skill Works
Start by reliably reproducing the issue, then narrow the source with focused questions and a minimal reproduction. Next, perform root-cause analysis using the 5 Whys to identify the underlying cause, then implement a fix and verify it with checks and regression safeguards.
When to Use It
- When debugging a complex issue where guessing won't help and evidence is required
- When you need reliable reproduction steps and evidence-based verification
- When the bug spans multiple environments or modules and must be isolated
- When a change was recently introduced and you must pinpoint its impact
- When you want a regression-safe fix and clear documentation of root cause
Quick Start
- Step 1: Reproduce the issue reliably using explicit steps and expected vs actual results
- Step 2: Isolate the source with targeted questions and a minimal repro to narrow the scope
- Step 3: Perform root-cause analysis with the 5 Whys and implement a verified fix, then run regression checks
Best Practices
- Reproduce the issue reliably before changing code
- Create a minimal, reproducible example to isolate the problem
- Apply the 5 Whys for true root-cause analysis
- Verify the fix with targeted checks and regression tests
- Document root cause and maintain evidence (logs, diffs, notes)
Example Use Cases
- A bug that always reproduces in staging—capture exact steps, minimize the code, and pinpoint the root cause
- A regression after a merge—use git log/diff to locate the change and verify with a regression test
- A production issue that appears only on one environment—compare logs across environments to identify differences
- Avoiding guessing by applying the 5 Whys to reveal root causes instead of symptoms
- After implementing a fix, add regression tests and ensure related functionality remains healthy
