From 20bb2101bd065a82b86d8c6f0fd551df7ce46cda Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 16:08:32 -0600 Subject: [PATCH] docs(13): create phase plans for dedicated debug agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .planning/phases/13-debug-agent/13-01-PLAN.md | 249 ++++++++++++ .planning/phases/13-debug-agent/13-02-PLAN.md | 366 ++++++++++++++++++ .planning/phases/13-debug-agent/13-03-PLAN.md | 147 +++++++ 3 files changed, 762 insertions(+) create mode 100644 .planning/phases/13-debug-agent/13-01-PLAN.md create mode 100644 .planning/phases/13-debug-agent/13-02-PLAN.md create mode 100644 .planning/phases/13-debug-agent/13-03-PLAN.md diff --git a/.planning/phases/13-debug-agent/13-01-PLAN.md b/.planning/phases/13-debug-agent/13-01-PLAN.md new file mode 100644 index 000000000..1b13d6c70 --- /dev/null +++ b/.planning/phases/13-debug-agent/13-01-PLAN.md @@ -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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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:** +```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. `` - What this agent does, when it's spawned, core responsibilities + +2. `` - 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. `` - 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. `` - 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. `` - From verification-patterns.md: + - What "verified" means (5 criteria) + - Reproduction verification + - Regression testing + - Environment verification + - Stability testing + - Verification checklist + +6. `` - 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. `` - From debug.md workflow: + - File structure and sections + - Update rules (OVERWRITE vs APPEND) + - Status transitions + - Current Focus maintenance + - Evidence and Eliminated tracking + +8. `` - 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. `` - 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. `` - From debug-subagent-prompt.md: + - ROOT CAUSE FOUND format + - DEBUG COMPLETE format + - INVESTIGATION INCONCLUSIVE format + - CHECKPOINT REACHED format + +11. `` - From debug.md workflow: + - symptoms_prefilled: true/false + - goal: find_root_cause_only / find_and_fix + - How each mode affects behavior + +12. `` - 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 + + + + +- 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 + + + +After completion, create `.planning/phases/13-debug-agent/13-01-SUMMARY.md` + diff --git a/.planning/phases/13-debug-agent/13-02-PLAN.md b/.planning/phases/13-debug-agent/13-02-PLAN.md new file mode 100644 index 000000000..eb39f9788 --- /dev/null +++ b/.planning/phases/13-debug-agent/13-02-PLAN.md @@ -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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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:** + +```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 + +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. + + + +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: + +```markdown + +Investigate issue: {trigger} + + + +expected: {expected} +actual: {actual} +errors: {errors} +reproduction: {reproduction} +timeline: {timeline} + + + +symptoms_prefilled: true +goal: find_and_fix + +``` + +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] + + + + +- [ ] Active sessions checked +- [ ] Symptoms gathered (if new) +- [ ] gsd-debugger spawned with context +- [ ] Checkpoints handled correctly +- [ ] Root cause confirmed before fixing + +``` + +**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 + + +File is <150 lines. +References gsd-debugger as subagent_type. +Does NOT reference workflows/debug.md or references/debugging/*.md. + + +/gsd:debug is thin orchestrator that spawns gsd-debugger agent + + + + + Task 2: Deprecate workflows/debug.md + get-shit-done/workflows/debug.md + +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:** + +```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 + +Investigate issue: {issue_id} + +**Summary:** {issue_summary} + + + +expected: {expected} +actual: {actual} +errors: {errors} +reproduction: {reproduction} +timeline: {timeline} + + + +symptoms_prefilled: {true_or_false} +goal: {find_root_cause_only | find_and_fix} + + + +Create: .planning/debug/{slug}.md + +``` + +--- + +## 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 + +Continue debugging {slug}. Evidence is in the debug file. + + + +Debug file: @.planning/debug/{slug}.md + + + +**Type:** {checkpoint_type} +**Response:** {user_response} + + + +goal: {goal} + +``` +``` + +**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 + + +File is <100 lines. +Contains template with placeholders. +Does NOT contain execution_context, checkpoint_behavior, or investigation_protocol sections. +References subagent_type="gsd-debugger". + + +debug-subagent-prompt.md simplified to context injection only + + + + + + +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 + + + + +- /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 + + + +After completion, create `.planning/phases/13-debug-agent/13-02-SUMMARY.md` + diff --git a/.planning/phases/13-debug-agent/13-03-PLAN.md b/.planning/phases/13-debug-agent/13-03-PLAN.md new file mode 100644 index 000000000..0036c0986 --- /dev/null +++ b/.planning/phases/13-debug-agent/13-03-PLAN.md @@ -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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Deprecate all debugging reference 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 + + +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` → `` section +2. `hypothesis-testing.md` → `` section +3. `investigation-techniques.md` → `` section +4. `verification-patterns.md` → `` section +5. `when-to-research.md` → `` section + +Each file should be ~15 lines with the redirect notice. + + +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. + + +All debugging reference files deprecated with agent pointers + + + + + Task 2: Update installer to include agents directory + bin/install.js + +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. + + +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. + + +Installer copies agents/ directory + + + + + + +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 + + + + +- Debugging reference files deprecated +- No duplicate content between references and agent +- Installer copies agents directory + + + +After completion, create `.planning/phases/13-debug-agent/13-03-SUMMARY.md` +