// Root cause debugging before fixes. Use when investigating bugs, diagnosing test failures, troubleshooting unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline.
| name | debug |
| description | Root cause debugging before fixes. Use when investigating bugs, diagnosing test failures, troubleshooting unexpected behavior, or when previous fix attempts failed. Enforces investigate-first discipline. |
| allowed-tools | * |
Find root cause before fixing. Symptom fixes are failure.
Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Answer IN ORDER. Stop at first match:
Use especially when:
Complete each phase before proceeding.
BEFORE attempting ANY fix:
Don't skip past errors. They often contain the exact solution.
- Full stack trace (note line numbers, file paths)
- Error codes and messages
- Warnings that preceded the error
When the error mentions a library/framework symbol (a function, class, or module from a dependency) — read the installed version's docs before forming a hypothesis. Signatures, defaults, and deprecation behavior change between versions; training memory may describe a different version than the one running. Check package.json / lockfile, then the source wired up (Context7, official docs, README at the pinned ref).
| Can reproduce? | Action |
|---|---|
| Yes, every time | Proceed to step 3 |
| Sometimes | Gather more data - when does it happen vs not? |
| Never | Cannot debug what you cannot reproduce - gather logs |
When repro hinges on user-only context (env, timeline, "what were you doing"), call /elicit — its multiple-choice format constrains the answer space better than open prompts.
git diff HEAD~5 # Recent code changes
git log --oneline -10 # Recent commits
What changed that could cause this? Dependencies? Config? Environment?
When error is deep in call stack:
Symptom: Error at line 50 in utils.js
↑ Called by handler.js:120
↑ Called by router.js:45
↑ Called by app.js:10 ← ROOT CAUSE: bad input here
Technique:
When system has multiple layers (API → service → database):
# Log at EACH boundary before proposing fixes
echo "=== Layer 1 (API): request=$REQUEST ==="
echo "=== Layer 2 (Service): input=$INPUT ==="
echo "=== Layer 3 (DB): query=$QUERY ==="
Run once to find WHERE it breaks. Then investigate that layer.
Locate similar working code in same codebase. What works that's similar?
| Working code | Broken code | Could this matter? |
|---|---|---|
| Uses async/await | Uses callbacks | Yes - timing |
| Validates input | No validation | Yes - bad data |
List ALL differences. Don't assume "that can't matter."
Write it down: "I think X is the root cause because Y"
Be specific:
| Rule | Why |
|---|---|
| ONE change at a time | Isolate what works |
| Smallest possible change | Avoid side effects |
| Don't bundle fixes | Can't tell what helped |
| Result | Action |
|---|---|
| Fixed | Phase 4 (verify) |
| Not fixed | NEW hypothesis (return to 3.1) |
| Partially fixed | Found one issue, continue investigating |
Before proceeding to Phase 4:
subtype: bug-investigatedExample:
## Root Cause
Connection pool exhausted because connections aren't released in error path.
Confirmed by adding pool logging - saw connections increment without decrement on errors.
Before fixing, write test that fails due to the bug:
it('handles empty input without crashing', () => {
// This test should FAIL before fix, PASS after
expect(() => processData('')).not.toThrow();
});
End the fix report with Next: on its own line — imperative, name what's now (commit message to use, ticket to mark done, follow-up issue to open for related debt the investigation surfaced). A debug session that ends without naming the next move is incomplete.
Examples:
fix(auth): release pool connection in error path, mark ticket 234 done.src/auth.ts:88.| Fix attempts | Action |
|---|---|
| 1-2 | Return to Phase 1 with new information |
| 3+ | STOP - Question architecture (see below) |
Pattern indicating architectural problem:
STOP and ask:
If you catch yourself thinking:
| Thought | Reality |
|---|---|
| "Quick fix for now, investigate later" | Investigate NOW or you never will |
| "Just try changing X" | That's guessing, not debugging |
| "I'll add multiple fixes and test" | Can't isolate what worked |
| "I don't fully understand but this might work" | You need to understand first |
| "One more fix attempt" (after 2+ failures) | 3+ failures = wrong approach |
ALL mean: STOP. Return to Phase 1.
| Phase | Key Question | Success Criteria |
|---|---|---|
| 1. Root Cause | "WHY is this happening?" | Understand cause, not just symptom |
| 2. Pattern | "What's different from working code?" | Identified key differences |
| 3. Hypothesis | "Is my theory correct?" | Confirmed or formed new theory |
| 4. Implementation | "Does the fix work?" | Test passes, issue resolved |
Voice: plainspoken and concise — write to be scanned.
Deep code review with web research. Use when double-checking code against latest docs, verifying dependency versions, or reviewing security concerns. Complements automatic quality hook with ecosystem verification.
Run comprehensive code audit for architecture, dead code, and test quality. Use when reviewing overall codebase health, checking for architectural violations, or before marking a feature complete.
Safeword semver commitment and release discipline. Use when bumping versions, cutting releases, deciding what goes in a patch vs minor vs major, or reviewing changelog entries. Also use when auto-upgrade logic needs to know what's safe to apply silently.
Behavior-first feature development — use when building new capabilities, continuing feature work, or when work introduces new state or multiple user flows. Discovers desired behavior through examples and scenarios before implementation. Do NOT use for bug fixes, typos, or small isolated changes.
Explore and debate options with fresh documentation and research before committing. Use when facing a real decision with multiple plausible approaches — library/framework choice, architecture call, API or schema design, algorithm selection, or any communication / strategy call where being wrong has cost. Enumerates relevant research domains, looks up current docs and evidence-based methods, weighs options on correctness and elegance, resists bloat. Do NOT use for divergent ideation (brainstorm), extracting user intent (elicit), or reviewing already-written code (quality-review).
Use when completing a TDD step and wanting a quality check. Reviews test quality after RED, implementation correctness after GREEN, and scenario completeness after REFACTOR.