gdd-debug

name	gdd-debug
description	Symptom-driven design debugger with persistent state. Phase 1 builds a feedback loop; Phase 2 hypothesizes. Writes findings to .design/DEBUG.md. Use when a symptom needs systematic, one-variable-at-a-time tracking.
argument-hint	[<symptom description>]
tools	Read, Write, Grep, Glob, AskUserQuestion, Task

{{command_prefix}}debug

Systematic, checkpoint-driven design debugger. Loads framing from ./../reference/debugger-philosophy.md (five principles) and the feedback-loop construction catalog from ./debug-feedback-loops.md (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to .design/DEBUG.md so killed sessions can resume.

Steps

1. Load philosophy + feedback-loop catalog: Read reference/debugger-philosophy.md (five principles) and ./debug-feedback-loops.md (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
2. Symptom: If no symptom argument was passed, ask (AskUserQuestion): "What design symptom are you investigating? (observable only - 'cards look crowded', not 'padding is wrong')"
3. Resume check: Read .design/DEBUG.md if it exists. If there is an open session with no ### Fix Proposal block, ask: "Resume existing session '' or start a new one?"
4. Ground truth load: Read .design/DESIGN-PLAN.md (goals), .design/STATE.md <decisions> block (D-XX items), and any source files pointed at by the symptom.
5. Phase 1 - Build a feedback loop: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See ./debug-feedback-loops.md for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.
6. Optional rendered-output check: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
7. Phase 2 - Investigation loop (one hypothesis at a time) - for each step:

   • Form one hypothesis (one variable).

   • Investigate (read files, grep, measure). Re-run the Phase 1 feedback loop to confirm the hypothesis pinpoints the symptom.

   • Append to .design/DEBUG.md:

     ## <symptom> — <date>
     ### Hypothesis <N>
     ### Investigation
     ### Finding
     

   • Ask (AskUserQuestion): "Continue investigating? (yes / found it / dead end)"

8. When found: Write ### Fix Proposal block with a concrete patch description. Re-run the Phase 1 loop to confirm the fix flips it from fail to pass. Ask: "Create a todo with {{command_prefix}}todo add, or execute the fix now?"

Do Not

• Do not change multiple variables at once.
• Do not modify global tokens to fix a single component without explicit user approval.
• Do not close the DEBUG.md session without a finding (mark as "dead end" if abandoned).

DEBUG COMPLETE