---
name: forge:debug
description: Systematic debugging with persistent state across context resets
argument-hint: [issue description]
allowed-tools:
  - Read
  - Bash
  - Task
  - AskUserQuestion
---

Debug issue "$ARGUMENTS" using scientific method with subagent isolation.

**Read:** state/STATE.json

**Steps:**

1. Check for active debug sessions in `.planning/debug/`. If found and no args, list sessions for user to resume.

2. Gather symptoms via AskUserQuestion: expected behavior, actual behavior, errors, timeline, reproduction steps.

3. Create `.planning/debug/{slug}.md` with symptom data.

4. Spawn debugger subagent via Task tool with symptoms context. Uses fresh 200k context for investigation.

5. Handle agent return:
   - **ROOT CAUSE FOUND:** Display cause + evidence, offer "Fix now" / "Plan fix" / "Manual fix"
   - **CHECKPOINT REACHED:** Present to user, get response, spawn continuation agent
   - **INCONCLUSIVE:** Show eliminated hypotheses, offer to continue or add context

6. Submit DEBUG_SESSION_CREATED/RESOLVED event. Rename resolved files to `{slug}.resolved.md`.