debug-session

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

1. Ask the user: "What is the expected behavior vs actual behavior?"
2. Get the exact error message or failing test output
3. Get minimal reproduction steps
4. Write a one-line problem statement

Step 2: Hypothesis

1. List up to 3 possible root causes
2. For each: "If [cause], then I expect to see [evidence]"
3. Prioritize by likelihood × verification cost
4. Read source code — do NOT guess paths or behavior

Step 3: Verification

1. Check each hypothesis using bash (run the failing command, read relevant files)
2. For each: report "Confirmed: [cause]" or "Rejected: [cause]"
3. If all hypotheses rejected, go back to Step 2 with broader scope

Step 4: Fix

1. Smallest possible change to confirm the fix
2. One fix at a time
3. Verify after each fix (re-run failing test/command)
4. 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]