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.

Check for active sessions:

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

0. Initialize Context

INIT=$(node {{PLATFORM_ROOT}}/get-shit-done/bin/gsd-tools.cjs state load)

Extract commit_docs from init JSON. Resolve debugger model:

DEBUGGER_MODEL=$(node {{PLATFORM_ROOT}}/get-shit-done/bin/gsd-tools.cjs resolve-model gsd-debugger --raw)

1. Check Active Sessions

If active sessions exist AND no $ARGUMENTS:

• List sessions with status, hypothesis, next action

• User picks number to resume OR describes new issue

If $ARGUMENTS provided OR user describes new issue:

• Continue to symptom gathering

2. Gather Symptoms (if new issue)

Use AskUserQuestion for each:

• Expected behavior - What should happen?

• Actual behavior - What happens instead?

• Error messages - Any errors? (paste or describe)

• Timeline - When did this start? Ever worked?

• Reproduction - How do you trigger it?

After all gathered, confirm ready to investigate.

3. Spawn gsd-debugger Agent

Fill prompt and spawn:

<objective> Investigate issue: {slug}

Summary: {trigger} </objective>

<symptoms> expected: {expected} actual: {actual} errors: {errors} reproduction: {reproduction} timeline: {timeline} </symptoms>

<mode> symptoms_prefilled: true goal: find_and_fix </mode>

<debug_file> Create: .planning/debug/{slug}.md </debug_file>

Task( prompt=filled_prompt, subagent_type="gsd-debugger", model="{debugger_model}", description="Debug {slug}" )

4. Handle Agent Return

If ## ROOT CAUSE FOUND :

• Display root cause and evidence summary

• Offer options:

• "Fix now" - spawn fix subagent

• "Plan fix" - suggest {{COMMAND_PREFIX}}plan-phase --gaps

• "Manual fix" - done

If ## CHECKPOINT REACHED :

• Present checkpoint details to user

• Get user response

• If checkpoint type is human-verify :

• If user confirms fixed: continue so agent can finalize/resolve/archive

• If user reports issues: continue so agent returns to investigation/fixing

• Spawn continuation agent (see step 5)

If ## INVESTIGATION INCONCLUSIVE :

• Show what was checked and eliminated

• Offer options:

• "Continue investigating" - spawn new agent with additional context

• "Manual investigation" - done

• "Add more context" - gather more symptoms, spawn again

5. Spawn Continuation Agent (After Checkpoint)

When user responds to checkpoint, spawn fresh agent:

<objective> Continue debugging {slug}. Evidence is in the debug file. </objective>

<prior_state> <files_to_read>

• .planning/debug/{slug}.md (Debug session state) </files_to_read> </prior_state>

<checkpoint_response> Type: {checkpoint_type} Response: {user_response} </checkpoint_response>

<mode> goal: find_and_fix </mode>

Task( prompt=continuation_prompt, subagent_type="gsd-debugger", model="{debugger_model}", description="Continue debug {slug}" )

<success_criteria>

• Active sessions checked

• Symptoms gathered (if new)

• gsd-debugger spawned with context

• Checkpoints handled correctly

• Root cause confirmed before fixing </success_criteria>