docs(14): create researcher agent phase plans

Phase 14: Dedicated Researcher Agent - 3 plans in 2 waves - Wave 1: 14-01 (agent creation) - Wave 2: 14-02, 14-03 (parallel orchestrator refactoring) - Ready for execution Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-15 16:54:12 -06:00
parent 667d7097b5
commit f93a177788
4 changed files with 683 additions and 1 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -233,7 +233,16 @@ Created gsd-debugger agent with scientific method, hypothesis testing, 7+ invest
 **Goal:** Create `gsd-researcher` agent with research methodology baked in, refactor research commands to spawn specialized agents
 **Depends on:** Phase 13
 **Research:** Unlikely (applying same agent pattern to research workflows)
-**Plans:** TBD
+**Plans:** 3 plans
+
+Plans:
+- [ ] 14-01: Create gsd-researcher agent - Consolidate research expertise (~800-1000 lines)
+- [ ] 14-02: Refactor /gsd:research-phase - Thin orchestrator, deprecate workflow
+- [ ] 14-03: Refactor /gsd:research-project - Parallel agent spawning, deprecate workflow
+
+**Wave structure:**
+- Wave 1: 14-01 (foundation)
+- Wave 2: 14-02, 14-03 (parallel - both depend only on 14-01)

 Components:
 - Create `agents/gsd-researcher.md` with research expertise
