golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs(13): create phase plans for dedicated debug agent

Browse Source 
Phase 13: Dedicated Debug Agent - 3 plans in 2 waves

Wave 1:
- 13-01: Create gsd-debugger agent with consolidated debugging expertise

Wave 2 (parallel):
- 13-02: Refactor /gsd:debug to thin orchestrator
- 13-03: Deprecate debugging reference files with agent pointers

Goal: ~95% context reduction in orchestrator (2,400 → 150 lines)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-15 16:08:32 -06:00
parent 2b1fd968a7
commit 20bb2101bd
3 changed files with 762 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
.planning/phases/13-debug-agent/13-01-PLAN.md Normal file
View File

@@ -0,0 +1,249 @@
---
phase: 13-debug-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- agents/gsd-debugger.md
autonomous: true
must_haves:
truths:
- "gsd-debugger agent contains all debugging expertise"
- "Agent can execute investigations autonomously"
- "Agent handles all checkpoint types (human-verify, decision, human-action)"
- "Agent follows scientific method for hypothesis testing"
artifacts:
- path: "agents/gsd-debugger.md"
provides: "Complete debugging expertise agent"
min_lines: 600
contains: "scientific method"
key_links:
- from: "agents/gsd-debugger.md"
to: "templates/DEBUG.md"
via: "references debug file structure"
pattern: "DEBUG\\.md"
---
<objective>
Create the gsd-debugger agent with all debugging expertise consolidated.
Purpose: Move ~2,400 lines of debugging methodology from orchestrator context into a dedicated agent file, following the gsd-executor/gsd-verifier pattern.
Output: `agents/gsd-debugger.md` containing complete debugging expertise.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Existing debugging content to consolidate:
@get-shit-done/workflows/debug.md
@get-shit-done/templates/debug-subagent-prompt.md
@get-shit-done/references/debugging/debugging-mindset.md
@get-shit-done/references/debugging/hypothesis-testing.md
@get-shit-done/references/debugging/investigation-techniques.md
@get-shit-done/references/debugging/verification-patterns.md
@get-shit-done/references/debugging/when-to-research.md
# Agent pattern reference:
@agents/gsd-executor.md
@agents/gsd-verifier.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create gsd-debugger agent file</name>
<files>agents/gsd-debugger.md</files>
<action>
Create `agents/gsd-debugger.md` following the pattern from gsd-executor/gsd-verifier.
**Structure:**
```yaml
---
name: gsd-debugger
description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
color: orange
---
```
**Sections to include (consolidate from references):**
1. `<role>` - What this agent does, when it's spawned, core responsibilities
2. `<philosophy>` - From debugging-mindset.md:
- User = reporter, Claude = investigator
- Meta-debugging awareness (debugging your own code)
- Foundation principles (observable facts, verify assumptions)
- Cognitive biases to avoid
3. `<hypothesis_testing>` - From hypothesis-testing.md:
- Falsifiability requirement
- How to form specific, testable hypotheses
- Experimental design framework
- Evidence quality (strong vs weak)
- Decision point criteria
- Recovery from wrong hypotheses
4. `<investigation_techniques>` - From investigation-techniques.md:
- Binary search / divide and conquer
- Rubber duck debugging
- Minimal reproduction
- Working backwards
- Differential debugging
- Observability first
- Comment out everything
- Git bisect
5. `<verification_patterns>` - From verification-patterns.md:
- What "verified" means (5 criteria)
- Reproduction verification
- Regression testing
- Environment verification
- Stability testing
- Verification checklist
6. `<research_vs_reasoning>` - From when-to-research.md:
- Research signals (error messages, library behavior, domain gaps)
- Reasoning signals (your code, have all info, logic errors)
- How to research (web search, Context7, GitHub issues)
- Balance between research and reasoning
7. `<debug_file_protocol>` - From debug.md workflow:
- File structure and sections
- Update rules (OVERWRITE vs APPEND)
- Status transitions
- Current Focus maintenance
- Evidence and Eliminated tracking
8. `<execution_flow>` - Adapted from debug.md workflow:
- check_active_session
- create_debug_file (if new session)
- symptom_gathering (if not prefilled)
- investigation_loop
- resume_from_file (if continuing)
- return_diagnosis (if find_root_cause_only)
- fix_and_verify (if find_and_fix)
- archive_session
9. `<checkpoint_behavior>` - From debug-subagent-prompt.md:
- When to return checkpoints
- Checkpoint return format
- Types: human-verify, human-action, decision
- What happens after (fresh continuation agent)
10. `<structured_returns>` - From debug-subagent-prompt.md:
- ROOT CAUSE FOUND format
- DEBUG COMPLETE format
- INVESTIGATION INCONCLUSIVE format
- CHECKPOINT REACHED format
11. `<modes>` - From debug.md workflow:
- symptoms_prefilled: true/false
- goal: find_root_cause_only / find_and_fix
- How each mode affects behavior
12. `<success_criteria>` - Checklist for complete debugging
**Key consolidation principles:**
- Compress verbose explanations into actionable rules
- Remove redundant examples (keep 1-2 best per concept)
- Maintain all key concepts and decision trees
- Target ~700-800 lines (vs ~2,400 original)
</action>
<verify>
File exists at agents/gsd-debugger.md with:
- YAML frontmatter with name, description, tools, color
- All 12 sections present
- At least 600 lines
- No markdown syntax errors
</verify>
<done>
gsd-debugger.md contains complete debugging expertise in consolidated form, following gsd-executor/gsd-verifier pattern
</done>
</task>
<task type="auto">
<name>Task 2: Verify agent completeness against source material</name>
<files>agents/gsd-debugger.md</files>
<action>
Review the created agent against source files to ensure no critical concepts were lost.
**Checklist:**
1. From debugging-mindset.md:
- [ ] Meta-debugging (debugging your own code)
- [ ] Cognitive biases (confirmation, anchoring, availability, sunk cost)
- [ ] Systematic investigation disciplines
- [ ] When to restart
2. From hypothesis-testing.md:
- [ ] Falsifiability principle
- [ ] Experimental design framework (7 steps)
- [ ] Multiple hypothesis comparison
- [ ] Recovery from wrong hypotheses
3. From investigation-techniques.md:
- [ ] All 7+ techniques documented
- [ ] Decision tree for technique selection
4. From verification-patterns.md:
- [ ] 5 criteria for verification
- [ ] All verification patterns
- [ ] Checklist template
5. From when-to-research.md:
- [ ] Research vs reasoning signals
- [ ] Research how-to guide
- [ ] Balance guidance
6. From debug.md workflow:
- [ ] All process steps
- [ ] Debug file update rules
- [ ] Mode handling
7. From debug-subagent-prompt.md:
- [ ] Return formats
- [ ] Checkpoint formats
- [ ] Continuation handling
If any concepts are missing, add them to the appropriate section.
</action>
<verify>
Review checklist shows all critical concepts present in gsd-debugger.md
</verify>
<done>
Agent contains all debugging expertise from source files
</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] agents/gsd-debugger.md exists with proper YAML frontmatter
- [ ] All 12 major sections present
- [ ] File is 600-900 lines (compressed but complete)
- [ ] No critical debugging concepts lost from source material
- [ ] Follows gsd-executor/gsd-verifier structural pattern
</verification>
<success_criteria>
- gsd-debugger.md created with complete debugging expertise
- Agent follows established pattern (frontmatter, role, process steps, success_criteria)
- Consolidation reduces ~2,400 lines to ~700-800 lines
- All critical debugging concepts preserved
</success_criteria>
<output>
After completion, create `.planning/phases/13-debug-agent/13-01-SUMMARY.md`
</output>

