refactor: research workflow as Claude Code context injection

Research is now optimized for Claude Code implementation quality:
- PROJECT.md-driven (features, constraints, questions, decisions)
- High-confidence only (no low-quality padding)
- 3 focused files: stack.md, implementation.md, risks.md
- Code examples with current vs deprecated patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2025-12-15 23:23:15 -06:00
parent 5bbff091c6
commit 77ea129fd5
4 changed files with 738 additions and 705 deletions

View File

@@ -11,14 +11,15 @@ allowed-tools:
--- ---
<objective> <objective>
Research domain ecosystem via batched subagents before roadmap creation. Research implementation context for Claude Code before roadmap creation.
Spawns 3-4 subagents in parallel to research: This is NOT research for human decision-making. This is context injection so Claude Code can implement correctly with current APIs, patterns, and best practices.
- Ecosystem (libraries, frameworks, tools) Spawns 2-3 subagents in parallel to research PROJECT.md-specific needs:
- Architecture (patterns, project structure)
- Pitfalls (common mistakes, what NOT to do) - **Stack** - What libraries/tools to use for THIS project's features
- Standards (best practices, conventions) - **Implementation** - Current API patterns, code examples, correct syntax
- **Risks** - What Claude might get wrong, deprecated patterns to avoid
Each subagent writes directly to `.planning/research/` preserving main context. Each subagent writes directly to `.planning/research/` preserving main context.
</objective> </objective>
@@ -67,51 +68,97 @@ What would you like to do?
Wait for user decision. Wait for user decision.
</step> </step>
<step name="detect_domain"> <step name="parse_project">
Parse PROJECT.md to identify the domain and research scope. Read PROJECT.md and extract research targets:
Look for: **From Scope (Building):**
- List each feature/capability that needs implementation
- These become specific research queries
- Technologies mentioned (Three.js, WebGL, audio, etc.) **From Constraints:**
- Problem domain (3D, games, real-time, etc.) - Tech stack requirements (language, framework, platform)
- Technical constraints that suggest specific ecosystems - Performance requirements
- Compatibility requirements
If domain unclear, use AskUserQuestion: **From Open Questions:**
- Questions that research should answer
- These are explicit research targets
- header: "Domain" **From Decisions Made:**
- question: "What domain should we research?" - Choices to validate ("any gotchas with X?")
- options:
- "3D/Graphics" - Three.js, WebGL, shaders Create a research manifest:
- "Games/Interactive" - Physics, collision, procedural ```
- "Audio/Music" - Web Audio, synthesis, DSP Features to implement:
- (other relevant options based on PROJECT.md) - [feature 1]
</step> - [feature 2]
- [feature 3]
Stack constraints:
- [constraint 1]
- [constraint 2]
Open questions to answer:
- [question 1]
- [question 2]
Decisions to validate:
- [decision 1]
```
If PROJECT.md is too vague for specific research targets, use AskUserQuestion:
- header: "Research scope"
- question: "What specific implementation questions should we research?"
- options based on detected domain
</step>
<step name="research"> <step name="research">
Follow research-project.md workflow: Follow research-project.md workflow with PROJECT.md-driven research:
1. Create `.planning/research/` directory 1. Create `.planning/research/` directory
2. Spawn first batch of subagents (ecosystem + architecture) 2. Spawn subagents in parallel (all at once if ≤3):
- **stack.md** - Libraries/tools for each feature in Scope
- **implementation.md** - Current API patterns and code examples
- **risks.md** - What Claude might get wrong, deprecated patterns
3. Wait for completion 3. Wait for completion
4. Spawn second batch (pitfalls + standards) 4. Verify all outputs exist and are high-quality
5. Wait for completion </step>
6. Verify all outputs exist
</step> <step name="verify_quality">
After subagents complete, verify quality:
```bash
# Check files exist
for f in stack implementation risks; do
[ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING"
done
```
**Quality check (read each file):**
- Contains ONLY high-confidence information?
- Includes actual code examples with current syntax?
- Addresses specific features from PROJECT.md?
- No low-confidence padding or "might be useful" items?
If a file contains low-quality content, note it for summary.
</step>
<step name="summarize"> <step name="summarize">
After all subagents complete: After verification:
``` ```
Research complete: Research complete:
- .planning/research/ecosystem.md - .planning/research/stack.md - [libraries/tools identified]
- .planning/research/architecture.md - .planning/research/implementation.md - [patterns documented]
- .planning/research/pitfalls.md - .planning/research/risks.md - [pitfalls to avoid]
- .planning/research/standards.md
Key findings: Key implementation context:
- [Top ecosystem recommendation] - [Primary stack choice with rationale]
- [Key architecture pattern] - [Most important API pattern to use]
- [Critical pitfall to avoid] - [Critical mistake Claude should avoid]
Open questions remaining:
- [Any questions research couldn't answer]
What's next? What's next?
1. Create roadmap (/gsd:create-roadmap) - Incorporates research 1. Create roadmap (/gsd:create-roadmap) - Incorporates research
@@ -125,18 +172,16 @@ If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
</process> </process>
<output> <output>
- `.planning/research/ecosystem.md` - `.planning/research/stack.md` - Libraries and tools for each feature
- `.planning/research/architecture.md` - `.planning/research/implementation.md` - Current API patterns and code examples
- `.planning/research/pitfalls.md` - `.planning/research/risks.md` - Deprecated patterns and common mistakes
- `.planning/research/standards.md`
</output> </output>
<success_criteria> <success_criteria>
- [ ] PROJECT.md parsed for specific research targets
- [ ] PROJECT.md exists (prerequisite checked) - [ ] Research addresses actual features from Scope
- [ ] Domain detected or user clarified - [ ] Open Questions from PROJECT.md answered (or noted as unanswerable)
- [ ] Subagents spawned in batches of 3-4 max - [ ] All outputs are HIGH-CONFIDENCE only (no padding)
- [ ] All subagents wrote files directly to .planning/research/ - [ ] Code examples use current API syntax
- [ ] All 4 research files exist
- [ ] User knows next steps (create-roadmap) - [ ] User knows next steps (create-roadmap)
</success_criteria> </success_criteria>

View File

@@ -1,557 +1,451 @@
# Research Subagent Prompts # Research Subagent Prompts
<overview> <overview>
Prompt templates for subagents that research domain ecosystems before roadmap creation. Prompt templates for subagents that research implementation context before roadmap creation.
**Critical understanding:** This research is NOT for human decision-making.
This is CONTEXT INJECTION so Claude Code implements correctly.
Each subagent: Each subagent:
- Researches ONE category (ecosystem, architecture, pitfalls, or standards) - Receives a research manifest extracted from PROJECT.md
- Researches ONLY the specific features, constraints, and questions in that manifest
- Outputs HIGH-CONFIDENCE information only (no padding)
- Writes directly to `.planning/research/{category}.md` - Writes directly to `.planning/research/{category}.md`
- Uses WebSearch and Context7 for current information - Formats output for Claude Code to consume during implementation
- Cross-verifies findings with authoritative sources
These prompts are used by the research-project workflow when spawning Task tool subagents. **Quality bar:** Will this context make Claude Code generate correct, modern code?
</overview> </overview>
<ecosystem_subagent_prompt> <stack_subagent_prompt>
## Ecosystem Research Subagent ## Stack Research Subagent
Use this template for spawning ecosystem research subagents: Use this template for spawning stack research subagents:
``` ```
<subagent_prompt> <subagent_prompt>
## Objective ## Objective
Research the library/framework ecosystem for {domain} and write findings to .planning/research/ecosystem.md
## Domain Context Research and document the libraries/tools needed for THIS specific project.
{Paste relevant sections from PROJECT.md describing what's being built} Write findings to .planning/research/stack.md
## Critical Context
**This research is for Claude Code, not humans.**
You are providing context injection so Claude Code implements correctly. Claude's training data may have outdated library versions, deprecated APIs, or old patterns. Your research overrides stale knowledge with current, accurate information.
**Quality bar:** Only include information that will make Claude generate correct, modern code.
## Research Manifest
{Paste the research manifest extracted from PROJECT.md}
## Your Assignment ## Your Assignment
File: .planning/research/ecosystem.md
Category: ecosystem
Purpose: Map the libraries, frameworks, and tools available for this domain
## Research Questions For EACH feature in the manifest:
Answer these questions through web research: 1. What library/tool should Claude use?
1. What are the go-to libraries for this problem space? 2. What's the current version?
2. Which frameworks are actively maintained (commits in last 12 months)? 3. What's the correct import/setup?
3. What's the "standard stack" that domain experts use?
4. What should NOT be hand-rolled because existing solutions exist? For EACH constraint in the manifest:
5. What are the version requirements and compatibility considerations? 1. Does the recommended library work within this constraint?
2. Any compatibility issues?
## Research Requirements ## Research Requirements
You MUST use WebSearch and Context7 to get current information. Use WebSearch to verify CURRENT information (2024-2025).
For EACH library/tool discovered: **INCLUDE only if:**
1. Verify actively maintained (GitHub commits in last 12 months) - Actively maintained (commits in last 12 months)
2. Get current version number - High confidence this is the right choice
3. Understand when to use vs alternatives - Directly relevant to a feature in the manifest
4. Find official documentation and getting started guides
5. Note any critical dependencies or compatibility issues
**Search queries to run:** **EXCLUDE:**
- "{domain} best libraries 2024 2025" - Low or medium confidence options
- "{domain} framework comparison" - "Might be useful" alternatives
- "{specific problem from PROJECT.md} library recommendation" - Deprecated or unmaintained libraries
- "{domain} standard stack production" - Generic options not tied to manifest features
**Red flags (reject these):**
- No updates in 12+ months
- Deprecated or archived repositories
- Pre-2023 recommendations without verification
## Output Format ## Output Format
Write to .planning/research/ecosystem.md using this structure: Write to .planning/research/stack.md:
# Ecosystem: {Domain} ```markdown
# Stack: [Project Name]
**Category:** ecosystem **Purpose:** Libraries and tools for Claude Code to use during implementation
**Domain:** {domain} **Researched:** [date]
**Researched:** {today's date}
**Confidence:** {high | medium | low}
## Research Summary ## [Feature 1 from Scope]
{2-3 sentences on what was found and the recommended direction} **Use:** [Library Name] v[X.Y.Z]
**Why:** [One sentence - why this for this feature]
## Findings ```[language]
// Setup / import
[actual code]
```
### {Library/Framework 1} **Docs:** [URL to current documentation]
{What it is and what it does} ## [Feature 2 from Scope]
**Source:** {URL} **Use:** [Library Name] v[X.Y.Z]
**Version:** {current version} **Why:** [One sentence]
**Confidence:** {high | medium | low}
**Why consider:** {Relevance to project}
**Tradeoffs:** {Limitations or considerations}
### {Library/Framework 2} ```[language]
// Setup / import
[actual code]
```
{Same structure} **Docs:** [URL]
{... continue for each significant option ...} ## [Continue for each feature...]
## Recommendations ## Constraint Compatibility
### Use | Constraint | Status | Notes |
|------------|--------|-------|
| [constraint 1] | ✓ Compatible | [brief note] |
| [constraint 2] | ✓ Compatible | [brief note] |
- **{Library A}** - {One-line reason, specific use case} ## Unanswered
- **{Library B}** - {One-line reason, specific use case}
### Avoid - [Any features where no clear library choice exists]
- [Any constraints that couldn't be satisfied]
```
- **{Library X}** - {One-line reason} ## Quality Checklist
- **Hand-rolling {Y}** - {Existing solution available}
### Defer Decision Before writing output, verify:
- [ ] Every feature from manifest has a library recommendation
- **{Topic}** - {Why more investigation needed} - [ ] Every library is actively maintained
- [ ] Current versions specified (not "latest")
## Sources - [ ] Setup code is current syntax
- [ ] No low-confidence padding included
| Source | Type | Confidence | Last Verified |
|--------|------|------------|---------------|
| {URL} | {official docs / github / blog} | {high/medium/low} | {today} |
## Open Questions
- {Question that couldn't be resolved}
- {Question for roadmap planning}
---
*Generated by research-project subagent*
*Category: ecosystem*
## Quality Criteria
- Include at least 3-5 library/framework options
- Compare options (don't just list them)
- Every recommendation has a specific reason
- Verify all versions are current
- Note what NOT to hand-roll
</subagent_prompt> </subagent_prompt>
``` ```
</ecosystem_subagent_prompt> </stack_subagent_prompt>
<architecture_subagent_prompt> <implementation_subagent_prompt>
## Architecture Research Subagent ## Implementation Research Subagent
Use this template for spawning architecture research subagents: Use this template for spawning implementation research subagents:
``` ```
<subagent_prompt> <subagent_prompt>
## Objective ## Objective
Research architecture patterns for {domain} projects and write findings to .planning/research/architecture.md
## Domain Context Research and document CURRENT implementation patterns for this project's stack.
{Paste relevant sections from PROJECT.md describing what's being built} Write findings to .planning/research/implementation.md
## Critical Context
**This research is for Claude Code, not humans.**
Claude may generate outdated code patterns. Your job is to provide:
- Current API syntax (not deprecated alternatives)
- Working code examples (not pseudocode)
- "Do this, not that" corrections
**Quality bar:** Claude reads this file, then generates correct modern code.
## Research Manifest
{Paste the research manifest extracted from PROJECT.md}
## Your Assignment ## Your Assignment
File: .planning/research/architecture.md
Category: architecture
Purpose: Document standard project structure and architectural patterns
## Research Questions For the stack chosen in stack.md (or infer from manifest):
Answer these questions through web research: 1. What are the CURRENT API patterns?
1. How do experts structure projects in this domain? 2. What code does Claude need to generate correctly?
2. What component boundaries work best? 3. What deprecated patterns might Claude default to?
3. What patterns prevent common problems?
4. How does data flow in typical implementations? For Open Questions in the manifest:
5. What directory structure do production projects use? 1. Research and provide direct answers
2. If unanswerable, explain why
## Research Requirements ## Research Requirements
You MUST use WebSearch and Context7 to get current information. Use WebSearch and Context7 for current documentation.
For EACH pattern discovered: **INCLUDE:**
1. Find real-world examples (GitHub repos, case studies) - Actual code examples with current syntax
2. Understand the tradeoffs - "Do this (current)" vs "Not this (deprecated)" comparisons
3. Note when it applies vs when it doesn't - Version-specific patterns (as of 2024-2025)
4. Find implementation guidelines - Answers to Open Questions from manifest
**Search queries to run:** **EXCLUDE:**
- "{domain} project structure best practices" - Theoretical explanations without code
- "{domain} architecture patterns" - Multiple options without recommendation
- "{specific problem from PROJECT.md} implementation patterns" - Old patterns from outdated tutorials
- "{domain} component organization" - Generic advice not specific to this project
- "{domain} example github repo structure"
## Output Format ## Output Format
Write to .planning/research/architecture.md using this structure: Write to .planning/research/implementation.md:
# Architecture: {Domain} ```markdown
# Implementation: [Project Name]
**Category:** architecture **Purpose:** Current API patterns for Claude Code to use
**Domain:** {domain} **Researched:** [date]
**Researched:** {today's date}
**Confidence:** {high | medium | low}
## Research Summary ## [Feature 1] Implementation
{2-3 sentences on recommended architectural approach} ### Current Pattern (2025)
## Findings ```[language]
// Correct way to do [thing]
### Project Structure [actual working code]
Recommended directory layout:
```
{concrete directory structure with comments}
``` ```
**Source:** {Reference project or documentation} ### NOT This (Deprecated)
**Rationale:** {Why this structure works}
### {Pattern 1 Name} ```[language]
// Claude may generate this - it's outdated
[old pattern to avoid]
// Why wrong: [brief explanation]
```
**When to use:** {Specific scenarios} ### Key API Details
**Implementation:** {How to implement}
**Example:** {Concrete code example if applicable}
**Tradeoffs:** {What you give up}
### {Pattern 2 Name} - `methodName()` - [what it does, when to use]
- `otherMethod()` - [what it does, when to use]
{Same structure} ## [Feature 2] Implementation
### Data Flow [Same structure]
{How data moves through the system} ## Open Questions Answered
### Component Boundaries ### [Question 1 from manifest]
{What should be separate vs combined} **Answer:** [Direct answer with source]
## Recommendations ### [Question 2 from manifest]
### Adopt **Answer:** [Direct answer with source]
- **{Pattern A}** - {Why it fits this project} ## Decisions Validated
- **{Structure B}** - {Why it fits this project}
### Avoid ### [Decision 1 from manifest]
- **{Anti-pattern X}** - {Why it fails} **Validation:** ✓ Good choice / ⚠️ Gotcha
- **{Premature abstraction Y}** - {Why to defer} **Notes:** [Any implementation considerations]
## Sources ## Patterns Summary
| Source | Type | Confidence | Last Verified | | Task | Current Pattern | Deprecated Pattern |
|--------|------|------------|---------------| |------|-----------------|-------------------|
| {URL} | {official docs / github / tutorial} | {high/medium/low} | {today} | | [task 1] | `doThisWay()` | `oldWay()` |
| [task 2] | `async/await` | `callbacks` |
```
## Open Questions ## Quality Checklist
- {Architecture decision that needs more context} Before writing output, verify:
- {Question about project-specific constraints} - [ ] Every code example is runnable (not pseudocode)
- [ ] Deprecated patterns explicitly flagged
--- - [ ] Open Questions from manifest answered
*Generated by research-project subagent* - [ ] Decisions from manifest validated
*Category: architecture* - [ ] No "it depends" - give clear recommendations
## Quality Criteria
- Include concrete directory structure
- Document at least 2-3 patterns
- Every recommendation has specific rationale
- Include real example sources
- Address data flow and component boundaries
</subagent_prompt> </subagent_prompt>
``` ```
</architecture_subagent_prompt> </implementation_subagent_prompt>
<pitfalls_subagent_prompt> <risks_subagent_prompt>
## Pitfalls Research Subagent ## Risks Research Subagent
Use this template for spawning pitfalls research subagents: Use this template for spawning risks research subagents:
``` ```
<subagent_prompt> <subagent_prompt>
## Objective ## Objective
Research common mistakes and pitfalls in {domain} projects and write findings to .planning/research/pitfalls.md
## Domain Context Research what Claude Code might get WRONG when implementing this project.
{Paste relevant sections from PROJECT.md describing what's being built} Write findings to .planning/research/risks.md
## Critical Context
**This research is for Claude Code, not humans.**
Claude's training data includes outdated tutorials, deprecated APIs, and bad patterns. Your job is to identify:
- What Claude might generate incorrectly
- Deprecated patterns to explicitly avoid
- Common implementation mistakes in this domain
**Quality bar:** After reading this, Claude avoids specific mistakes.
## Research Manifest
{Paste the research manifest extracted from PROJECT.md}
## Your Assignment ## Your Assignment
File: .planning/research/pitfalls.md
Category: pitfalls
Purpose: Catalog what NOT to do and why
## Research Questions For this project's domain and stack:
Answer these questions through web research: 1. What deprecated patterns might Claude default to?
1. What mistakes do beginners commonly make in this domain? 2. What common mistakes happen in this domain?
2. What causes performance problems? 3. What version-specific gotchas exist?
3. What architectural choices lead to regret?
4. What seems like a good idea but isn't? For Decisions in the manifest:
5. What are the debugging nightmares people warn about? 1. Any known issues with these choices?
2. Pitfalls specific to this combination?
## Research Requirements ## Research Requirements
You MUST use WebSearch and Context7 to get current information. Use WebSearch to find:
- GitHub issues about common mistakes
- Stack Overflow questions about gotchas
- Migration guides showing old → new patterns
- "Things I wish I knew" posts
For EACH pitfall discovered: **INCLUDE:**
1. Find real examples (Stack Overflow, GitHub issues, blog posts) - Specific mistakes with code examples
2. Understand the root cause - Version-specific deprecations
3. Find the correct approach - Domain-specific pitfalls for this project
4. Note detection methods (how to know if you're doing this)
**Search queries to run:** **EXCLUDE:**
- "{domain} common mistakes" - Generic coding advice
- "{domain} things I wish I knew" - Low-probability edge cases
- "{domain} performance problems" - "Best practices" (that's not risks)
- "{domain} debugging nightmare" - Risks that don't apply to this specific project
- "{specific technology} gotchas"
- "{domain} anti-patterns"
## Output Format ## Output Format
Write to .planning/research/pitfalls.md using this structure: Write to .planning/research/risks.md:
# Pitfalls: {Domain} ```markdown
# Risks: [Project Name]
**Category:** pitfalls **Purpose:** What Claude Code might get wrong
**Domain:** {domain} **Researched:** [date]
**Researched:** {today's date}
**Confidence:** {high | medium | low}
## Research Summary ## Deprecated Patterns to Avoid
{2-3 sentences on the most critical pitfalls to avoid} ### [Deprecated Thing 1]
## Findings **Claude might generate:**
```[language]
// This is outdated
[deprecated code pattern]
```
### {Pitfall 1: Descriptive Name} **Instead use:**
```[language]
// Current approach
[correct code pattern]
```
**Problem:** {What people do wrong} **Why:** [Deprecated in vX.Y, removed in vX.Z, etc.]
**Why it happens:** {Root cause or common misconception}
**Consequence:** {What goes wrong}
**Detection:** {How to know if you're doing this}
**Prevention:** {Correct approach}
**Source:** {URL with real example} ### [Deprecated Thing 2]
**Severity:** {high | medium | low}
### {Pitfall 2: Descriptive Name} [Same structure]
{Same structure} ## Common Mistakes
{... continue for each significant pitfall ...} ### [Mistake 1: Descriptive Name]
## Recommendations **What happens:** [The incorrect approach]
**Why it's wrong:** [Consequence]
**Correct approach:** [What to do instead]
### Critical Pitfalls (Must Avoid) ```[language]
// Wrong
[bad code]
1. **{Pitfall A}** - {One-line why it's critical} // Right
2. **{Pitfall B}** - {One-line why it's critical} [good code]
```
### Common But Recoverable ### [Mistake 2]
- **{Pitfall C}** - {Can be fixed if caught early} [Same structure]
### Easy Wins ## Stack-Specific Gotchas
- **{Prevention D}** - {Simple thing that prevents problems} ### [Gotcha for chosen library/framework]
## Sources **Issue:** [What goes wrong]
**When:** [Trigger conditions]
**Fix:** [How to avoid/handle]
| Source | Type | Confidence | Last Verified | ## Decision Risks
|--------|------|------------|---------------|
| {URL} | {stack overflow / github issue / blog} | {high/medium/low} | {today} |
## Open Questions ### [Decision 1 from manifest]
- {Potential pitfall that needs more context} **Risk level:** Low / Medium / High
- {Question about project-specific risks} **Specific concern:** [What could go wrong with this choice]
**Mitigation:** [How to avoid the problem]
--- ## Critical Warnings
*Generated by research-project subagent*
*Category: pitfalls*
## Quality Criteria 1. **[Most important thing to not mess up]**
- Include at least 5-7 pitfalls 2. **[Second most important]**
- Categorize by severity 3. **[Third most important]**
- Every pitfall has prevention/solution ```
- Include real examples with sources
- Focus on domain-specific issues (not generic coding advice) ## Quality Checklist
Before writing output, verify:
- [ ] Every risk is specific (not generic advice)
- [ ] Code examples show wrong vs right
- [ ] Risks are relevant to this project's stack
- [ ] No padding with unlikely scenarios
- [ ] Critical warnings prioritized
</subagent_prompt> </subagent_prompt>
``` ```
</pitfalls_subagent_prompt> </risks_subagent_prompt>
<standards_subagent_prompt>
## Standards Research Subagent
Use this template for spawning standards research subagents:
```
<subagent_prompt>
## Objective
Research best practices and quality standards for {domain} projects and write findings to .planning/research/standards.md
## Domain Context
{Paste relevant sections from PROJECT.md describing what's being built}
## Your Assignment
File: .planning/research/standards.md
Category: standards
Purpose: Document best practices, conventions, and quality expectations
## Research Questions
Answer these questions through web research:
1. What does "production quality" mean for this domain?
2. What testing approaches work for this type of project?
3. What performance benchmarks matter?
4. What accessibility/security considerations apply?
5. What conventions do experts follow?
## Research Requirements
You MUST use WebSearch and Context7 to get current information.
For EACH standard discovered:
1. Find authoritative sources (official docs, style guides)
2. Understand the rationale
3. Find measurable criteria where possible
4. Note enforcement tools if available
**Search queries to run:**
- "{domain} best practices 2024 2025"
- "{domain} style guide"
- "{domain} testing strategy"
- "{domain} performance benchmarks"
- "{domain} production checklist"
- "{domain} code quality standards"
## Output Format
Write to .planning/research/standards.md using this structure:
# Standards: {Domain}
**Category:** standards
**Domain:** {domain}
**Researched:** {today's date}
**Confidence:** {high | medium | low}
## Research Summary
{2-3 sentences on key quality standards for this project}
## Findings
### Code Quality
**Conventions:**
- {Naming conventions}
- {Formatting standards}
- {Organization patterns}
**Tools:** {Linters, formatters, static analysis}
**Source:** {URL}
### Testing Standards
**Strategy:** {How to test this type of project}
**Coverage expectations:** {What to test, what's overkill}
**Tools:** {Testing frameworks and utilities}
**Source:** {URL}
### Performance Standards
**Benchmarks:** {What metrics matter}
**Targets:** {Specific numbers if applicable}
**Measurement:** {How to test}
**Source:** {URL}
### {Domain-Specific Standard}
{Standards specific to this domain}
## Recommendations
### Adopt
- **{Standard A}** - {Why it applies}
- **{Convention B}** - {Why it matters}
### Skip (Over-Engineering)
- **{Standard X}** - {Why not needed for this project}
### Defer
- **{Standard Y}** - {Consider after MVP}
## Sources
| Source | Type | Confidence | Last Verified |
|--------|------|------------|---------------|
| {URL} | {official docs / style guide / blog} | {high/medium/low} | {today} |
## Open Questions
- {Standard that depends on project scale}
- {Question about appropriate rigor level}
---
*Generated by research-project subagent*
*Category: standards*
## Quality Criteria
- Cover code quality, testing, and performance
- Include measurable criteria where possible
- Distinguish must-haves from nice-to-haves
- Reference authoritative sources
- Be realistic about project scope (not enterprise overkill)
</subagent_prompt>
```
</standards_subagent_prompt>
<task_tool_usage> <task_tool_usage>
## Using the Task Tool ## Using the Task Tool
When spawning research subagents, use the Task tool with: Spawn all 3 subagents in a SINGLE message:
- `subagent_type`: "general-purpose"
- `prompt`: The filled-in template above
- `description`: Brief description like "Research ecosystem for {domain}"
**Batching strategy:**
Spawn 3-4 Task calls in a SINGLE message. Wait for all to complete before next batch.
``` ```
[Message 1: Batch 1] Task 1:
Task: Research ecosystem for {domain} subagent_type: "general-purpose"
Task: Research architecture for {domain} description: "Research stack for [project]"
[Wait for completion] prompt: [stack_subagent_prompt with manifest]
[Message 2: Batch 2] Task 2:
Task: Research pitfalls for {domain} subagent_type: "general-purpose"
Task: Research standards for {domain} description: "Research implementation for [project]"
[Wait for completion] prompt: [implementation_subagent_prompt with manifest]
Task 3:
subagent_type: "general-purpose"
description: "Research risks for [project]"
prompt: [risks_subagent_prompt with manifest]
``` ```
**Batch ordering rationale:** Wait for all to complete, then verify outputs.
- Batch 1 (ecosystem + architecture): Core understanding of what to build and how
- Batch 2 (pitfalls + standards): Refinements that build on core understanding
**After all batches complete:**
1. Verify all 4 files exist in .planning/research/
2. Extract key findings for summary
3. Present next steps to user
</task_tool_usage> </task_tool_usage>
<quality_checklist> <quality_verification>
## Subagent Quality Verification ## Post-Research Quality Check
After subagents complete, verify: After subagents complete, verify each file:
- [ ] All 4 files exist in .planning/research/ **stack.md:**
- [ ] Each file has substantive content (not stub/error) - [ ] Every manifest feature has a library
- [ ] Recommendations are specific (not "it depends") - [ ] Current versions specified
- [ ] Sources are cited with confidence levels - [ ] Setup code included
- [ ] Information is current (2024-2025 sources preferred) - [ ] No low-confidence alternatives
- [ ] Open questions are honest about gaps
</quality_checklist> **implementation.md:**
- [ ] Code examples are runnable
- [ ] Deprecated patterns flagged
- [ ] Open Questions answered
- [ ] Decisions validated
**risks.md:**
- [ ] Risks specific to this project
- [ ] Wrong vs right code shown
- [ ] No generic advice padding
- [ ] Critical warnings clear
**If a file fails quality check:**
Re-run that specific subagent with stricter instructions, or flag the gap for the user.
</quality_verification>

View File

@@ -1,181 +1,243 @@
# Project Research Template # Project Research Template
Template for `.planning/research/{category}.md` - project-level domain research written by subagents. Template for `.planning/research/{category}.md` - implementation context for Claude Code.
--- ---
## File Template <philosophy>
## What This Research Is
**Context injection for Claude Code implementation quality.**
This is NOT research for humans to make decisions.
This is context that Claude Code reads during implementation to generate correct, modern code.
**Quality bar:** Will this make Claude generate better code?
**Include:** High-confidence, directly actionable, current patterns with code examples
**Exclude:** Low-confidence, generic advice, "might be useful" padding, outdated patterns
</philosophy>
---
## stack.md Template
```markdown ```markdown
# {Category}: {Domain} # Stack: [Project Name]
**Category:** {ecosystem | architecture | pitfalls | standards} **Purpose:** Libraries and tools for Claude Code to use during implementation
**Domain:** {domain from PROJECT.md} **Researched:** [date]
**Researched:** {date}
**Confidence:** {high | medium | low}
## Research Summary ## [Feature 1 from PROJECT.md Scope]
{2-3 sentence overview of what was found and why it matters for this project} **Use:** [Library Name] v[X.Y.Z]
**Why:** [One sentence - why this library for this feature]
## Findings ```[language]
// Setup / import
import { Thing } from 'library'
### {Finding 1 Title} // Basic usage
const result = Thing.doThing()
```
{What was discovered} **Docs:** [URL to current documentation]
**Source:** {URL or documentation reference} ## [Feature 2 from PROJECT.md Scope]
**Confidence:** {high | medium | low}
**Relevance:** {Why this matters for the project}
### {Finding 2 Title} **Use:** [Library Name] v[X.Y.Z]
**Why:** [One sentence]
{What was discovered} ```[language]
// Setup / import
[actual code]
```
**Source:** {URL or documentation reference} **Docs:** [URL]
**Confidence:** {high | medium | low}
**Relevance:** {Why this matters for the project}
{... additional findings ...} ## [Continue for each feature in Scope...]
## Recommendations ## Constraint Compatibility
### Use | Constraint | Status | Notes |
|------------|--------|-------|
| [constraint from PROJECT.md] | ✓ Compatible | [brief note] |
| [constraint from PROJECT.md] | ✓ Compatible | [brief note] |
- **{Library/Pattern/Tool}** - {One line why} ## Unanswered
- **{Library/Pattern/Tool}** - {One line why}
### Avoid - [Any features where no clear library choice exists - be honest]
- **{Thing to avoid}** - {One line why}
- **{Thing to avoid}** - {One line why}
### Defer Decision
- **{Topic}** - {Why more info needed}
## Sources
| Source | Type | Confidence | Last Verified |
|--------|------|------------|---------------|
| {URL or reference} | {official docs / blog / github / forum} | {high/medium/low} | {date} |
| {URL or reference} | {type} | {confidence} | {date} |
## Open Questions
- {Question that couldn't be resolved}
- {Question that needs more context}
- {Question for roadmap planning to consider}
---
*Generated by research-project subagent*
*Category: {category}*
``` ```
--- ---
<category_guides> ## implementation.md Template
## Category-Specific Guidance ```markdown
# Implementation: [Project Name]
### ecosystem.md **Purpose:** Current API patterns for Claude Code to use
**Researched:** [date]
**Purpose:** Map the library/framework landscape for this domain ## [Feature 1] Implementation
**Key questions to answer:** ### Current Pattern (2025)
- What are the go-to libraries for this problem?
- Which frameworks are actively maintained?
- What's the "standard stack" experts use?
- What NOT to hand-roll (existing solutions exist)?
**Structure emphasis:** ```[language]
- Compare 2-4 main options // Correct way to implement [feature]
- Clear "use X when..." guidance [actual working code - not pseudocode]
- Version currency (is it maintained?) ```
- Integration considerations
### architecture.md ### NOT This (Deprecated)
**Purpose:** Document standard project structure and patterns ```[language]
// Claude may generate this - it's outdated
[old pattern]
// Why wrong: [deprecated in vX, removed in vY, causes Z problem]
```
**Key questions to answer:** ### Key APIs
- How do experts organize code for this domain?
- What patterns prevent common problems?
- What component boundaries make sense?
- How does data flow in typical implementations?
**Structure emphasis:** - `methodName(params)` - [what it does, when to use]
- Directory structure recommendations - `otherMethod(params)` - [what it does, when to use]
- Component organization patterns
- State management approaches
- Integration patterns with related systems
### pitfalls.md ## [Feature 2] Implementation
**Purpose:** Catalog what NOT to do and why [Same structure]
**Key questions to answer:** ## Open Questions Answered
- What mistakes do beginners commonly make?
- What causes performance problems?
- What architectural choices cause regret?
- What seems like a good idea but isn't?
**Structure emphasis:** ### [Question from PROJECT.md Open Questions]
- Clear problem → consequence → solution
- Real examples of failures
- Detection (how to know if you're doing this)
- Prevention (how to avoid)
### standards.md **Answer:** [Direct answer]
**Source:** [URL or documentation reference]
**Purpose:** Document best practices and quality expectations ### [Question 2]
**Key questions to answer:** **Answer:** [Direct answer or "Could not determine - [reason]"]
- What does "production quality" mean for this domain?
- What testing approaches work?
- What performance benchmarks matter?
- What accessibility/security considerations apply?
**Structure emphasis:** ## Decisions Validated
- Measurable quality criteria
- Testing strategies that work
- Performance targets
- Common standards/conventions
</category_guides> ### [Decision from PROJECT.md Decisions Made]
<difference_from_phase_research> **Validation:** ✓ Good choice / ⚠️ Has gotchas
## How This Differs from Phase-Level Research **Notes:** [Implementation considerations Claude should know]
**project-research.md (this template):** ## Quick Reference
- Written BEFORE roadmap exists
- Informs phase structure and scope
- Ecosystem-level landscape view
- Answers "what tools/patterns should we use?"
**research.md (phase-level):** | Task | Current Pattern | Deprecated Pattern |
- Written AFTER roadmap exists |------|-----------------|-------------------|
- Informs specific phase implementation | [common task 1] | `newWay()` | `oldWay()` |
- Implementation-level detail | [common task 2] | `async/await` | `.then()` chains |
- Answers "how do we implement this phase?" ```
Project research is strategic (shapes the roadmap). ---
Phase research is tactical (shapes the implementation).
</difference_from_phase_research>
<quality_bar> ## risks.md Template
## Quality Expectations
A well-written research file: ```markdown
- Has specific, actionable recommendations (not "it depends") # Risks: [Project Name]
- Cites sources with confidence levels
- Distinguishes verified facts from educated guesses **Purpose:** What Claude Code might get wrong
- Surfaces open questions honestly **Researched:** [date]
- Can be read in 2-3 minutes and inform a decision
## Deprecated Patterns to Avoid
### [Deprecated Thing 1]
**Claude might generate:**
```[language]
// This is outdated - from old tutorials/training data
[deprecated code pattern]
```
**Instead use:**
```[language]
// Current approach (2025)
[correct code pattern]
```
**Why:** Deprecated in v[X], removed in v[Y]. [Brief explanation]
### [Deprecated Thing 2]
[Same structure]
## Common Mistakes
### [Mistake 1: Descriptive Name]
**What happens:** [The incorrect approach Claude might take]
**Why it's wrong:** [Specific consequence - performance, bugs, etc.]
**Correct approach:**
```[language]
// Wrong
[bad code]
// Right
[good code]
```
## Stack-Specific Gotchas
### [Gotcha for this project's chosen stack]
**Issue:** [What goes wrong]
**When:** [Trigger conditions]
**Fix:** [How to avoid or handle]
## Decision Risks
### [Decision from PROJECT.md]
**Risk level:** Low / Medium / High
**Concern:** [What could go wrong with this choice]
**Mitigation:** [How to avoid the problem]
## Critical Warnings
1. **[Most important thing Claude must not mess up]**
2. **[Second most important]**
3. **[Third most important]**
```
---
<quality_rules>
## Quality Rules
### INCLUDE:
- High-confidence information only
- Actual code examples (runnable, not pseudocode)
- Current syntax (2024-2025)
- Direct answers to PROJECT.md questions
- Specific recommendations tied to manifest features
### EXCLUDE:
- Low or medium confidence items
- "Might be useful" padding
- Generic advice not specific to this project
- Options without clear recommendation
- Old repos/articles acknowledged as outdated
- Anything that doesn't directly improve Claude's implementation
### Format for Claude Consumption:
Every recommendation should include:
1. What to use (specific, versioned)
2. Why (one sentence)
3. How (actual code)
4. What NOT to do (if relevant)
### No Padding Rule:
If you can't find high-confidence information for something, say so:
- "Could not determine - no authoritative source found"
- "Unanswered - requires experimentation"
This is better than padding with low-quality guesses.
</quality_rules>
**Avoid:**
- Generic advice that applies to anything
- Recommendations without reasoning
- Outdated information (pre-2024 unless fundamental)
- Confidence without verification
</quality_bar>

View File

@@ -1,14 +1,42 @@
<purpose> <purpose>
Orchestrate batched subagent research for domain ecosystems before roadmap creation. Research implementation context for Claude Code before roadmap creation.
Subagents write directly to `.planning/research/` to preserve main context. This is NOT research for human decision-making.
Maximum 4 parallel subagents, recommended batch size 3. This is CONTEXT INJECTION so Claude Code implements correctly.
Research quality directly impacts implementation quality.
Claude's training data may have outdated APIs, deprecated patterns, old syntax.
This research provides current, accurate context to override stale knowledge.
</purpose> </purpose>
<research_philosophy>
## What This Research Is
**Context injection for Claude Code implementation quality.**
Claude Code will read these files during implementation. The research should:
- Override outdated patterns Claude might default to
- Provide current API syntax and code examples
- Explicitly correct common mistakes Claude makes
- Include version-specific details (as of 2024-2025)
## What This Research Is NOT
- A survey of options for humans to choose from
- Generic "best practices" documentation
- Padding with low-confidence "might be useful" items
- Academic completeness over practical utility
## Quality Bar
**Include if:** High confidence, directly actionable, will improve Claude's implementation
**Exclude if:** Low confidence, tangential, "might be relevant", padding
</research_philosophy>
<required_reading> <required_reading>
**Read before executing:** **Read before executing:**
1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates for each category 1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates
2. `~/.claude/get-shit-done/templates/project-research.md` - Output format subagents use 2. `~/.claude/get-shit-done/templates/project-research.md` - Output format
</required_reading> </required_reading>
<process> <process>
@@ -20,172 +48,176 @@ Create research directory:
mkdir -p .planning/research mkdir -p .planning/research
``` ```
Parse PROJECT.md to extract: Parse PROJECT.md to create research manifest:
- Domain keywords (technology mentions, problem space)
- Constraints that affect ecosystem choices ```
- Any mentioned preferences or requirements ## Research Manifest
### Features to Implement
[Extract from Scope > Building]
- Feature 1: [description]
- Feature 2: [description]
- Feature 3: [description]
### Stack Constraints
[Extract from Constraints]
- [constraint 1]
- [constraint 2]
### Open Questions to Answer
[Extract from Open Questions]
- [question 1]
- [question 2]
### Decisions to Validate
[Extract from Decisions Made]
- [decision 1]: Any gotchas?
```
This manifest drives ALL research. Subagents research these specific items, not generic domain knowledge.
</step> </step>
<step name="define_research_categories"> <step name="define_research_categories">
Standard research categories: Three research categories, each PROJECT.md-driven:
1. **ecosystem.md** - Libraries, frameworks, tools for this domain 1. **stack.md** - What to use for each feature
2. **architecture.md** - Patterns, project structure, component organization - For each feature in Scope: what library/tool?
3. **pitfalls.md** - Common mistakes, what NOT to do, performance traps - For each constraint: what works within it?
4. **standards.md** - Best practices, conventions, quality expectations - Current versions, import statements, setup code
Each subagent researches ONE category and writes directly to `.planning/research/{category}.md` 2. **implementation.md** - How to implement correctly
- Current API patterns for chosen stack
- Actual code examples with correct syntax
- "Do this (current) not that (deprecated)"
3. **risks.md** - What Claude might get wrong
- Deprecated patterns Claude may default to
- Common implementation mistakes
- Version-specific gotchas
Each subagent writes directly to `.planning/research/{category}.md`
</step> </step>
<step name="batch_execution"> <step name="spawn_subagents">
## Batched Subagent Spawning ## Subagent Spawning
Read prompt templates from `~/.claude/get-shit-done/references/research-subagent-prompts.md` Read prompt templates from `~/.claude/get-shit-done/references/research-subagent-prompts.md`
**Batch 1: Foundation research** (spawn in parallel) **Single batch (spawn all 3 in parallel):**
Spawn using Task tool with `subagent_type="general-purpose"`:
``` ```
Task 1: Task 1:
description: "Research ecosystem for {domain}" description: "Research stack for [project]"
prompt: [ecosystem_subagent_prompt template filled with PROJECT.md context] prompt: [stack_subagent_prompt with research manifest]
Task 2: Task 2:
description: "Research architecture for {domain}" description: "Research implementation for [project]"
prompt: [architecture_subagent_prompt template filled with PROJECT.md context] prompt: [implementation_subagent_prompt with research manifest]
```
Send BOTH Task calls in a single message. Wait for Batch 1 completion.
**Batch 2: Risk & quality research** (spawn in parallel)
```
Task 3: Task 3:
description: "Research pitfalls for {domain}" description: "Research risks for [project]"
prompt: [pitfalls_subagent_prompt template filled with PROJECT.md context] prompt: [risks_subagent_prompt with research manifest]
Task 4:
description: "Research standards for {domain}"
prompt: [standards_subagent_prompt template filled with PROJECT.md context]
``` ```
Send BOTH Task calls in a single message. Wait for Batch 2 completion. Send ALL Task calls in a single message. Wait for completion.
**Batch ordering rationale:**
- Batch 1 (ecosystem + architecture): Core understanding of what to build and how
- Batch 2 (pitfalls + standards): Refinements that build on core understanding
**Each subagent receives:** **Each subagent receives:**
- Domain context from PROJECT.md - The research manifest (features, constraints, questions, decisions)
- Category assignment (ecosystem, architecture, pitfalls, standards) - Category assignment (stack, implementation, risks)
- Output format from templates/project-research.md - Output format from templates/project-research.md
- Instruction to write directly to `.planning/research/{category}.md` - Instruction: HIGH-CONFIDENCE ONLY
</step> </step>
<step name="verify_outputs"> <step name="verify_outputs">
After all batches complete: After subagents complete:
```bash ```bash
# Check all files exist # Check all files exist
ls -la .planning/research/ ls -la .planning/research/
# Verify each file has content # Verify each file has content
for f in ecosystem architecture pitfalls standards; do for f in stack implementation risks; do
[ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING" [ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING"
done done
``` ```
**If any file missing:** **Quality verification (read each file):**
- Log which subagent failed
- Optionally retry that specific subagent For each file, check:
- Continue with available research (partial is better than none) - [ ] Addresses specific features from research manifest?
- [ ] Contains actual code examples?
- [ ] No low-confidence items included?
- [ ] Current syntax (2024-2025)?
**If quality issues found:**
- Note specific problems
- Consider re-running that subagent with stricter prompt
- Or flag for manual review
</step> </step>
<step name="aggregate"> <step name="aggregate">
Read key findings from each research file for summary: Extract key findings for summary:
```bash From stack.md:
# Extract first few lines of each for summary - Primary libraries chosen for each feature
for f in .planning/research/*.md; do - Any constraint-driven choices
echo "=== $(basename $f) ==="
head -20 "$f"
echo ""
done
```
Extract for user summary: From implementation.md:
- Top library/framework recommendation from ecosystem.md - Most important API patterns
- Primary architecture pattern from architecture.md - Key code examples
- Most critical pitfall from pitfalls.md
- Key quality standard from standards.md From risks.md:
- Critical mistakes to avoid
- Deprecated patterns flagged
Present summary to user with next steps.
</step> </step>
</process> </process>
<batching_rules> <subagent_quality_rules>
## Batching Configuration ## Quality Rules for Subagents
**Maximum parallel subagents:** 4 (API safety limit) **INCLUDE:**
**Recommended batch size:** 3 (reliable) - High-confidence, verified information
- Current API patterns with actual code
- Direct answers to Open Questions from PROJECT.md
- Specific recommendations for features in Scope
**Batch ordering rationale:** **EXCLUDE:**
- Batch 1 (ecosystem + architecture): Foundation knowledge that informs everything - Low or medium confidence items
- Batch 2 (pitfalls + standards): Risk and quality that build on foundation - "Might be useful" padding
- Generic advice not specific to this project
- Old repos/articles marked as outdated
- Options without clear recommendation
**Between batches:** **Format for Claude consumption:**
- Verify all subagents in batch completed ```markdown
- Check for failures, note for retry if needed ## [Feature Name] Implementation
- Proceed to next batch
</batching_rules>
<subagent_template> **Use:** [Library] v[X.Y]
## Task Tool Invocation Pattern
For each subagent, use: ```[language]
// Current pattern (2025)
``` import { Thing } from 'library'
Task tool parameters: const result = await Thing.doCorrectThing()
- subagent_type: "general-purpose"
- description: "Research {category} for {domain}"
- prompt: [filled template from research-subagent-prompts.md]
``` ```
**Prompt template (simplified):** **NOT:**
```[language]
// Deprecated - Claude may generate this
import Thing from 'library' // Old syntax
Thing.doOldThing() // Removed in v2.0
``` ```
Research and write {category}.md for {domain} domain.
## Context
{Paste relevant sections from PROJECT.md}
## Your Assignment
File: .planning/research/{category}.md
Category: {category}
Purpose: {category-specific purpose}
## Research Requirements
Use WebSearch to find current information. Verify:
- Libraries are actively maintained (commits in last 12 months)
- Patterns are current best practice (not deprecated)
- Examples are from 2024-2025 sources where possible
## Output
Write directly to .planning/research/{category}.md using the template structure:
- research_summary
- findings (specific discoveries with sources)
- recommendations (actionable guidance)
- sources (where info came from, confidence level)
- open_questions (what couldn't be resolved)
Quality bar: Someone reading this should be able to make informed decisions about the roadmap.
``` ```
</subagent_template> </subagent_quality_rules>
<success_criteria> <success_criteria>
Research workflow complete when: Research workflow complete when:
- [ ] All 4 research files exist in .planning/research/ - [ ] All 3 research files exist in .planning/research/
- [ ] Each file has substantive content (not empty/error) - [ ] Each file addresses PROJECT.md features specifically
- [ ] Key findings extracted for summary - [ ] Open Questions from PROJECT.md are answered
- [ ] Main agent context preserved (minimal usage) - [ ] Only high-confidence information included
- [ ] Code examples use current syntax
- [ ] Main agent context preserved
</success_criteria> </success_criteria>