refactor(research): inject rich context from orchestrators to agent
research-phase.md:
- Added <key_insight> framing ("what don't I know that I don't know")
- Added <downstream_consumer> explaining plan-phase integration
- Added <quality_gate> checklist
research-project.md:
- Added milestone context (greenfield vs v1.1+)
- Added <downstream_consumer> per dimension
- Added <quality_gate> per agent
- Enhanced roadmap implications guidance
gsd-researcher.md:
- Simplified <gsd_integration> to point to orchestrator-provided context
- Agent is now pure research capability, context is injected
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -24,47 +24,14 @@ Your job: Answer research questions with verified, actionable findings. Produce
|
||||
|
||||
<gsd_integration>
|
||||
|
||||
## Why You Research
|
||||
## Research Feeds Planning
|
||||
|
||||
Your research output directly feeds into `/gsd:plan-phase`. The planning workflow loads your RESEARCH.md and uses specific sections to create better plans.
|
||||
Your output is consumed by downstream GSD workflows. The orchestrator's prompt tells you:
|
||||
- `<research_type>` — Phase research vs project research
|
||||
- `<downstream_consumer>` — What workflow uses your output and how
|
||||
- `<quality_gate>` — Checklist before declaring complete
|
||||
|
||||
**The contract:**
|
||||
|
||||
| Your Section | How plan-phase Uses It |
|
||||
|--------------|------------------------|
|
||||
| `## Standard Stack` | Plans use these libraries, not alternatives |
|
||||
| `## Architecture Patterns` | Task structure follows these patterns |
|
||||
| `## Don't Hand-Roll` | Tasks NEVER build custom solutions for listed problems |
|
||||
| `## Common Pitfalls` | Verification steps check for these |
|
||||
| `## Code Examples` | Task actions reference these patterns |
|
||||
|
||||
**What this means for your output:**
|
||||
|
||||
1. **Section names matter** — plan-phase greps for these exact headings
|
||||
2. **Be prescriptive, not exploratory** — "Use X" not "Consider X or Y"
|
||||
3. **Actionable over comprehensive** — A focused stack beats a survey of options
|
||||
4. **Examples are instructions** — Code snippets become task templates
|
||||
|
||||
**Bad research (for GSD):**
|
||||
```markdown
|
||||
## Options for State Management
|
||||
There are several approaches: Redux, Zustand, Jotai, or React Context...
|
||||
```
|
||||
|
||||
**Good research (for GSD):**
|
||||
```markdown
|
||||
## Standard Stack
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| Zustand | 4.5 | State management |
|
||||
|
||||
## Don't Hand-Roll
|
||||
| Problem | Use Instead |
|
||||
|---------|-------------|
|
||||
| Global state | Zustand (not React Context) |
|
||||
```
|
||||
|
||||
The second version tells the planner exactly what to put in tasks.
|
||||
**Universal principle:** Be prescriptive, not exploratory. "Use X" beats "Consider X or Y." Your research becomes instructions.
|
||||
|
||||
</gsd_integration>
|
||||
|
||||
|
||||
@@ -61,6 +61,23 @@ Present summary with phase description, requirements, prior decisions.
|
||||
Research modes: ecosystem (default), feasibility, implementation, comparison.
|
||||
|
||||
```markdown
|
||||
<research_type>
|
||||
Phase Research — investigating HOW to implement a specific phase well.
|
||||
</research_type>
|
||||
|
||||
<key_insight>
|
||||
The question is NOT "which library should I use?"
|
||||
|
||||
The question is: "What do I not know that I don't know?"
|
||||
|
||||
For this phase, discover:
|
||||
- What's the established architecture pattern?
|
||||
- What libraries form the standard stack?
|
||||
- What problems do people commonly hit?
|
||||
- What's SOTA vs what Claude's training thinks is SOTA?
|
||||
- What should NOT be hand-rolled?
|
||||
</key_insight>
|
||||
|
||||
<objective>
|
||||
Research implementation approach for Phase {phase_number}: {phase_name}
|
||||
Mode: ecosystem
|
||||
@@ -73,6 +90,26 @@ Mode: ecosystem
|
||||
**Phase context:** {context_md_content}
|
||||
</context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your RESEARCH.md will be loaded by `/gsd:plan-phase` which uses specific sections:
|
||||
- `## Standard Stack` → Plans use these libraries
|
||||
- `## Architecture Patterns` → Task structure follows these
|
||||
- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
|
||||
- `## Common Pitfalls` → Verification steps check for these
|
||||
- `## Code Examples` → Task actions reference these patterns
|
||||
|
||||
Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
Before declaring complete, verify:
|
||||
- [ ] All domains investigated (not just some)
|
||||
- [ ] Negative claims verified with official docs
|
||||
- [ ] Multiple sources for critical claims
|
||||
- [ ] Confidence levels assigned honestly
|
||||
- [ ] Section names match what plan-phase expects
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
|
||||
</output>
|
||||
|
||||
@@ -64,24 +64,168 @@ Present for approval.
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
Spawn all 4 in parallel:
|
||||
**Determine milestone context:**
|
||||
- If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
|
||||
- If "Validated" requirements exist → Subsequent milestone (v1.1+)
|
||||
|
||||
Spawn all 4 in parallel with rich context:
|
||||
|
||||
```
|
||||
Task(prompt="Research stack for [domain]. Question: [question]. Context: [PROJECT.md summary].
|
||||
Write to: .planning/research/STACK.md. Use template from ~/.claude/get-shit-done/templates/research-project/STACK.md",
|
||||
subagent_type="gsd-researcher", description="Stack research")
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Stack dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
Task(prompt="Research features for [domain]. Question: [question]. Context: [PROJECT.md summary].
|
||||
Write to: .planning/research/FEATURES.md. Use template from ~/.claude/get-shit-done/templates/research-project/FEATURES.md",
|
||||
subagent_type="gsd-researcher", description="Features research")
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Task(prompt="Research architecture for [domain]. Question: [question]. Context: [PROJECT.md summary].
|
||||
Write to: .planning/research/ARCHITECTURE.md. Use template from ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md",
|
||||
subagent_type="gsd-researcher", description="Architecture research")
|
||||
Greenfield: Research the standard stack for building [domain] from scratch.
|
||||
Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
|
||||
</milestone_context>
|
||||
|
||||
Task(prompt="Research pitfalls for [domain]. Question: [question]. Context: [PROJECT.md summary].
|
||||
Write to: .planning/research/PITFALLS.md. Use template from ~/.claude/get-shit-done/templates/research-project/PITFALLS.md",
|
||||
subagent_type="gsd-researcher", description="Pitfalls research")
|
||||
<question>
|
||||
[stack question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your STACK.md feeds into /gsd:create-roadmap. Be prescriptive:
|
||||
- Specific libraries with versions
|
||||
- Clear rationale for each choice
|
||||
- What NOT to use and why
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Versions are current (not Claude's training data)
|
||||
- [ ] Rationale explains WHY, not just WHAT
|
||||
- [ ] Confidence levels assigned
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/STACK.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
|
||||
</output>
|
||||
", subagent_type="gsd-researcher", description="Stack research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Features dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
|
||||
Subsequent: How do [target features] typically work? What's expected behavior?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[features question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your FEATURES.md feeds into /gsd:define-requirements. Categorize clearly:
|
||||
- Table stakes (must have or users leave)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (things to deliberately NOT build)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Categories are clear
|
||||
- [ ] Complexity noted for each
|
||||
- [ ] Dependencies between features identified
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/FEATURES.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
|
||||
</output>
|
||||
", subagent_type="gsd-researcher", description="Features research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Architecture dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: How are [domain] systems typically structured? What are major components?
|
||||
Subsequent: How do [target features] integrate with existing [domain] architecture?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[architecture question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
|
||||
- Component boundaries (what talks to what)
|
||||
- Data flow (how information moves)
|
||||
- Suggested build order (dependencies between components)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Components clearly defined
|
||||
- [ ] Boundaries explicit
|
||||
- [ ] Build order implications noted
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/ARCHITECTURE.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
|
||||
</output>
|
||||
", subagent_type="gsd-researcher", description="Architecture research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Pitfalls dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
|
||||
Subsequent: What are common mistakes when adding [target features] to [domain]?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[pitfalls question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
|
||||
- Warning signs (how to detect early)
|
||||
- Prevention strategy (how to avoid)
|
||||
- Which phase should address it
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Pitfalls are specific, not generic
|
||||
- [ ] Prevention is actionable
|
||||
- [ ] Phase mapping included
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/PITFALLS.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
</output>
|
||||
", subagent_type="gsd-researcher", description="Pitfalls research")
|
||||
```
|
||||
|
||||
**Announce:** "Spawning 4 research agents... may take 2-3 minutes."
|
||||
@@ -91,9 +235,35 @@ subagent_type="gsd-researcher", description="Pitfalls research")
|
||||
After all agents complete, read their outputs and write `.planning/research/SUMMARY.md`:
|
||||
- Read template: `~/.claude/get-shit-done/templates/research-project/SUMMARY.md`
|
||||
- Synthesize executive summary from all 4 files
|
||||
- Include "Implications for Roadmap" with suggested phase structure
|
||||
- Add confidence assessment
|
||||
|
||||
**Critical: Include "Implications for Roadmap" section:**
|
||||
|
||||
```markdown
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
|
||||
1. **[Phase name]** — [rationale from research]
|
||||
- Addresses: [features from FEATURES.md]
|
||||
- Avoids: [pitfall from PITFALLS.md]
|
||||
- Uses: [stack element from STACK.md]
|
||||
|
||||
2. **[Phase name]** — [rationale from research]
|
||||
- Implements: [architecture component from ARCHITECTURE.md]
|
||||
...
|
||||
|
||||
**Phase ordering rationale:**
|
||||
- [Why this order based on dependencies discovered in ARCHITECTURE.md]
|
||||
- [Why this grouping based on PITFALLS.md prevention strategies]
|
||||
|
||||
**Research flags for phases:**
|
||||
- Phase [X]: Likely needs deeper research (reason)
|
||||
- Phase [Y]: Standard patterns, unlikely to need research
|
||||
```
|
||||
|
||||
This section directly feeds into `/gsd:create-roadmap`.
|
||||
|
||||
## 7. Commit Research
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user