gsd:debug

Orchestrator role: Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.

Why subagent: Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.

Flags:

• --diagnose — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.

Subcommands:

• list — List all active debug sessions
• status <slug> — Print full summary of a session without spawning an agent
• continue <slug> — Resume a specific session by slug

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

• gsd-debug-session-manager — manages debug checkpoint/continuation loop in isolated context
• gsd-debugger — investigates bugs using scientific method </available_agent_types>

Parse subcommands and flags from $ARGUMENTS BEFORE the active-session check:

• If $ARGUMENTS starts with "list": SUBCMD=list, no further args
• If $ARGUMENTS starts with "status ": SUBCMD=status, SLUG=remainder (trim whitespace)
• If $ARGUMENTS starts with "continue ": SUBCMD=continue, SLUG=remainder (trim whitespace)
• If $ARGUMENTS contains --diagnose: SUBCMD=debug, diagnose_only=true, strip --diagnose from description
• Otherwise: SUBCMD=debug, diagnose_only=false

Check for active sessions (used for non-list/status/continue flows):

ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5

0. Initialize Context

INIT=$(gsd-sdk query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Extract commit_docs from init JSON. Resolve debugger model:

debugger_model=$(gsd-sdk query resolve-model gsd-debugger 2>/dev/null | jq -r '.model' 2>/dev/null || true)

Read TDD mode from config:

TDD_MODE=$(gsd-sdk query config-get workflow.tdd_mode 2>/dev/null | jq -r 'if type == "boolean" then tostring else . end' 2>/dev/null || echo "false")