--- a/.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md
+++ b/.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md
@@ -0,0 +1,207 @@
+---
+phase: 14-dedicated-researcher-agent
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: [agents/gsd-researcher.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "gsd-researcher agent file exists with complete research methodology"
+    - "Agent covers all 4 research modes: ecosystem, feasibility, implementation, comparison"
+    - "Agent includes tool strategy (when to use Context7 vs WebSearch vs WebFetch)"
+    - "Agent includes source hierarchy and verification requirements"
+  artifacts:
+    - path: "agents/gsd-researcher.md"
+      provides: "Complete research expertise in single agent file"
+      min_lines: 600
+      contains: "research_modes"
+  key_links:
+    - from: "agents/gsd-researcher.md"
+      to: "research commands"
+      via: "spawned by orchestrator"
+      pattern: "spawned by.*research"
+---
+
+<objective>
+Create gsd-researcher agent with all research expertise baked in.
+
+Purpose: Consolidate ~1,200 lines of research methodology (research-phase.md workflow, research-project.md workflow, research-pitfalls.md, research.md template) into a single agent file following the thin orchestrator pattern established in Phase 13.
+
+Output: `agents/gsd-researcher.md` (~800-1000 lines) containing complete research methodology that orchestrators can spawn.
+</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
+
+Source material to consolidate:
+@get-shit-done/workflows/research-phase.md
+@get-shit-done/workflows/research-project.md
+@get-shit-done/references/research-pitfalls.md
+@get-shit-done/templates/research.md
+
+Pattern reference (Phase 13 agent):
+@agents/gsd-debugger.md (first 150 lines for structure pattern)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create gsd-researcher agent file</name>
+  <files>agents/gsd-researcher.md</files>
+  <action>
+Create agents/gsd-researcher.md following the gsd-debugger pattern with these sections:
+
+**Frontmatter:**
+```yaml
+---
+name: gsd-researcher
+description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /gsd:research-phase and /gsd:research-project orchestrators.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+color: cyan
+---
+```
+
+**Core sections to include:**
+
+1. `<role>` - Research agent identity, what spawns it, core responsibilities
+
+2. `<philosophy>` - Research principles:
+   - Source hierarchy (Context7 > Official docs > WebSearch)
+   - Verification requirements (cross-reference, confidence levels)
+   - Treating Claude's training as hypothesis not fact
+   - Honest reporting of gaps and unknowns
+
+3. `<research_modes>` - Four research modes with clear triggers:
+   - `ecosystem` — Survey landscape (tools, approaches, prior art)
+   - `feasibility` — Can we do X? What are blockers?
+   - `implementation` — How specifically to implement X?
+   - `comparison` — Compare options A vs B vs C
+
+4. `<tool_strategy>` - When to use each research tool:
+   - Context7: First for any library/framework (authoritative, current)
+   - Official docs via WebFetch: When Context7 lacks coverage
+   - WebSearch: Ecosystem discovery, community patterns, pitfalls
+   - Verification protocol: WebSearch findings must be cross-verified
+
+5. `<source_hierarchy>` - Source prioritization:
+   - HIGH confidence: Context7, official documentation
+   - MEDIUM confidence: WebSearch verified with official source
+   - LOW confidence: WebSearch only (flagged for validation)
+
+6. `<verification_protocol>` - From research-pitfalls.md:
+   - All known pitfalls (config scope, deprecated features, tool variations, negative claims, etc.)
+   - Red flags to watch for
+   - Quick reference checklist
+
+7. `<output_formats>` - Templates for research outputs:
+   - Phase research (RESEARCH.md structure)
+   - Project research (SUMMARY.md, STACK.md, etc.)
+   - Comparison matrices
+   - Feasibility assessments
+
+8. `<execution_flow>` - How the agent operates:
+   - Receive research question/scope from orchestrator
+   - Identify research domains
+   - Execute research protocol
+   - Verify findings
+   - Write output file(s)
+   - Return structured result
+
+9. `<structured_returns>` - Return format to orchestrator:
+   - Research complete with findings summary
+   - Confidence assessment
+   - Files created
+   - Open questions/gaps
+
+10. `<success_criteria>` - When research is complete
+
+Target: 800-1000 lines (consolidation from ~1,200 source lines with 20-30% reduction while preserving all critical concepts)
+  </action>
+  <verify>
+Verify file exists and has required sections:
+```bash
+wc -l agents/gsd-researcher.md
+grep -c "research_modes\|tool_strategy\|source_hierarchy\|verification_protocol\|output_formats" agents/gsd-researcher.md
+```
+Expected: 600-1000 lines, 5+ section matches
+  </verify>
+  <done>agents/gsd-researcher.md exists with all 10 required sections, 600-1000 lines</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Verify agent completeness</name>
+  <files>agents/gsd-researcher.md</files>
+  <action>
+Read the created agent file and verify:
+
+1. **All research modes documented:**
+   - ecosystem mode has clear scope and output
+   - feasibility mode has clear scope and output
+   - implementation mode has clear scope and output
+   - comparison mode has clear scope and output
+
+2. **Tool strategy is actionable:**
+   - Context7 usage is explicit (resolve-library-id, query-docs)
+   - WebFetch patterns for official docs
+   - WebSearch query templates with {current_year}
+   - Verification requirements are clear
+
+3. **Pitfalls are preserved:**
+   - All pitfalls from research-pitfalls.md included
+   - Red flags section present
+   - Quick reference checklist included
+
+4. **Output formats match templates:**
+   - RESEARCH.md structure matches research.md template
+   - Project research structure matches research-project templates
+
+5. **No critical concepts lost:**
+   - Source hierarchy preserved
+   - Confidence levels system preserved
+   - Cross-verification requirements preserved
+
+If any gaps found, edit to add missing content.
+  </action>
+  <verify>
+All 4 research modes documented:
+```bash
+grep -E "ecosystem|feasibility|implementation|comparison" agents/gsd-researcher.md | wc -l
+```
+Expected: 4+ matches (mode definitions plus references)
+  </verify>
+  <done>Agent contains all 4 research modes, complete tool strategy, all pitfalls, and output formats</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] agents/gsd-researcher.md exists
+- [ ] File is 600-1000 lines (consolidated from ~1,200)
+- [ ] All 10 required sections present
+- [ ] 4 research modes defined with triggers and outputs
+- [ ] Tool strategy section is actionable
+- [ ] Verification protocol includes all pitfalls
+- [ ] Output formats match existing templates
+</verification>
+
+<success_criteria>
+- All tasks completed
+- Agent file follows gsd-debugger pattern
+- Research methodology consolidated without concept loss
+- Ready for orchestrator integration (Plan 14-02)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-dedicated-researcher-agent/14-01-SUMMARY.md`
+</output>
--- a/.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md
+++ b/.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md
@@ -0,0 +1,233 @@
+---
+phase: 14-dedicated-researcher-agent
+plan: 02
+type: execute
+wave: 2
+depends_on: ["14-01"]
+files_modified: [commands/gsd/research-phase.md, get-shit-done/workflows/research-phase.md, get-shit-done/templates/research-subagent-prompt.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "/gsd:research-phase spawns gsd-researcher agent"
+    - "Command is <200 lines (thin orchestrator)"
+    - "Workflow file has deprecation notice pointing to agent"
+  artifacts:
+    - path: "commands/gsd/research-phase.md"
+      provides: "Thin orchestrator that spawns researcher agent"
+      min_lines: 80
+      contains: "gsd-researcher"
+    - path: "get-shit-done/workflows/research-phase.md"
+      provides: "Deprecation notice"
+      contains: "DEPRECATED"
+  key_links:
+    - from: "commands/gsd/research-phase.md"
+      to: "agents/gsd-researcher.md"
+      via: "Task tool spawn"
+      pattern: "subagent_type.*gsd-researcher"
+---
+
+<objective>
+Refactor /gsd:research-phase to thin orchestrator that spawns gsd-researcher agent.
+
+Purpose: Apply the thin orchestrator pattern from Phase 13 — command handles argument parsing and context gathering, all research expertise lives in the agent. Reduces main context from ~450+ lines to ~150 lines.
+
+Output: Refactored command (~150 lines), deprecated workflow, simplified subagent prompt 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
+
+Files to refactor:
+@commands/gsd/research-phase.md
+@get-shit-done/workflows/research-phase.md
+
+Pattern reference (Phase 13 thin orchestrator):
+@commands/gsd/debug.md
+@.planning/phases/13-debug-agent/13-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Refactor /gsd:research-phase to thin orchestrator</name>
+  <files>commands/gsd/research-phase.md</files>
+  <action>
+Rewrite commands/gsd/research-phase.md as thin orchestrator following the debug.md pattern:
+
+**Keep in orchestrator (low context cost, user interaction):**
+- Argument parsing (phase number)
+- Validation (phase exists in roadmap)
+- Checking for existing RESEARCH.md
+- Gathering phase context (roadmap description, requirements)
+- Spawning the researcher agent with context
+- Presenting results to user
+- Offering next steps
+
+**Delegate to agent (burns context during research):**
+- All research methodology
+- Tool strategy (Context7, WebSearch, etc.)
+- Source verification
+- Output generation
+
+**Structure:**
+```markdown
+---
+name: gsd:research-phase
+description: Research how to implement a phase before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+---
+
+<objective>
+Research how to implement a phase. Spawns gsd-researcher agent with phase context.
+</objective>
+
+<process>
+1. Parse phase argument
+2. Validate phase exists in roadmap
+3. Check for existing RESEARCH.md
+4. Gather phase context (description, requirements, constraints)
+5. Spawn gsd-researcher agent with research question
+6. Present results and offer next steps
+</process>
+
+<spawn_researcher>
+Task(
+  prompt="Research implementation approach for phase {phase}...",
+  subagent_type="gsd-researcher"
+)
+</spawn_researcher>
+```
+
+Target: ~150 lines (down from ~84 lines command + ~450 lines workflow)
+  </action>
+  <verify>
+```bash
+wc -l commands/gsd/research-phase.md
+grep -c "gsd-researcher\|Task\|subagent_type" commands/gsd/research-phase.md
+```
+Expected: <200 lines, 3+ spawning references
+  </verify>
+  <done>commands/gsd/research-phase.md is thin orchestrator <200 lines, spawns gsd-researcher</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Deprecate workflows/research-phase.md</name>
+  <files>get-shit-done/workflows/research-phase.md</files>
+  <action>
+Replace workflows/research-phase.md with deprecation notice following Phase 13 pattern:
+
+```markdown
+# Research Phase Workflow
+
+## ⚠️ DEPRECATED
+
+**This workflow has been consolidated into the gsd-researcher agent.**
+
+The research methodology, tool strategy, and verification protocols now live in:
+- `agents/gsd-researcher.md`
+
+The `/gsd:research-phase` command spawns the gsd-researcher agent directly.
+
+**Migration:** No action needed — the command handles this automatically.
+
+---
+
+*Deprecated: 2026-01-XX*
+*Replaced by: agents/gsd-researcher.md*
+```
+
+Keep file (don't delete) for git history traceability.
+  </action>
+  <verify>
+```bash
+head -20 get-shit-done/workflows/research-phase.md
+```
+Should show DEPRECATED notice
+  </verify>
+  <done>workflows/research-phase.md has deprecation notice pointing to agent</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Create research-subagent-prompt.md template</name>
+  <files>get-shit-done/templates/research-subagent-prompt.md</files>
+  <action>
+Create a simple context-passing template for spawning the researcher agent:
+
+```markdown
+# Research Subagent Prompt Template
+
+Template for spawning gsd-researcher agent from orchestrators.
+
+## Template
+
+```
+<objective>
+Research: {research_question}
+
+Mode: {research_mode} (ecosystem | feasibility | implementation | comparison)
+</objective>
+
+<context>
+Phase: {phase_number} - {phase_name}
+Description: {phase_description}
+
+Requirements:
+{phase_requirements}
+
+Constraints:
+{constraints_from_state}
+</context>
+
+<output>
+Write research findings to: {output_path}
+Use RESEARCH.md template structure for phase research.
+</output>
+```
+
+**Note:** Research methodology, tool strategy, and verification protocols are baked into the gsd-researcher agent. This template only passes context.
+```
+
+Target: ~60 lines (context-only, agent has expertise)
+  </action>
+  <verify>
+```bash
+wc -l get-shit-done/templates/research-subagent-prompt.md
+```
+Expected: <100 lines
+  </verify>
+  <done>research-subagent-prompt.md template created, context-only (~60 lines)</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] commands/gsd/research-phase.md is <200 lines
+- [ ] Command spawns gsd-researcher agent via Task tool
+- [ ] workflows/research-phase.md has deprecation notice
+- [ ] research-subagent-prompt.md template exists
+- [ ] Template is context-only (no methodology duplication)
+</verification>
+
+<success_criteria>
+- All tasks completed
+- Thin orchestrator pattern applied
+- Main context reduced from ~530 lines to ~150 lines
+- Workflow deprecated with clear redirect
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-dedicated-researcher-agent/14-02-SUMMARY.md`
+</output>
--- a/.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md
+++ b/.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md
@@ -0,0 +1,233 @@
+---
+phase: 14-dedicated-researcher-agent
+plan: 03
+type: execute
+wave: 2
+depends_on: ["14-01"]
+files_modified: [commands/gsd/research-project.md, get-shit-done/workflows/research-project.md]
+autonomous: true
+
+must_haves:
+  truths:
+    - "/gsd:research-project spawns parallel gsd-researcher agents"
+    - "Command is <200 lines (thin orchestrator)"
+    - "Workflow file has deprecation notice pointing to agent"
+    - "4 parallel agents for stack, features, architecture, pitfalls"
+  artifacts:
+    - path: "commands/gsd/research-project.md"
+      provides: "Thin orchestrator that spawns parallel researcher agents"
+      min_lines: 100
+      contains: "gsd-researcher"
+    - path: "get-shit-done/workflows/research-project.md"
+      provides: "Deprecation notice"
+      contains: "DEPRECATED"
+  key_links:
+    - from: "commands/gsd/research-project.md"
+      to: "agents/gsd-researcher.md"
+      via: "Parallel Task tool spawns"
+      pattern: "subagent_type.*gsd-researcher"
+---
+
+<objective>
+Refactor /gsd:research-project to spawn parallel gsd-researcher agents.
+
+Purpose: Apply thin orchestrator pattern — command handles project analysis and spawns 4 parallel researcher agents (stack, features, architecture, pitfalls). Each agent writes its own file, orchestrator synthesizes SUMMARY.md.
+
+Output: Refactored command (~180 lines), deprecated workflow.
+</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
+
+Files to refactor:
+@commands/gsd/research-project.md
+@get-shit-done/workflows/research-project.md
+
+Pattern reference:
+@commands/gsd/debug.md (thin orchestrator pattern)
+@.planning/phases/13-debug-agent/13-02-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Refactor /gsd:research-project to thin orchestrator</name>
+  <files>commands/gsd/research-project.md</files>
+  <action>
+Rewrite commands/gsd/research-project.md as thin orchestrator:
+
+**Keep in orchestrator:**
+- PROJECT.md validation
+- Domain analysis from PROJECT.md
+- Research question generation
+- Spawning 4 parallel researcher agents
+- Waiting for all agents to complete
+- Synthesizing SUMMARY.md from agent outputs
+- Offering next steps
+
+**Delegate to agents (each writes its own file):**
+- Stack research → .planning/research/STACK.md
+- Features research → .planning/research/FEATURES.md
+- Architecture research → .planning/research/ARCHITECTURE.md
+- Pitfalls research → .planning/research/PITFALLS.md
+
+**Structure:**
+```markdown
+---
+name: gsd:research-project
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+<objective>
+Research domain ecosystem. Spawns 4 parallel gsd-researcher agents for comprehensive coverage.
+</objective>
+
+<process>
+1. Validate PROJECT.md exists
+2. Analyze project to determine domain
+3. Generate research questions (stack, features, architecture, pitfalls)
+4. Create .planning/research/ directory
+5. Spawn 4 gsd-researcher agents in parallel (each writes its own file)
+6. Wait for all to complete
+7. Synthesize SUMMARY.md from agent outputs
+8. Commit research
+9. Offer next steps
+</process>
+
+<spawn_agents>
+Spawn all 4 in parallel with single message containing multiple Task calls:
+
+Task(prompt="Research stack for {domain}...", subagent_type="gsd-researcher")
+Task(prompt="Research features for {domain}...", subagent_type="gsd-researcher")
+Task(prompt="Research architecture for {domain}...", subagent_type="gsd-researcher")
+Task(prompt="Research pitfalls for {domain}...", subagent_type="gsd-researcher")
+</spawn_agents>
+```
+
+Target: ~180 lines (down from ~138 lines command + ~430 lines workflow)
+  </action>
+  <verify>
+```bash
+wc -l commands/gsd/research-project.md
+grep -c "gsd-researcher\|Task\|parallel" commands/gsd/research-project.md
+```
+Expected: <200 lines, 4+ spawning references
+  </verify>
+  <done>commands/gsd/research-project.md is thin orchestrator <200 lines, spawns 4 parallel agents</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Deprecate workflows/research-project.md</name>
+  <files>get-shit-done/workflows/research-project.md</files>
+  <action>
+Replace workflows/research-project.md with deprecation notice:
+
+```markdown
+# Research Project Workflow
+
+## ⚠️ DEPRECATED
+
+**This workflow has been consolidated into the gsd-researcher agent.**
+
+The research methodology for project research now lives in:
+- `agents/gsd-researcher.md`
+
+The `/gsd:research-project` command spawns 4 parallel gsd-researcher agents:
+- Stack agent → .planning/research/STACK.md
+- Features agent → .planning/research/FEATURES.md
+- Architecture agent → .planning/research/ARCHITECTURE.md
+- Pitfalls agent → .planning/research/PITFALLS.md
+
+The orchestrator synthesizes SUMMARY.md after all agents complete.
+
+**Migration:** No action needed — the command handles this automatically.
+
+---
+
+*Deprecated: 2026-01-XX*
+*Replaced by: agents/gsd-researcher.md*
+```
+
+Keep file for git history.
+  </action>
+  <verify>
+```bash
+head -25 get-shit-done/workflows/research-project.md
+```
+Should show DEPRECATED notice
+  </verify>
+  <done>workflows/research-project.md has deprecation notice pointing to agent</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Deprecate research-pitfalls.md reference</name>
+  <files>get-shit-done/references/research-pitfalls.md</files>
+  <action>
+Add deprecation notice to top of research-pitfalls.md (keeping content for reference):
+
+```markdown
+# Research Pitfalls Reference
+
+## ⚠️ DEPRECATED
+
+**This reference has been consolidated into the gsd-researcher agent.**
+
+The verification protocols and pitfall patterns now live in:
+- `agents/gsd-researcher.md` (section: `<verification_protocol>`)
+
+The content below is preserved for reference but is no longer the primary source.
+
+---
+
+*Deprecated: 2026-01-XX*
+*Replaced by: agents/gsd-researcher.md*
+
+---
+
+[existing content follows]
+```
+
+Keep full content below the notice for reference.
+  </action>
+  <verify>
+```bash
+head -20 get-shit-done/references/research-pitfalls.md
+```
+Should show DEPRECATED notice with pointer to agent
+  </verify>
+  <done>research-pitfalls.md has deprecation notice pointing to agent</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] commands/gsd/research-project.md is <200 lines
+- [ ] Command spawns 4 parallel gsd-researcher agents
+- [ ] workflows/research-project.md has deprecation notice
+- [ ] research-pitfalls.md has deprecation notice
+- [ ] All deprecation notices point to agents/gsd-researcher.md
+</verification>
+
+<success_criteria>
+- All tasks completed
+- Parallel agent spawning pattern documented
+- Main context reduced significantly
+- All deprecated files point to new agent location
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-dedicated-researcher-agent/14-03-SUMMARY.md`
+</output>