Files
msd-core/.planning/phases/13-debug-agent/13-01-PLAN.md
Lex Christopherson 20bb2101bd docs(13): create phase plans for dedicated debug agent
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>
2026-01-15 16:08:32 -06:00

250 lines
7.6 KiB
Markdown

---
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>