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>
250 lines
7.6 KiB
Markdown
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>
|