Our review
A structured debugging strategy using a decision tree and common root cause table to systematically reproduce, isolate, and trace bugs.
Strengths
- Provides a clear decision tree for common debugging scenarios
- Includes a table mapping symptoms to likely causes and checks
- Warns against anti-patterns like shotgun debugging and fixing symptoms
Limitations
- Assumes ability to reproduce the bug, which may not always be possible
- Root cause table is not exhaustive; novel bugs may require deeper analysis
- Requires basic familiarity with debugging tools (logging, breakpoints, heap snapshots)
When investigating a bug, crash, or unexpected behavior to follow a methodical diagnostic process.
When the problem is already well-understood and a known fix can be directly applied, or for exploratory code understanding without a specific error.
Security analysis
SafeThe skill provides a debugging guide with a decision tree, common root causes, and strategies. It only allows Bash and Read, which are safe in this context. There are no destructive commands, network calls, or data exfiltration risks.
No concerns found
Examples
I have a test that passes locally but fails intermittently in CI. It's a race condition, so I need to add timestamps to logs and isolate the issue. Use the debugging decision tree and root cause table to help me diagnose and fix it.I'm getting a 'Cannot read property of null' error. I need to trace the data flow backwards from the error point to find where the null value originates. Apply the systematic debugging strategy with binary search isolation.My application's memory usage keeps growing over time. I suspect unclosed resources or event listener leaks. Use the debugging guide to take heap snapshots before and after, identify the leak, and fix it.name: debugging description: Systematic diagnostic strategy with decision tree for reproducing, isolating, and tracing bugs. Use when investigating bugs, crashes, or unexpected behavior. Complements systematic-debugging workflow with concrete diagnostic patterns. metadata: version: "1.0" allowed-tools: Bash Read
Debugging
Decision Tree
Bug reported → Can you reproduce it?
├─ Yes → Is it consistent?
│ ├─ Yes → Add breakpoint/logging at suspected location → Trace
│ └─ No (intermittent) → Race condition or timing issue → Add timestamps to logs
└─ No → Check environment differences
├─ Works locally, fails in CI → Compare env vars, paths, timezone
├─ Works for others, fails for me → Check local config, versions, OS
└─ Cannot reproduce anywhere → Get reproduction steps from reporter
Common Root Causes
| Symptom | Likely Cause | Check | |---------|-------------|-------| | Works locally, fails in CI | Env vars, file paths, timezone | Compare environments | | Intermittent failure | Race condition, flaky test, timeout | Add logging, increase timeout | | Null/undefined error | Missing null check, async ordering | Trace data flow backwards | | Memory growing | Unclosed resources, event listener leaks | Heap snapshot before/after | | Slow response | N+1 queries, missing index, large payload | Profile, check query count | | CORS error | Missing headers, wrong origin, preflight | Check server response headers | | 403/401 | Token expired, wrong scope, missing header | Inspect request headers | | "It worked yesterday" | Dependency update, config change, data change | Check git log, dep diff, recent deploys | | Passes alone, fails in suite | Shared state between tests, order dependency | Run in isolation, check setup/teardown |
Strategy
- Reproduce - Get a reliable reproduction case first
- Isolate - Binary search: remove half the variables, see if it still fails
- Trace - Follow data flow from input to failure point
- Verify - Fix should explain the symptom, not just suppress it
Anti-Patterns
- Shotgun debugging - Changing random things hoping it works. Understand first, fix second.
- Fix the symptom - Adding a null check without understanding why it's null. Find the root cause.
- "It works now" - Can't explain why it broke or why the fix works. Keep investigating.
- Printf and pray - Adding one log, running, adding another. Plan your instrumentation.
Next.js App Router Expert
Development
A skill that turns Claude into a Next.js App Router expert.
README Generator
Development
Creates professional and comprehensive README.md files for your projects.
API Documentation Writer
Development
Generates comprehensive API documentation in OpenAPI/Swagger format.