msd-core/.planning/phases/13-debug-agent/13-01-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	01	execute	1		agents/gsd-debugger.md	true	truths artifacts key_links 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 path provides min_lines contains agents/gsd-debugger.md Complete debugging expertise agent 600 scientific method from to via pattern agents/gsd-debugger.md templates/DEBUG.md references debug file structure DEBUG.md

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.

<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

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

Task 1: Create gsd-debugger agent file agents/gsd-debugger.md Create `agents/gsd-debugger.md` following the pattern from gsd-executor/gsd-verifier.

Structure:

---
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) 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 gsd-debugger.md contains complete debugging expertise in consolidated form, following gsd-executor/gsd-verifier pattern

Task 2: Verify agent completeness against source material agents/gsd-debugger.md 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. Review checklist shows all critical concepts present in gsd-debugger.md Agent contains all debugging expertise from source files

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

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

After completion, create `.planning/phases/13-debug-agent/13-01-SUMMARY.md`