debug

Structured Debugging

Find and fix bugs systematically using evidence, never guessing. Implements the debugging protocol defined in CLAUDE.md.

---

Auto Mode

Auto Mode suppresses confirmation prompts and proceed-pauses — not the one clarifying question that can matter here: if the symptom isn't reproducible and the exact error/repro steps aren't given, ask for them (debugging the wrong symptom wastes the whole effort). Once you can reproduce, proceed: fix immediately after the root cause is found, surface assumptions inline, and treat course-corrections as normal input. Don't loop on trivia.

---

The Job

Follow the 4-step protocol strictly. Do NOT skip steps.

---

Step 1: REPRODUCE

• Get the exact error message, stack trace, or unexpected behavior
• Find minimal reproduction steps
• Identify: when did it last work? What changed since?
• If the bug is intermittent, identify conditions that trigger it
• Establish baseline: what is the EXPECTED behavior?

Output: "The bug is [X]. Expected [Y]. Triggered by [Z]."

---

Step 2: HYPOTHESIZE

• Form 2-3 hypotheses based on evidence (not intuition)
• Rank by likelihood
• For each, state what evidence would confirm or deny it

If stuck gathering evidence: use @researcher agent to search the codebase for related patterns, recent changes, or similar bugs.

Output:

H1 (most likely): [hypothesis] — confirm by [check]
H2: [hypothesis] — confirm by [check]
H3: [hypothesis] — confirm by [check]

---

Step 3: ISOLATE

• Test hypotheses one at a time, most likely first
• Add targeted logging or read code at suspect locations
• Narrow to the exact line/condition causing the failure
• DO NOT fix multiple things at once

Output: "Root cause: [exact cause] at [file:line]"

---

Step 4: FIX & VERIFY

• Apply the minimal targeted fix
• Write a regression test (fails without fix, passes with fix)
• Run ALL quality gates (as defined in CLAUDE.md):
  1. Typecheck passes
  2. Lint passes
  3. All tests pass
  4. No regressions
• Remove any debug logging added in Step 3

Output: "Fixed [root cause]. Added test [name]. All quality gates pass."

---

Rules

• Never guess. Always gather evidence first.
• State your hypothesis BEFORE each investigation step.
• One hypothesis at a time. Don't shotgun-fix.
• If stuck after 3 attempts: step back, re-examine assumptions, use @researcher for context.
• Always write a regression test.

---

Agent Routing

Step	Agent	Purpose
HYPOTHESIZE	MUST spawn @researcher when >5 files may be involved	Search codebase for related patterns, recent changes, similar bugs in parallel
FIX	Always spawn @test-writer for low-coverage areas	Ensure regression test coverage around the fix, especially in undertested code
Post-fix	MUST spawn @security-auditor for security-sensitive fixes	Validate that fixes touching auth, input handling, or data access are safe

Rule: Never explore the codebase inline when @researcher can do it in parallel.

---

Feeding Back Into the Workflow

Once the root cause is found (end of Step 3), decide how the fix re-enters the workflow spine:

• Fix now (default). Apply the fix immediately, write the regression test, run quality gates, commit. Best for small, well-understood bugs.
• Defer as a work unit. When the fix is larger or should be planned alongside other work, append a new work unit to .planning/missions/<mission_id>/ROADMAP.md describing the bug and root cause, then pick it up later with /brief N. The brief captures the why + what, /plan N breaks it down, and /build N ships it.

In Auto Mode, fix now unless the bug clearly needs design work — then append a work unit and say so inline.

Appended work-unit note (for .planning/missions/<mission_id>/ROADMAP.md):

- Fix: [root cause summary] — bug found by /debug.
  Root cause: [cause] at [file:line]. Needs: regression test + minimal fix.

---

Related

• @researcher — use for gathering context when stuck
• @test-writer — use for comprehensive test coverage after the fix
• /refactor — if the fix reveals structural issues, refactor separately

Spine: find the root cause, then either fix now (/ship) or append a work unit to .planning/missions/<mission_id>/ROADMAP.md and resume the spine at /brief N.