366
.planning/phases/13-debug-agent/13-02-PLAN.md Normal file
View File

@@ -0,0 +1,366 @@
---
phase: 13-debug-agent
plan: 02
type: execute
wave: 2
depends_on: ["13-01"]
files_modified:
- commands/gsd/debug.md
- get-shit-done/workflows/debug.md
- get-shit-done/templates/debug-subagent-prompt.md
autonomous: true
must_haves:
truths:
- "/gsd:debug spawns gsd-debugger agent"
- "Command is <150 lines (thin orchestrator)"
- "Workflow file removed or redirects to agent"
- "Debug subagent template simplified"
artifacts:
- path: "commands/gsd/debug.md"
provides: "Thin orchestrator for debugging"
min_lines: 80
contains: "gsd-debugger"
key_links:
- from: "commands/gsd/debug.md"
to: "agents/gsd-debugger.md"
via: "Task spawn with subagent_type"
pattern: "gsd-debugger"
---
<objective>
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.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
<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
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor /gsd:debug to thin orchestrator</name>
<files>commands/gsd/debug.md</files>
<action>
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:**
```yaml
---
name: gsd:debug
description: Systematic debugging with persistent state across context resets
argument-hint: [issue description]
allowed-tools:
- Read
- Bash
- Task
- AskUserQuestion
---
```
**Sections:**
```markdown
<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
```
</context>
<process>
## 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:
```markdown
<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]
</process>
<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.
</action>
<verify>
File exists with deprecation notice.
File is <30 lines.
Points to agents/gsd-debugger.md.
</verify>
<done>
workflows/debug.md deprecated with redirect to agent
</done>
</task>
<task type="auto">
<name>Task 3: Simplify debug-subagent-prompt.md template</name>
<files>get-shit-done/templates/debug-subagent-prompt.md</files>
<action>
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:**
```markdown
# 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:**
```python
Task(
prompt=filled_template,
subagent_type="gsd-debugger",
description="Debug {slug}"
)
```
**From diagnose-issues (UAT):**
```python
Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
```
---
## Continuation
For checkpoints, spawn fresh agent with:
```markdown
<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>

147
.planning/phases/13-debug-agent/13-03-PLAN.md Normal file
View File

@@ -0,0 +1,147 @@
---
phase: 13-debug-agent
plan: 03
type: execute
wave: 2
depends_on: ["13-01"]
files_modified:
- get-shit-done/references/debugging/debugging-mindset.md
- get-shit-done/references/debugging/hypothesis-testing.md
- get-shit-done/references/debugging/investigation-techniques.md
- get-shit-done/references/debugging/verification-patterns.md
- get-shit-done/references/debugging/when-to-research.md
autonomous: true
must_haves:
truths:
- "Reference files replaced with pointers to agent"
- "No duplicate content between references and agent"
artifacts:
- path: "get-shit-done/references/debugging/debugging-mindset.md"
provides: "Redirect to gsd-debugger agent"
contains: "gsd-debugger"
key_links:
- from: "get-shit-done/references/debugging/*.md"
to: "agents/gsd-debugger.md"
via: "redirect notice"
pattern: "agents/gsd-debugger"
---
<objective>
Deprecate debugging reference files with pointers to gsd-debugger agent.
Purpose: Eliminate duplicate content. Debugging expertise now lives solely in the agent file.
Output: 5 reference files reduced to redirect notices.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/13-debug-agent/13-01-SUMMARY.md
# Agent that now contains this content:
@agents/gsd-debugger.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Deprecate all debugging reference files</name>
<files>
get-shit-done/references/debugging/debugging-mindset.md
get-shit-done/references/debugging/hypothesis-testing.md
get-shit-done/references/debugging/investigation-techniques.md
get-shit-done/references/debugging/verification-patterns.md
get-shit-done/references/debugging/when-to-research.md
</files>
<action>
Replace each file with a redirect notice pointing to the agent.
**Template for each file (~15 lines):**
```markdown
# [Original Title] (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<[relevant_section_name]>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.
```
**Specific mappings:**
1. `debugging-mindset.md` → `<philosophy>` section
2. `hypothesis-testing.md` → `<hypothesis_testing>` section
3. `investigation-techniques.md` → `<investigation_techniques>` section
4. `verification-patterns.md` → `<verification_patterns>` section
5. `when-to-research.md` → `<research_vs_reasoning>` section
Each file should be ~15 lines with the redirect notice.
</action>
<verify>
All 5 files exist with redirect notices.
Each file is <20 lines.
Each file points to agents/gsd-debugger.md.
Each file specifies the relevant section in the agent.
</verify>
<done>
All debugging reference files deprecated with agent pointers
</done>
</task>
<task type="auto">
<name>Task 2: Update installer to include agents directory</name>
<files>bin/install.js</files>
<action>
Verify that `bin/install.js` copies the `agents/` directory during installation.
Check if agents/ is already included. If not, add it to the copy list.
**Expected behavior:**
- `agents/*.md` files copied to `~/.claude/agents/` (global) or `.claude/agents/` (local)
- Similar to how `commands/`, `get-shit-done/`, etc. are handled
**If already handled:** No changes needed, note in summary.
**If not handled:** Add agents directory to the copy list.
</action>
<verify>
Run: `node bin/install.js --local --dry-run` (if dry-run exists) or check install.js code
Confirm agents/ directory will be copied on install.
</verify>
<done>
Installer copies agents/ directory
</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] All 5 debugging reference files are <20 lines each
- [ ] All 5 files point to agents/gsd-debugger.md
- [ ] Each file specifies the section in the agent
- [ ] Installer handles agents/ directory
</verification>
<success_criteria>
- Debugging reference files deprecated
- No duplicate content between references and agent
- Installer copies agents directory
</success_criteria>
<output>
After completion, create `.planning/phases/13-debug-agent/13-03-SUMMARY.md`
</output>