| name | debugging-systematic |
| description | Apply systematic root cause analysis and debugging methodologies to diagnose and fix bugs, test failures, and unexpected behavior. Use when encountering production issues, investigating test failures, diagnosing performance problems, tracing error sources through call stacks, analyzing logs and stack traces, reproducing inconsistent bugs, debugging race conditions, investigating memory leaks, or applying scientific method to problem-solving before proposing fixes. |
| context | fork |
| agent | debugger |
| hooks | {"Stop":[{"type":"prompt","prompt":"Did you identify the root cause with evidence before proposing a fix? Verify you have reproduction steps and a clear explanation of WHY the bug occurred.","once":true}]} |
Systematic Debugging
This skill activates the debugger agent in a forked context for focused, systematic root cause analysis.
When to Use
- Bug reports or unexpected behavior
- Test failures (especially intermittent ones)
- Performance regressions
- Error traces that need investigation
- Any situation where you need to understand WHY something is broken before fixing it
What the Debugger Agent Does
The debugger agent follows a strict investigation-first methodology:
Phase 1: Investigation (BEFORE any fixes)
- Reproduce the issue — Get a reliable reproduction
- Gather evidence — Logs, stack traces, git blame, recent changes
- Trace data flow — Follow the data from entry to failure point
- Identify root cause — Find WHERE and WHY the bug occurs
- Document findings — Clear explanation with evidence
Phase 2: Fix (AFTER root cause is confirmed)
- Write a failing test — Proves the bug exists
- Implement minimal fix — Fix at the source, not the symptom
- Verify the test passes — Confirms the fix works
- Check for regressions — Run full test suite
Key Principles
- Investigate before fixing — Never propose a fix without understanding the root cause
- Evidence over intuition — Every conclusion needs supporting evidence
- Fix at the source — Don't patch symptoms, fix the actual cause
- One bug at a time — Focus on a single issue per investigation
Usage
/debugging-systematic "Tests in auth module are failing intermittently"
Or simply:
/debugging-systematic
The agent will ask for context about the issue to investigate.
Integration
This skill wraps the debugger agent defined in agents/debugger.md. The agent has access to Read, Edit, Grep, Glob, Bash, and WebFetch tools, and runs with permissionMode: bypassPermissions for autonomous investigation.
The debugger agent's Stop hook verifies that root cause analysis was completed with evidence before allowing exit.
