diff --git a/commands/gsd/research-project.md b/commands/gsd/research-project.md
index 5d5bbfa1b..9fad26832 100644
--- a/commands/gsd/research-project.md
+++ b/commands/gsd/research-project.md
@@ -11,14 +11,15 @@ allowed-tools:
---
-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)
-- Architecture (patterns, project structure)
-- Pitfalls (common mistakes, what NOT to do)
-- Standards (best practices, conventions)
+Spawns 2-3 subagents in parallel to research PROJECT.md-specific needs:
+
+- **Stack** - What libraries/tools to use for THIS project's features
+- **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.
@@ -67,51 +68,97 @@ What would you like to do?
Wait for user decision.
-
-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.)
-- Problem domain (3D, games, real-time, etc.)
-- Technical constraints that suggest specific ecosystems
+**From Constraints:**
+- Tech stack requirements (language, framework, platform)
+- Performance requirements
+- Compatibility requirements
-If domain unclear, use AskUserQuestion:
+**From Open Questions:**
+- Questions that research should answer
+- These are explicit research targets
-- header: "Domain"
-- question: "What domain should we research?"
-- options:
- - "3D/Graphics" - Three.js, WebGL, shaders
- - "Games/Interactive" - Physics, collision, procedural
- - "Audio/Music" - Web Audio, synthesis, DSP
- - (other relevant options based on PROJECT.md)
-
+**From Decisions Made:**
+- Choices to validate ("any gotchas with X?")
+
+Create a research manifest:
+```
+Features to implement:
+- [feature 1]
+- [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
+
-Follow research-project.md workflow:
+Follow research-project.md workflow with PROJECT.md-driven research:
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
-4. Spawn second batch (pitfalls + standards)
-5. Wait for completion
-6. Verify all outputs exist
-
+4. Verify all outputs exist and are high-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.
+
-After all subagents complete:
+After verification:
```
Research complete:
-- .planning/research/ecosystem.md
-- .planning/research/architecture.md
-- .planning/research/pitfalls.md
-- .planning/research/standards.md
+- .planning/research/stack.md - [libraries/tools identified]
+- .planning/research/implementation.md - [patterns documented]
+- .planning/research/risks.md - [pitfalls to avoid]
-Key findings:
-- [Top ecosystem recommendation]
-- [Key architecture pattern]
-- [Critical pitfall to avoid]
+Key implementation context:
+- [Primary stack choice with rationale]
+- [Most important API pattern to use]
+- [Critical mistake Claude should avoid]
+
+Open questions remaining:
+- [Any questions research couldn't answer]
What's next?
1. Create roadmap (/gsd:create-roadmap) - Incorporates research
@@ -125,18 +172,16 @@ If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
-
-- [ ] PROJECT.md exists (prerequisite checked)
-- [ ] Domain detected or user clarified
-- [ ] Subagents spawned in batches of 3-4 max
-- [ ] All subagents wrote files directly to .planning/research/
-- [ ] All 4 research files exist
+- [ ] PROJECT.md parsed for specific research targets
+- [ ] Research addresses actual features from Scope
+- [ ] Open Questions from PROJECT.md answered (or noted as unanswerable)
+- [ ] All outputs are HIGH-CONFIDENCE only (no padding)
+- [ ] Code examples use current API syntax
- [ ] User knows next steps (create-roadmap)
-
+
diff --git a/get-shit-done/references/research-subagent-prompts.md b/get-shit-done/references/research-subagent-prompts.md
index f46b9c04c..91dffbcac 100644
--- a/get-shit-done/references/research-subagent-prompts.md
+++ b/get-shit-done/references/research-subagent-prompts.md
@@ -1,557 +1,451 @@
# Research Subagent Prompts
-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?
-
-## Ecosystem Research Subagent
+
+## Stack Research Subagent
-Use this template for spawning ecosystem research subagents:
+Use this template for spawning stack research subagents:
```
## 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
```
-
+
-
-## Architecture Research Subagent
+
+## Implementation Research Subagent
-Use this template for spawning architecture research subagents:
+Use this template for spawning implementation research subagents:
```
## 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
```
-
+
-
-## Pitfalls Research Subagent
+
+## Risks Research Subagent
-Use this template for spawning pitfalls research subagents:
+Use this template for spawning risks research subagents:
```
## 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
```
-
-
-
-## Standards Research Subagent
-
-Use this template for spawning standards research subagents:
-
-```
-
-## 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)
-
-```
-
+
## 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.
-
-## Subagent 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
-
+**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.
+
diff --git a/get-shit-done/templates/project-research.md b/get-shit-done/templates/project-research.md
index 7f8625692..266793e47 100644
--- a/get-shit-done/templates/project-research.md
+++ b/get-shit-done/templates/project-research.md
@@ -1,181 +1,243 @@
# 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
+
+## 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
+
+
+---
+
+## stack.md Template
```markdown
-# {Category}: {Domain}
+# Stack: [Project Name]
-**Category:** {ecosystem | architecture | pitfalls | standards}
-**Domain:** {domain from PROJECT.md}
-**Researched:** {date}
-**Confidence:** {high | medium | low}
+**Purpose:** Libraries and tools for Claude Code to use during implementation
+**Researched:** [date]
-## 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}
-**Confidence:** {high | medium | low}
-**Relevance:** {Why this matters for the project}
+## [Feature 2 from PROJECT.md Scope]
-### {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}
-**Confidence:** {high | medium | low}
-**Relevance:** {Why this matters for the project}
+**Docs:** [URL]
-{... 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}
-- **{Library/Pattern/Tool}** - {One line why}
+## Unanswered
-### Avoid
-
-- **{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}*
+- [Any features where no clear library choice exists - be honest]
```
---
-
+## 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:**
-- 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)?
+### Current Pattern (2025)
-**Structure emphasis:**
-- Compare 2-4 main options
-- Clear "use X when..." guidance
-- Version currency (is it maintained?)
-- Integration considerations
+```[language]
+// Correct way to implement [feature]
+[actual working code - not pseudocode]
+```
-### 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:**
-- 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?
+### Key APIs
-**Structure emphasis:**
-- Directory structure recommendations
-- Component organization patterns
-- State management approaches
-- Integration patterns with related systems
+- `methodName(params)` - [what it does, when to use]
+- `otherMethod(params)` - [what it does, when to use]
-### pitfalls.md
+## [Feature 2] Implementation
-**Purpose:** Catalog what NOT to do and why
+[Same structure]
-**Key questions to answer:**
-- What mistakes do beginners commonly make?
-- What causes performance problems?
-- What architectural choices cause regret?
-- What seems like a good idea but isn't?
+## Open Questions Answered
-**Structure emphasis:**
-- Clear problem → consequence → solution
-- Real examples of failures
-- Detection (how to know if you're doing this)
-- Prevention (how to avoid)
+### [Question from PROJECT.md Open Questions]
-### standards.md
+**Answer:** [Direct answer]
+**Source:** [URL or documentation reference]
-**Purpose:** Document best practices and quality expectations
+### [Question 2]
-**Key questions to answer:**
-- What does "production quality" mean for this domain?
-- What testing approaches work?
-- What performance benchmarks matter?
-- What accessibility/security considerations apply?
+**Answer:** [Direct answer or "Could not determine - [reason]"]
-**Structure emphasis:**
-- Measurable quality criteria
-- Testing strategies that work
-- Performance targets
-- Common standards/conventions
+## Decisions Validated
-
+### [Decision from PROJECT.md Decisions Made]
-
-## How This Differs from Phase-Level Research
+**Validation:** ✓ Good choice / ⚠️ Has gotchas
+**Notes:** [Implementation considerations Claude should know]
-**project-research.md (this template):**
-- Written BEFORE roadmap exists
-- Informs phase structure and scope
-- Ecosystem-level landscape view
-- Answers "what tools/patterns should we use?"
+## Quick Reference
-**research.md (phase-level):**
-- Written AFTER roadmap exists
-- Informs specific phase implementation
-- Implementation-level detail
-- Answers "how do we implement this phase?"
+| Task | Current Pattern | Deprecated Pattern |
+|------|-----------------|-------------------|
+| [common task 1] | `newWay()` | `oldWay()` |
+| [common task 2] | `async/await` | `.then()` chains |
+```
-Project research is strategic (shapes the roadmap).
-Phase research is tactical (shapes the implementation).
-
+---
-
-## Quality Expectations
+## risks.md Template
-A well-written research file:
-- Has specific, actionable recommendations (not "it depends")
-- Cites sources with confidence levels
-- Distinguishes verified facts from educated guesses
-- Surfaces open questions honestly
-- Can be read in 2-3 minutes and inform a decision
+```markdown
+# Risks: [Project Name]
+
+**Purpose:** What Claude Code might get wrong
+**Researched:** [date]
+
+## 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
+
+### 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.
+
-**Avoid:**
-- Generic advice that applies to anything
-- Recommendations without reasoning
-- Outdated information (pre-2024 unless fundamental)
-- Confidence without verification
-
diff --git a/get-shit-done/workflows/research-project.md b/get-shit-done/workflows/research-project.md
index 4e8401c8f..aaff5c79d 100644
--- a/get-shit-done/workflows/research-project.md
+++ b/get-shit-done/workflows/research-project.md
@@ -1,14 +1,42 @@
-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.
-Maximum 4 parallel subagents, recommended batch size 3.
+This is NOT research for human decision-making.
+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.
+
+## 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
+
+
**Read before executing:**
-1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates for each category
-2. `~/.claude/get-shit-done/templates/project-research.md` - Output format subagents use
+1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates
+2. `~/.claude/get-shit-done/templates/project-research.md` - Output format
@@ -20,172 +48,176 @@ Create research directory:
mkdir -p .planning/research
```
-Parse PROJECT.md to extract:
-- Domain keywords (technology mentions, problem space)
-- Constraints that affect ecosystem choices
-- Any mentioned preferences or requirements
+Parse PROJECT.md to create research manifest:
+
+```
+## 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.
-Standard research categories:
+Three research categories, each PROJECT.md-driven:
-1. **ecosystem.md** - Libraries, frameworks, tools for this domain
-2. **architecture.md** - Patterns, project structure, component organization
-3. **pitfalls.md** - Common mistakes, what NOT to do, performance traps
-4. **standards.md** - Best practices, conventions, quality expectations
+1. **stack.md** - What to use for each feature
+ - For each feature in Scope: what library/tool?
+ - For each constraint: what works within it?
+ - 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`
-
-## Batched Subagent Spawning
+
+## Subagent Spawning
Read prompt templates from `~/.claude/get-shit-done/references/research-subagent-prompts.md`
-**Batch 1: Foundation research** (spawn in parallel)
-
-Spawn using Task tool with `subagent_type="general-purpose"`:
+**Single batch (spawn all 3 in parallel):**
```
Task 1:
- description: "Research ecosystem for {domain}"
- prompt: [ecosystem_subagent_prompt template filled with PROJECT.md context]
+ description: "Research stack for [project]"
+ prompt: [stack_subagent_prompt with research manifest]
Task 2:
- description: "Research architecture for {domain}"
- prompt: [architecture_subagent_prompt template filled with PROJECT.md context]
-```
+ description: "Research implementation for [project]"
+ 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:
- description: "Research pitfalls for {domain}"
- prompt: [pitfalls_subagent_prompt template filled with PROJECT.md context]
-
-Task 4:
- description: "Research standards for {domain}"
- prompt: [standards_subagent_prompt template filled with PROJECT.md context]
+ description: "Research risks for [project]"
+ prompt: [risks_subagent_prompt with research manifest]
```
-Send BOTH Task calls in a single message. Wait for Batch 2 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
+Send ALL Task calls in a single message. Wait for completion.
**Each subagent receives:**
-- Domain context from PROJECT.md
-- Category assignment (ecosystem, architecture, pitfalls, standards)
+- The research manifest (features, constraints, questions, decisions)
+- Category assignment (stack, implementation, risks)
- Output format from templates/project-research.md
-- Instruction to write directly to `.planning/research/{category}.md`
+- Instruction: HIGH-CONFIDENCE ONLY
-After all batches complete:
+After subagents complete:
```bash
# Check all files exist
ls -la .planning/research/
# 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"
done
```
-**If any file missing:**
-- Log which subagent failed
-- Optionally retry that specific subagent
-- Continue with available research (partial is better than none)
+**Quality verification (read each file):**
+
+For each file, check:
+- [ ] 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
-Read key findings from each research file for summary:
+Extract key findings for summary:
-```bash
-# Extract first few lines of each for summary
-for f in .planning/research/*.md; do
- echo "=== $(basename $f) ==="
- head -20 "$f"
- echo ""
-done
-```
+From stack.md:
+- Primary libraries chosen for each feature
+- Any constraint-driven choices
-Extract for user summary:
-- Top library/framework recommendation from ecosystem.md
-- Primary architecture pattern from architecture.md
-- Most critical pitfall from pitfalls.md
-- Key quality standard from standards.md
+From implementation.md:
+- Most important API patterns
+- Key code examples
+
+From risks.md:
+- Critical mistakes to avoid
+- Deprecated patterns flagged
+
+Present summary to user with next steps.
-
-## Batching Configuration
+
+## Quality Rules for Subagents
-**Maximum parallel subagents:** 4 (API safety limit)
-**Recommended batch size:** 3 (reliable)
+**INCLUDE:**
+- 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:**
-- Batch 1 (ecosystem + architecture): Foundation knowledge that informs everything
-- Batch 2 (pitfalls + standards): Risk and quality that build on foundation
+**EXCLUDE:**
+- Low or medium confidence items
+- "Might be useful" padding
+- Generic advice not specific to this project
+- Old repos/articles marked as outdated
+- Options without clear recommendation
-**Between batches:**
-- Verify all subagents in batch completed
-- Check for failures, note for retry if needed
-- Proceed to next batch
-
+**Format for Claude consumption:**
+```markdown
+## [Feature Name] Implementation
-
-## Task Tool Invocation Pattern
+**Use:** [Library] v[X.Y]
-For each subagent, use:
-
-```
-Task tool parameters:
-- subagent_type: "general-purpose"
-- description: "Research {category} for {domain}"
-- prompt: [filled template from research-subagent-prompts.md]
+```[language]
+// Current pattern (2025)
+import { Thing } from 'library'
+const result = await Thing.doCorrectThing()
```
-**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.
```
-
+
Research workflow complete when:
-- [ ] All 4 research files exist in .planning/research/
-- [ ] Each file has substantive content (not empty/error)
-- [ ] Key findings extracted for summary
-- [ ] Main agent context preserved (minimal usage)
+- [ ] All 3 research files exist in .planning/research/
+- [ ] Each file addresses PROJECT.md features specifically
+- [ ] Open Questions from PROJECT.md are answered
+- [ ] Only high-confidence information included
+- [ ] Code examples use current syntax
+- [ ] Main agent context preserved