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

@@ -1,557 +1,451 @@
# Research Subagent Prompts
<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:
- 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`
- Uses WebSearch and Context7 for current information
- Cross-verifies findings with authoritative sources
- Formats output for Claude Code to consume during implementation
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>
<ecosystem_subagent_prompt>
## Ecosystem Research Subagent
<stack_subagent_prompt>
## Stack Research Subagent
Use this template for spawning ecosystem research subagents:
Use this template for spawning stack research subagents:
```
<subagent_prompt>
## Objective
Research the library/framework ecosystem for {domain} and write findings to .planning/research/ecosystem.md
## Domain Context
{Paste relevant sections from PROJECT.md describing what's being built}
Research and document the libraries/tools needed for THIS specific project.
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
File: .planning/research/ecosystem.md
Category: ecosystem
Purpose: Map the libraries, frameworks, and tools available for this domain
## Research Questions
Answer these questions through web research:
1. What are the go-to libraries for this problem space?
2. Which frameworks are actively maintained (commits in last 12 months)?
3. What's the "standard stack" that domain experts use?
4. What should NOT be hand-rolled because existing solutions exist?
5. What are the version requirements and compatibility considerations?
For EACH feature in the manifest:
1. What library/tool should Claude use?
2. What's the current version?
3. What's the correct import/setup?
For EACH constraint in the manifest:
1. Does the recommended library work within this constraint?
2. Any compatibility issues?
## 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:
1. Verify actively maintained (GitHub commits in last 12 months)
2. Get current version number
3. Understand when to use vs alternatives
4. Find official documentation and getting started guides
5. Note any critical dependencies or compatibility issues
**INCLUDE only if:**
- Actively maintained (commits in last 12 months)
- High confidence this is the right choice
- Directly relevant to a feature in the manifest
**Search queries to run:**
- "{domain} best libraries 2024 2025"
- "{domain} framework comparison"
- "{specific problem from PROJECT.md} library recommendation"
- "{domain} standard stack production"
**Red flags (reject these):**
- No updates in 12+ months
- Deprecated or archived repositories
- Pre-2023 recommendations without verification
**EXCLUDE:**
- Low or medium confidence options
- "Might be useful" alternatives
- Deprecated or unmaintained libraries
- Generic options not tied to manifest features
## 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
**Domain:** {domain}
**Researched:** {today's date}
**Confidence:** {high | medium | low}
**Purpose:** Libraries and tools for Claude Code to use during implementation
**Researched:** [date]
## 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}
**Version:** {current version}
**Confidence:** {high | medium | low}
**Why consider:** {Relevance to project}
**Tradeoffs:** {Limitations or considerations}
**Use:** [Library Name] v[X.Y.Z]
**Why:** [One sentence]
### {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}
- **{Library B}** - {One-line reason, specific use case}
## Unanswered
### Avoid
- [Any features where no clear library choice exists]
- [Any constraints that couldn't be satisfied]
```
- **{Library X}** - {One-line reason}
- **Hand-rolling {Y}** - {Existing solution available}
## Quality Checklist
### Defer Decision
- **{Topic}** - {Why more investigation needed}
## Sources
| 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
Before writing output, verify:
- [ ] Every feature from manifest has a library recommendation
- [ ] Every library is actively maintained
- [ ] Current versions specified (not "latest")
- [ ] Setup code is current syntax
- [ ] No low-confidence padding included
</subagent_prompt>
```
</ecosystem_subagent_prompt>
</stack_subagent_prompt>
<architecture_subagent_prompt>
## Architecture Research Subagent
<implementation_subagent_prompt>
## Implementation Research Subagent
Use this template for spawning architecture research subagents:
Use this template for spawning implementation research subagents:
```
<subagent_prompt>
## Objective
Research architecture patterns for {domain} projects and write findings to .planning/research/architecture.md
## Domain Context
{Paste relevant sections from PROJECT.md describing what's being built}
Research and document CURRENT implementation patterns for this project's stack.
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
File: .planning/research/architecture.md
Category: architecture
Purpose: Document standard project structure and architectural patterns
## Research Questions
Answer these questions through web research:
1. How do experts structure projects in this domain?
2. What component boundaries work best?
3. What patterns prevent common problems?
4. How does data flow in typical implementations?
5. What directory structure do production projects use?
For the stack chosen in stack.md (or infer from manifest):
1. What are the CURRENT API patterns?
2. What code does Claude need to generate correctly?
3. What deprecated patterns might Claude default to?
For Open Questions in the manifest:
1. Research and provide direct answers
2. If unanswerable, explain why
## Research Requirements
You MUST use WebSearch and Context7 to get current information.
Use WebSearch and Context7 for current documentation.
For EACH pattern discovered:
1. Find real-world examples (GitHub repos, case studies)
2. Understand the tradeoffs
3. Note when it applies vs when it doesn't
4. Find implementation guidelines
**INCLUDE:**
- Actual code examples with current syntax
- "Do this (current)" vs "Not this (deprecated)" comparisons
- Version-specific patterns (as of 2024-2025)
- Answers to Open Questions from manifest
**Search queries to run:**
- "{domain} project structure best practices"
- "{domain} architecture patterns"
- "{specific problem from PROJECT.md} implementation patterns"
- "{domain} component organization"
- "{domain} example github repo structure"
**EXCLUDE:**
- Theoretical explanations without code
- Multiple options without recommendation
- Old patterns from outdated tutorials
- Generic advice not specific to this project
## 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
**Domain:** {domain}
**Researched:** {today's date}
**Confidence:** {high | medium | low}
**Purpose:** Current API patterns for Claude Code to use
**Researched:** [date]
## Research Summary
## [Feature 1] Implementation
{2-3 sentences on recommended architectural approach}
### Current Pattern (2025)
## Findings
### Project Structure
Recommended directory layout:
```
{concrete directory structure with comments}
```[language]
// Correct way to do [thing]
[actual working code]
```
**Source:** {Reference project or documentation}
**Rationale:** {Why this structure works}
### NOT This (Deprecated)
### {Pattern 1 Name}
```[language]
// Claude may generate this - it's outdated
[old pattern to avoid]
// Why wrong: [brief explanation]
```
**When to use:** {Specific scenarios}
**Implementation:** {How to implement}
**Example:** {Concrete code example if applicable}
**Tradeoffs:** {What you give up}
### Key API Details
### {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}
- **{Structure B}** - {Why it fits this project}
## Decisions Validated
### Avoid
### [Decision 1 from manifest]
- **{Anti-pattern X}** - {Why it fails}
- **{Premature abstraction Y}** - {Why to defer}
**Validation:** ✓ Good choice / ⚠️ Gotcha
**Notes:** [Any implementation considerations]
## Sources
## Patterns Summary
| Source | Type | Confidence | Last Verified |
|--------|------|------------|---------------|
| {URL} | {official docs / github / tutorial} | {high/medium/low} | {today} |
| Task | Current Pattern | Deprecated Pattern |
|------|-----------------|-------------------|
| [task 1] | `doThisWay()` | `oldWay()` |
| [task 2] | `async/await` | `callbacks` |
```
## Open Questions
## Quality Checklist
- {Architecture decision that needs more context}
- {Question about project-specific constraints}
---
*Generated by research-project subagent*
*Category: architecture*
## 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
Before writing output, verify:
- [ ] Every code example is runnable (not pseudocode)
- [ ] Deprecated patterns explicitly flagged
- [ ] Open Questions from manifest answered
- [ ] Decisions from manifest validated
- [ ] No "it depends" - give clear recommendations
</subagent_prompt>
```
</architecture_subagent_prompt>
</implementation_subagent_prompt>
<pitfalls_subagent_prompt>
## Pitfalls Research Subagent
<risks_subagent_prompt>
## Risks Research Subagent
Use this template for spawning pitfalls research subagents:
Use this template for spawning risks research subagents:
```
<subagent_prompt>
## Objective
Research common mistakes and pitfalls in {domain} projects and write findings to .planning/research/pitfalls.md
## Domain Context
{Paste relevant sections from PROJECT.md describing what's being built}
Research what Claude Code might get WRONG when implementing this project.
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
File: .planning/research/pitfalls.md
Category: pitfalls
Purpose: Catalog what NOT to do and why
## Research Questions
Answer these questions through web research:
1. What mistakes do beginners commonly make in this domain?
2. What causes performance problems?
3. What architectural choices lead to regret?
4. What seems like a good idea but isn't?
5. What are the debugging nightmares people warn about?
For this project's domain and stack:
1. What deprecated patterns might Claude default to?
2. What common mistakes happen in this domain?
3. What version-specific gotchas exist?
For Decisions in the manifest:
1. Any known issues with these choices?
2. Pitfalls specific to this combination?
## 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:
1. Find real examples (Stack Overflow, GitHub issues, blog posts)
2. Understand the root cause
3. Find the correct approach
4. Note detection methods (how to know if you're doing this)
**INCLUDE:**
- Specific mistakes with code examples
- Version-specific deprecations
- Domain-specific pitfalls for this project
**Search queries to run:**
- "{domain} common mistakes"
- "{domain} things I wish I knew"
- "{domain} performance problems"
- "{domain} debugging nightmare"
- "{specific technology} gotchas"
- "{domain} anti-patterns"
**EXCLUDE:**
- Generic coding advice
- Low-probability edge cases
- "Best practices" (that's not risks)
- Risks that don't apply to this specific project
## 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
**Domain:** {domain}
**Researched:** {today's date}
**Confidence:** {high | medium | low}
**Purpose:** What Claude Code might get wrong
**Researched:** [date]
## 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 it happens:** {Root cause or common misconception}
**Consequence:** {What goes wrong}
**Detection:** {How to know if you're doing this}
**Prevention:** {Correct approach}
**Why:** [Deprecated in vX.Y, removed in vX.Z, etc.]
**Source:** {URL with real example}
**Severity:** {high | medium | low}
### [Deprecated Thing 2]
### {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}
2. **{Pitfall B}** - {One-line why it's critical}
// Right
[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 |
|--------|------|------------|---------------|
| {URL} | {stack overflow / github issue / blog} | {high/medium/low} | {today} |
## Decision Risks
## Open Questions
### [Decision 1 from manifest]
- {Potential pitfall that needs more context}
- {Question about project-specific risks}
**Risk level:** Low / Medium / High
**Specific concern:** [What could go wrong with this choice]
**Mitigation:** [How to avoid the problem]
---
*Generated by research-project subagent*
*Category: pitfalls*
## Critical Warnings
## Quality Criteria
- Include at least 5-7 pitfalls
- Categorize by severity
- Every pitfall has prevention/solution
- Include real examples with sources
- Focus on domain-specific issues (not generic coding advice)
1. **[Most important thing to not mess up]**
2. **[Second most important]**
3. **[Third most important]**
```
## 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>
```
</pitfalls_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>
</risks_subagent_prompt>
<task_tool_usage>
## Using the Task Tool
When spawning research subagents, use the Task tool with:
- `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.
Spawn all 3 subagents in a SINGLE message:
```
[Message 1: Batch 1]
Task: Research ecosystem for {domain}
Task: Research architecture for {domain}
[Wait for completion]
Task 1:
subagent_type: "general-purpose"
description: "Research stack for [project]"
prompt: [stack_subagent_prompt with manifest]
[Message 2: Batch 2]
Task: Research pitfalls for {domain}
Task: Research standards for {domain}
[Wait for completion]
Task 2:
subagent_type: "general-purpose"
description: "Research implementation for [project]"
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:**
- 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
Wait for all to complete, then verify outputs.
</task_tool_usage>
<quality_checklist>
## Subagent Quality Verification
<quality_verification>
## Post-Research Quality Check
After subagents complete, verify:
After subagents complete, verify each file:
- [ ] All 4 files exist in .planning/research/
- [ ] Each file has substantive content (not stub/error)
- [ ] Recommendations are specific (not "it depends")
- [ ] Sources are cited with confidence levels
- [ ] Information is current (2024-2025 sources preferred)
- [ ] Open questions are honest about gaps
</quality_checklist>
**stack.md:**
- [ ] Every manifest feature has a library
- [ ] Current versions specified
- [ ] Setup code included
- [ ] No low-confidence alternatives
**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>