refactor: remove research-project command
Pre-roadmap research was over-engineered theater: - 3 parallel subagents producing fragmented output - Files with unclear consumption points - Duplicated what research-phase does better (just-in-time) Deleted: - commands/gsd/research-project.md - get-shit-done/workflows/research-project.md - get-shit-done/templates/project-research.md - get-shit-done/references/research-subagent-prompts.md Phase-level research (/gsd:research-phase) remains for niche domains. 🤖 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
@@ -1,451 +0,0 @@
|
||||
# Research Subagent Prompts
|
||||
|
||||
<overview>
|
||||
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:
|
||||
- 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`
|
||||
- Formats output for Claude Code to consume during implementation
|
||||
|
||||
**Quality bar:** Will this context make Claude Code generate correct, modern code?
|
||||
</overview>
|
||||
|
||||
<stack_subagent_prompt>
|
||||
## Stack Research Subagent
|
||||
|
||||
Use this template for spawning stack research subagents:
|
||||
|
||||
```
|
||||
<subagent_prompt>
|
||||
## Objective
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
Use WebSearch to verify CURRENT information (2024-2025).
|
||||
|
||||
**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
|
||||
|
||||
**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/stack.md:
|
||||
|
||||
```markdown
|
||||
# Stack: [Project Name]
|
||||
|
||||
**Purpose:** Libraries and tools for Claude Code to use during implementation
|
||||
**Researched:** [date]
|
||||
|
||||
## [Feature 1 from Scope]
|
||||
|
||||
**Use:** [Library Name] v[X.Y.Z]
|
||||
**Why:** [One sentence - why this for this feature]
|
||||
|
||||
```[language]
|
||||
// Setup / import
|
||||
[actual code]
|
||||
```
|
||||
|
||||
**Docs:** [URL to current documentation]
|
||||
|
||||
## [Feature 2 from Scope]
|
||||
|
||||
**Use:** [Library Name] v[X.Y.Z]
|
||||
**Why:** [One sentence]
|
||||
|
||||
```[language]
|
||||
// Setup / import
|
||||
[actual code]
|
||||
```
|
||||
|
||||
**Docs:** [URL]
|
||||
|
||||
## [Continue for each feature...]
|
||||
|
||||
## Constraint Compatibility
|
||||
|
||||
| Constraint | Status | Notes |
|
||||
|------------|--------|-------|
|
||||
| [constraint 1] | ✓ Compatible | [brief note] |
|
||||
| [constraint 2] | ✓ Compatible | [brief note] |
|
||||
|
||||
## Unanswered
|
||||
|
||||
- [Any features where no clear library choice exists]
|
||||
- [Any constraints that couldn't be satisfied]
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
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>
|
||||
```
|
||||
</stack_subagent_prompt>
|
||||
|
||||
<implementation_subagent_prompt>
|
||||
## Implementation Research Subagent
|
||||
|
||||
Use this template for spawning implementation research subagents:
|
||||
|
||||
```
|
||||
<subagent_prompt>
|
||||
## Objective
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
Use WebSearch and Context7 for current documentation.
|
||||
|
||||
**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
|
||||
|
||||
**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/implementation.md:
|
||||
|
||||
```markdown
|
||||
# Implementation: [Project Name]
|
||||
|
||||
**Purpose:** Current API patterns for Claude Code to use
|
||||
**Researched:** [date]
|
||||
|
||||
## [Feature 1] Implementation
|
||||
|
||||
### Current Pattern (2025)
|
||||
|
||||
```[language]
|
||||
// Correct way to do [thing]
|
||||
[actual working code]
|
||||
```
|
||||
|
||||
### NOT This (Deprecated)
|
||||
|
||||
```[language]
|
||||
// Claude may generate this - it's outdated
|
||||
[old pattern to avoid]
|
||||
// Why wrong: [brief explanation]
|
||||
```
|
||||
|
||||
### Key API Details
|
||||
|
||||
- `methodName()` - [what it does, when to use]
|
||||
- `otherMethod()` - [what it does, when to use]
|
||||
|
||||
## [Feature 2] Implementation
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Open Questions Answered
|
||||
|
||||
### [Question 1 from manifest]
|
||||
|
||||
**Answer:** [Direct answer with source]
|
||||
|
||||
### [Question 2 from manifest]
|
||||
|
||||
**Answer:** [Direct answer with source]
|
||||
|
||||
## Decisions Validated
|
||||
|
||||
### [Decision 1 from manifest]
|
||||
|
||||
**Validation:** ✓ Good choice / ⚠️ Gotcha
|
||||
**Notes:** [Any implementation considerations]
|
||||
|
||||
## Patterns Summary
|
||||
|
||||
| Task | Current Pattern | Deprecated Pattern |
|
||||
|------|-----------------|-------------------|
|
||||
| [task 1] | `doThisWay()` | `oldWay()` |
|
||||
| [task 2] | `async/await` | `callbacks` |
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
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>
|
||||
```
|
||||
</implementation_subagent_prompt>
|
||||
|
||||
<risks_subagent_prompt>
|
||||
## Risks Research Subagent
|
||||
|
||||
Use this template for spawning risks research subagents:
|
||||
|
||||
```
|
||||
<subagent_prompt>
|
||||
## Objective
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
**INCLUDE:**
|
||||
- Specific mistakes with code examples
|
||||
- Version-specific deprecations
|
||||
- Domain-specific pitfalls for this project
|
||||
|
||||
**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/risks.md:
|
||||
|
||||
```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
|
||||
[deprecated code pattern]
|
||||
```
|
||||
|
||||
**Instead use:**
|
||||
```[language]
|
||||
// Current approach
|
||||
[correct code pattern]
|
||||
```
|
||||
|
||||
**Why:** [Deprecated in vX.Y, removed in vX.Z, etc.]
|
||||
|
||||
### [Deprecated Thing 2]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### [Mistake 1: Descriptive Name]
|
||||
|
||||
**What happens:** [The incorrect approach]
|
||||
**Why it's wrong:** [Consequence]
|
||||
**Correct approach:** [What to do instead]
|
||||
|
||||
```[language]
|
||||
// Wrong
|
||||
[bad code]
|
||||
|
||||
// Right
|
||||
[good code]
|
||||
```
|
||||
|
||||
### [Mistake 2]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Stack-Specific Gotchas
|
||||
|
||||
### [Gotcha for chosen library/framework]
|
||||
|
||||
**Issue:** [What goes wrong]
|
||||
**When:** [Trigger conditions]
|
||||
**Fix:** [How to avoid/handle]
|
||||
|
||||
## Decision Risks
|
||||
|
||||
### [Decision 1 from manifest]
|
||||
|
||||
**Risk level:** Low / Medium / High
|
||||
**Specific concern:** [What could go wrong with this choice]
|
||||
**Mitigation:** [How to avoid the problem]
|
||||
|
||||
## Critical Warnings
|
||||
|
||||
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>
|
||||
```
|
||||
</risks_subagent_prompt>
|
||||
|
||||
<task_tool_usage>
|
||||
## Using the Task Tool
|
||||
|
||||
Spawn all 3 subagents in a SINGLE message:
|
||||
|
||||
```
|
||||
Task 1:
|
||||
subagent_type: "general-purpose"
|
||||
description: "Research stack for [project]"
|
||||
prompt: [stack_subagent_prompt with manifest]
|
||||
|
||||
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]
|
||||
```
|
||||
|
||||
Wait for all to complete, then verify outputs.
|
||||
</task_tool_usage>
|
||||
|
||||
<quality_verification>
|
||||
## Post-Research Quality Check
|
||||
|
||||
After subagents complete, verify each file:
|
||||
|
||||
**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>
|
||||
@@ -1,243 +0,0 @@
|
||||
# Project Research Template
|
||||
|
||||
Template for `.planning/research/{category}.md` - implementation context for Claude Code.
|
||||
|
||||
---
|
||||
|
||||
<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
|
||||
# Stack: [Project Name]
|
||||
|
||||
**Purpose:** Libraries and tools for Claude Code to use during implementation
|
||||
**Researched:** [date]
|
||||
|
||||
## [Feature 1 from PROJECT.md Scope]
|
||||
|
||||
**Use:** [Library Name] v[X.Y.Z]
|
||||
**Why:** [One sentence - why this library for this feature]
|
||||
|
||||
```[language]
|
||||
// Setup / import
|
||||
import { Thing } from 'library'
|
||||
|
||||
// Basic usage
|
||||
const result = Thing.doThing()
|
||||
```
|
||||
|
||||
**Docs:** [URL to current documentation]
|
||||
|
||||
## [Feature 2 from PROJECT.md Scope]
|
||||
|
||||
**Use:** [Library Name] v[X.Y.Z]
|
||||
**Why:** [One sentence]
|
||||
|
||||
```[language]
|
||||
// Setup / import
|
||||
[actual code]
|
||||
```
|
||||
|
||||
**Docs:** [URL]
|
||||
|
||||
## [Continue for each feature in Scope...]
|
||||
|
||||
## Constraint Compatibility
|
||||
|
||||
| Constraint | Status | Notes |
|
||||
|------------|--------|-------|
|
||||
| [constraint from PROJECT.md] | ✓ Compatible | [brief note] |
|
||||
| [constraint from PROJECT.md] | ✓ Compatible | [brief note] |
|
||||
|
||||
## Unanswered
|
||||
|
||||
- [Any features where no clear library choice exists - be honest]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## implementation.md Template
|
||||
|
||||
```markdown
|
||||
# Implementation: [Project Name]
|
||||
|
||||
**Purpose:** Current API patterns for Claude Code to use
|
||||
**Researched:** [date]
|
||||
|
||||
## [Feature 1] Implementation
|
||||
|
||||
### Current Pattern (2025)
|
||||
|
||||
```[language]
|
||||
// Correct way to implement [feature]
|
||||
[actual working code - not pseudocode]
|
||||
```
|
||||
|
||||
### NOT This (Deprecated)
|
||||
|
||||
```[language]
|
||||
// Claude may generate this - it's outdated
|
||||
[old pattern]
|
||||
// Why wrong: [deprecated in vX, removed in vY, causes Z problem]
|
||||
```
|
||||
|
||||
### Key APIs
|
||||
|
||||
- `methodName(params)` - [what it does, when to use]
|
||||
- `otherMethod(params)` - [what it does, when to use]
|
||||
|
||||
## [Feature 2] Implementation
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Open Questions Answered
|
||||
|
||||
### [Question from PROJECT.md Open Questions]
|
||||
|
||||
**Answer:** [Direct answer]
|
||||
**Source:** [URL or documentation reference]
|
||||
|
||||
### [Question 2]
|
||||
|
||||
**Answer:** [Direct answer or "Could not determine - [reason]"]
|
||||
|
||||
## Decisions Validated
|
||||
|
||||
### [Decision from PROJECT.md Decisions Made]
|
||||
|
||||
**Validation:** ✓ Good choice / ⚠️ Has gotchas
|
||||
**Notes:** [Implementation considerations Claude should know]
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Current Pattern | Deprecated Pattern |
|
||||
|------|-----------------|-------------------|
|
||||
| [common task 1] | `newWay()` | `oldWay()` |
|
||||
| [common task 2] | `async/await` | `.then()` chains |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## risks.md Template
|
||||
|
||||
```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>
|
||||
## 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>
|
||||
|
||||
@@ -27,67 +27,6 @@ If proceeding without brief, gather quick context:
|
||||
- What's the rough scope?
|
||||
</step>
|
||||
|
||||
<step name="check_research">
|
||||
Check for project research from /gsd:research-project:
|
||||
|
||||
```bash
|
||||
ls .planning/research/*.md 2>/dev/null
|
||||
```
|
||||
|
||||
**If research files found:**
|
||||
|
||||
Load and extract key findings from each file:
|
||||
|
||||
1. **ecosystem.md** → Standard stack recommendations
|
||||
- Which libraries/frameworks to use
|
||||
- Why they're recommended for this domain
|
||||
|
||||
2. **architecture.md** → Architectural patterns
|
||||
- Recommended project structure
|
||||
- Key patterns to follow
|
||||
|
||||
3. **pitfalls.md** → Critical pitfalls
|
||||
- Top 2-3 things that commonly go wrong
|
||||
- How to avoid them
|
||||
|
||||
4. **standards.md** → Domain standards
|
||||
- Conventions and best practices
|
||||
- Compliance requirements (if any)
|
||||
|
||||
Present summary to user:
|
||||
```
|
||||
Found project research:
|
||||
|
||||
**Ecosystem:**
|
||||
[Key libraries/frameworks from ecosystem.md]
|
||||
|
||||
**Architecture:**
|
||||
[Key patterns from architecture.md]
|
||||
|
||||
**Pitfalls to Avoid:**
|
||||
[Top 2-3 from pitfalls.md]
|
||||
|
||||
**Standards:**
|
||||
[Key conventions from standards.md]
|
||||
|
||||
This research will inform phase structure and planning.
|
||||
Continue with roadmap creation? (yes / review research first)
|
||||
```
|
||||
|
||||
If user wants to review research, show relevant files.
|
||||
|
||||
**If no research found:**
|
||||
```
|
||||
No project research found.
|
||||
Creating roadmap based on PROJECT.md.
|
||||
|
||||
(For niche/complex domains, consider running /gsd:research-project first)
|
||||
```
|
||||
|
||||
Continue with roadmap creation.
|
||||
|
||||
**Store research context** for use in identify_phases and write_roadmap steps.
|
||||
</step>
|
||||
|
||||
<step name="detect_domain">
|
||||
Scan for available domain expertise:
|
||||
@@ -144,26 +83,6 @@ Select (comma-separate for multiple):
|
||||
<step name="identify_phases">
|
||||
Derive phases from the actual work needed. The phase count emerges from the project—don't impose a number.
|
||||
|
||||
**Incorporate research if available:**
|
||||
|
||||
If research was found in check_research step, use findings to inform phase structure:
|
||||
|
||||
- **ecosystem.md recommendations** → Inform technology choices in phases
|
||||
- If research recommends specific libraries, plan phases that set them up properly
|
||||
- Add foundation phases for recommended architectural patterns
|
||||
|
||||
- **architecture.md patterns** → Inform phase ordering
|
||||
- If research identifies layered architecture, order phases accordingly
|
||||
- Include phases for recommended project structure setup
|
||||
|
||||
- **pitfalls.md warnings** → Add phases to address risks
|
||||
- If research identifies common failure modes, add phases that mitigate them
|
||||
- Consider early validation phases for risky integrations
|
||||
|
||||
- **standards.md conventions** → Inform phase content
|
||||
- Ensure phases follow domain conventions
|
||||
- Add phases for compliance requirements if applicable
|
||||
|
||||
**Phase Numbering System:**
|
||||
|
||||
Use integer phases (1, 2, 3) for planned milestone work.
|
||||
@@ -348,7 +267,6 @@ Decimal phases added later via /gsd:insert-phase command (if it exists).
|
||||
Write to `.planning/ROADMAP.md` with:
|
||||
|
||||
- Domain Expertise section (paths from detect_domain step, or "None" if skipped)
|
||||
- **Research Context section** (if research found in check_research step)
|
||||
- Phase list with names and one-line descriptions
|
||||
- Dependencies (what must complete before what)
|
||||
- **Research flags** (from detect_research_needs step):
|
||||
@@ -356,29 +274,6 @@ Write to `.planning/ROADMAP.md` with:
|
||||
- `Research: Unlikely ([reason])` for unflagged phases
|
||||
- Status tracking (all start as "not started")
|
||||
|
||||
**Research Context section format (if research exists):**
|
||||
|
||||
```markdown
|
||||
## Research Context
|
||||
|
||||
Pre-planning research was conducted for this domain. Key findings incorporated into phase planning:
|
||||
|
||||
**Source:** .planning/research/
|
||||
|
||||
**Key Ecosystem Choices:**
|
||||
- [Library/framework from ecosystem.md and why]
|
||||
|
||||
**Architectural Patterns:**
|
||||
- [Pattern from architecture.md]
|
||||
|
||||
**Critical Pitfalls Addressed:**
|
||||
- [Pitfall from pitfalls.md and which phase addresses it]
|
||||
|
||||
See .planning/research/*.md for full research findings.
|
||||
```
|
||||
|
||||
**If no research:** Omit the Research Context section entirely.
|
||||
|
||||
Create phase directories:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -1,223 +0,0 @@
|
||||
<purpose>
|
||||
Research implementation context for Claude Code before roadmap creation.
|
||||
|
||||
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.
|
||||
</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>
|
||||
**Read before executing:**
|
||||
1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates
|
||||
2. `~/.claude/get-shit-done/templates/project-research.md` - Output format
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="setup">
|
||||
Create research directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="define_research_categories">
|
||||
Three research categories, each PROJECT.md-driven:
|
||||
|
||||
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
|
||||
|
||||
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 name="spawn_subagents">
|
||||
## Subagent Spawning
|
||||
|
||||
Read prompt templates from `~/.claude/get-shit-done/references/research-subagent-prompts.md`
|
||||
|
||||
**Single batch (spawn all 3 in parallel):**
|
||||
|
||||
```
|
||||
Task 1:
|
||||
description: "Research stack for [project]"
|
||||
prompt: [stack_subagent_prompt with research manifest]
|
||||
|
||||
Task 2:
|
||||
description: "Research implementation for [project]"
|
||||
prompt: [implementation_subagent_prompt with research manifest]
|
||||
|
||||
Task 3:
|
||||
description: "Research risks for [project]"
|
||||
prompt: [risks_subagent_prompt with research manifest]
|
||||
```
|
||||
|
||||
Send ALL Task calls in a single message. Wait for completion.
|
||||
|
||||
**Each subagent receives:**
|
||||
- The research manifest (features, constraints, questions, decisions)
|
||||
- Category assignment (stack, implementation, risks)
|
||||
- Output format from templates/project-research.md
|
||||
- Instruction: HIGH-CONFIDENCE ONLY
|
||||
</step>
|
||||
|
||||
<step name="verify_outputs">
|
||||
After subagents complete:
|
||||
|
||||
```bash
|
||||
# Check all files exist
|
||||
ls -la .planning/research/
|
||||
|
||||
# Verify each file has content
|
||||
for f in stack implementation risks; do
|
||||
[ -s ".planning/research/${f}.md" ] && echo "✓ ${f}.md" || echo "✗ ${f}.md MISSING"
|
||||
done
|
||||
```
|
||||
|
||||
**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
|
||||
</step>
|
||||
|
||||
<step name="aggregate">
|
||||
Extract key findings for summary:
|
||||
|
||||
From stack.md:
|
||||
- Primary libraries chosen for each feature
|
||||
- Any constraint-driven choices
|
||||
|
||||
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.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<subagent_quality_rules>
|
||||
## Quality Rules for Subagents
|
||||
|
||||
**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
|
||||
|
||||
**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
|
||||
|
||||
**Format for Claude consumption:**
|
||||
```markdown
|
||||
## [Feature Name] Implementation
|
||||
|
||||
**Use:** [Library] v[X.Y]
|
||||
|
||||
```[language]
|
||||
// Current pattern (2025)
|
||||
import { Thing } from 'library'
|
||||
const result = await Thing.doCorrectThing()
|
||||
```
|
||||
|
||||
**NOT:**
|
||||
```[language]
|
||||
// Deprecated - Claude may generate this
|
||||
import Thing from 'library' // Old syntax
|
||||
Thing.doOldThing() // Removed in v2.0
|
||||
```
|
||||
```
|
||||
</subagent_quality_rules>
|
||||
|
||||
<success_criteria>
|
||||
Research workflow complete when:
|
||||
- [ ] 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
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user