msd-core/.planning/phases/13-debug-agent/13-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
13-debug-agent	02	execute	2	13-01	commands/gsd/debug.md get-shit-done/workflows/debug.md get-shit-done/templates/debug-subagent-prompt.md	true	truths artifacts key_links /gsd:debug spawns gsd-debugger agent Command is <150 lines (thin orchestrator) Workflow file removed or redirects to agent Debug subagent template simplified path provides min_lines contains commands/gsd/debug.md Thin orchestrator for debugging 80 gsd-debugger from to via pattern commands/gsd/debug.md agents/gsd-debugger.md Task spawn with subagent_type gsd-debugger

Refactor /gsd:debug command to thin orchestrator that spawns gsd-debugger agent.

Purpose: Reduce orchestrator context from ~2,400 lines to ~100-150 lines. Debugging expertise now lives in the agent.

Output: Streamlined command, deprecated workflow, simplified template.

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/13-debug-agent/13-01-SUMMARY.md

Current files to refactor:

@commands/gsd/debug.md @get-shit-done/workflows/debug.md @get-shit-done/templates/debug-subagent-prompt.md

Agent created in previous plan:

@agents/gsd-debugger.md

Task 1: Refactor /gsd:debug to thin orchestrator commands/gsd/debug.md Rewrite `commands/gsd/debug.md` as a thin orchestrator (~100-150 lines).

Orchestrator responsibilities:

1. Check for active debug sessions
2. Gather symptoms from user (if new issue)
3. Spawn gsd-debugger agent with context
4. Handle checkpoint returns
5. Spawn continuation agents as needed

Structure:

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

Sections:

<objective>
Debug issues using scientific method with subagent isolation.

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

**Why subagent:** Investigation burns context fast. Fresh 200k context per investigation. Main context stays lean.
</objective>

<context>
User's issue: $ARGUMENTS

Check for active sessions:
```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5

1. Check Active Sessions

[Simplified from current - just list and route]

2. Gather Symptoms (if new issue)

[Keep current AskUserQuestion flow - this stays in main context]

3. Spawn gsd-debugger Agent

Fill prompt and spawn:

<objective>
Investigate issue: {trigger}
</objective>

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

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

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

4. Handle Agent Return

[Keep current routing logic for ROOT CAUSE FOUND, CHECKPOINT REACHED, INCONCLUSIVE]

5. Spawn Continuation (After Checkpoint)

[Keep current continuation spawning, but simpler]

<success_criteria>

• Active sessions checked
• Symptoms gathered (if new)
• gsd-debugger spawned with context
• Checkpoints handled correctly
• Root cause confirmed before fixing </success_criteria>

**Key changes:**
- Remove @~/.claude/get-shit-done/workflows/debug.md reference
- Remove @~/.claude/get-shit-done/references/debugging/*.md references
- Use `subagent_type="gsd-debugger"` instead of `subagent_type="general-purpose"`
- All debugging expertise is now IN the agent, not loaded by orchestrator
  </action>
  <verify>
File is <150 lines.
References gsd-debugger as subagent_type.
Does NOT reference workflows/debug.md or references/debugging/*.md.
  </verify>
  <done>
/gsd:debug is thin orchestrator that spawns gsd-debugger agent
  </done>
</task>

<task type="auto">
  <name>Task 2: Deprecate workflows/debug.md</name>
  <files>get-shit-done/workflows/debug.md</files>
  <action>
Replace `get-shit-done/workflows/debug.md` with a redirect notice.

**New content (~20 lines):**

```markdown
# Debug Workflow (DEPRECATED)

This workflow has been consolidated into the `gsd-debugger` agent.

**Location:** `agents/gsd-debugger.md`

**Reason:** The gsd-debugger agent contains all debugging expertise. Loading a separate workflow into orchestrator context was wasteful.

**Migration:**
- `/gsd:debug` now spawns `gsd-debugger` agent directly
- All debugging methodology lives in the agent file
- Templates remain at `get-shit-done/templates/DEBUG.md`

See `agents/gsd-debugger.md` for debugging expertise.

This preserves the file for git history but makes it clear the content moved. File exists with deprecation notice. File is <30 lines. Points to agents/gsd-debugger.md. workflows/debug.md deprecated with redirect to agent

Task 3: Simplify debug-subagent-prompt.md template get-shit-done/templates/debug-subagent-prompt.md Simplify `get-shit-done/templates/debug-subagent-prompt.md` since the agent now contains the expertise.

Current state: ~355 lines with embedded execution context, checkpoint formats, investigation protocol.

New state: ~60-80 lines - just placeholders and context injection.

New structure:

# Debug Subagent Prompt Template

Template for spawning gsd-debugger agent. The agent contains all debugging expertise - this template provides problem context only.

---

## Template

```markdown
<objective>
Investigate issue: {issue_id}

**Summary:** {issue_summary}
</objective>

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

<mode>
symptoms_prefilled: {true_or_false}
goal: {find_root_cause_only | find_and_fix}
</mode>

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

---

Placeholders

Placeholder	Source	Example
{issue_id}	Orchestrator-assigned	auth-screen-dark
{issue_summary}	User description	Auth screen is too dark
{expected}	From symptoms	See logo clearly
{actual}	From symptoms	Screen is dark
{errors}	From symptoms	None in console
{reproduction}	From symptoms	Open /auth page
{timeline}	From symptoms	After recent deploy
{goal}	Orchestrator sets	find_and_fix
{slug}	Generated	auth-screen-dark

---

Usage

From /gsd:debug:

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

From diagnose-issues (UAT):

Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")

---

Continuation

For checkpoints, spawn fresh agent with:

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

<prior_state>
Debug file: @.planning/debug/{slug}.md
</prior_state>

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

<mode>
goal: {goal}
</mode>

**Key changes:**
- Remove embedded execution_context references (agent has this)
- Remove checkpoint_behavior section (agent has this)
- Remove return_formats section (agent has this)
- Remove investigation_protocol section (agent has this)
- Keep only: template, placeholders, usage examples, continuation format
  </action>
  <verify>
File is <100 lines.
Contains template with placeholders.
Does NOT contain execution_context, checkpoint_behavior, or investigation_protocol sections.
References subagent_type="gsd-debugger".
  </verify>
  <done>
debug-subagent-prompt.md simplified to context injection only
  </done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] commands/gsd/debug.md is <150 lines
- [ ] commands/gsd/debug.md uses subagent_type="gsd-debugger"
- [ ] commands/gsd/debug.md does NOT load workflow or reference files
- [ ] workflows/debug.md is deprecated redirect (<30 lines)
- [ ] templates/debug-subagent-prompt.md is <100 lines
- [ ] All files reference the agent, not embedded expertise
</verification>

<success_criteria>

- /gsd:debug refactored to thin orchestrator
- Context usage reduced from ~2,400 to ~150 lines in orchestrator
- workflows/debug.md deprecated with pointer to agent
- debug-subagent-prompt.md simplified to context-only
</success_criteria>

<output>
After completion, create `.planning/phases/13-debug-agent/13-02-SUMMARY.md`
</output>