systematic-debugging
A structured 4-phase framework to debug software systematically and avoid guessing.
Install
mkdir -p .claude/skills/systematic-debugging-piyushkghosh && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/10206" && unzip -o skill.zip -d .claude/skills/systematic-debugging-piyushkghosh && rm skill.zipInstalls to .claude/skills/systematic-debugging-piyushkghosh
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.Key capabilities
- →Reproduce issues
- →Isolate sources
- →Perform root cause analysis
- →Verify fixes
How it works
It follows a 4-phase process: reproduction, isolation, root cause analysis (5 Whys), and verification.
Inputs & outputs
When to use systematic-debugging
- →Debugging intermittent production issues
- →Performing root cause analysis on complex bugs
- →Documenting reproduction steps for issue tracking
- →Verifying fixes to prevent regressions
About this skill
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
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
When not to use it
- →When the issue is not reproducible
Limitations
- →Requires consistent reproduction
- →Requires understanding of expected behavior
How it compares
It enforces a structured, evidence-based approach that prevents guessing and ensures the root cause is addressed.
Compared to similar skills
systematic-debugging side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| systematic-debugging (this skill) | 0 | 5mo | Review | Intermediate |
| python-testing-patterns | 77 | 2mo | Review | Intermediate |
| chrome-devtools | 41 | 7mo | Review | Intermediate |
| bats | 9 | 7mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
python-testing-patterns
wshobson
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
chrome-devtools
mrgoonie
Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
bats
OleksandrKucherenko
Bash Automated Testing System (BATS) for TDD-style testing of shell scripts. Use when: (1) Writing unit or integration tests for Bash scripts, (2) Testing CLI tools or shell functions, (3) Setting up test infrastructure with setup/teardown hooks, (4) Mocking external commands (curl, git, docker), (5) Generating JUnit reports for CI/CD, (6) Debugging test failures or flaky tests, (7) Implementing test-driven development for shell scripts.
browser-daemon
noiv
Persistent browser automation via Playwright daemon. Keep a browser window open and send it commands (navigate, execute JS, inspect console). Perfect for interactive debugging, development, and testing web applications. Use when you need to interact with a browser repeatedly without opening/closing it.
performance-profiling
davila7
Performance profiling principles. Measurement, analysis, and optimization techniques.
obsidian-local-dev-loop
jeremylongshore
Configure Obsidian plugin development with hot-reload and fast iteration. Use when setting up development workflow, configuring test vaults, or establishing a rapid development cycle. Trigger with phrases like "obsidian dev loop", "obsidian hot reload", "obsidian development workflow", "develop obsidian plugin".