| name | debug-session |
| description | Structured debugging workflow. Use when code fails, tests break, errors are unclear, or debugging needs a systematic approach. Define problem → hypothesize → verify → fix.
|
| disable-model-invocation | false |
| allowed-tools | Read, Bash(git*), Bash(cat*), Bash(grep*), Glob, Grep |
Process
Step 1: Problem Definition
- Ask the user: "What is the expected behavior vs actual behavior?"
- Get the exact error message or failing test output
- Get minimal reproduction steps
- Write a one-line problem statement
Step 2: Hypothesis
- List up to 3 possible root causes
- For each: "If [cause], then I expect to see [evidence]"
- Prioritize by likelihood × verification cost
- Read source code — do NOT guess paths or behavior
Step 3: Verification
- Check each hypothesis using bash (run the failing command, read relevant files)
- For each: report "Confirmed: [cause]" or "Rejected: [cause]"
- If all hypotheses rejected, go back to Step 2 with broader scope
Step 4: Fix
- Smallest possible change to confirm the fix
- One fix at a time
- Verify after each fix (re-run failing test/command)
- If 3 consecutive fixes fail → rollback (
git checkout -- files) and restart
Output Format
## Diagnosis
**Problem**: [one-line problem statement]
**Root Cause**: [confirmed cause]
**Evidence**: [what you observed]
## Fix
**Change**: [what was changed and why]
**Verification**: [how you confirmed it works]
**Side Effects**: [any risks or related areas affected]
