- Created /gsd:research-project slash command for pre-roadmap domain research - Built batched subagent workflow (3-4 max parallel, 2 batches) - Defined project-research template for ecosystem/architecture/pitfalls/standards 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
182 lines
4.4 KiB
Markdown
182 lines
4.4 KiB
Markdown
# Project Research Template
|
|
|
|
Template for `.planning/research/{category}.md` - project-level domain research written by subagents.
|
|
|
|
---
|
|
|
|
## File Template
|
|
|
|
```markdown
|
|
# {Category}: {Domain}
|
|
|
|
**Category:** {ecosystem | architecture | pitfalls | standards}
|
|
**Domain:** {domain from PROJECT.md}
|
|
**Researched:** {date}
|
|
**Confidence:** {high | medium | low}
|
|
|
|
## Research Summary
|
|
|
|
{2-3 sentence overview of what was found and why it matters for this project}
|
|
|
|
## Findings
|
|
|
|
### {Finding 1 Title}
|
|
|
|
{What was discovered}
|
|
|
|
**Source:** {URL or documentation reference}
|
|
**Confidence:** {high | medium | low}
|
|
**Relevance:** {Why this matters for the project}
|
|
|
|
### {Finding 2 Title}
|
|
|
|
{What was discovered}
|
|
|
|
**Source:** {URL or documentation reference}
|
|
**Confidence:** {high | medium | low}
|
|
**Relevance:** {Why this matters for the project}
|
|
|
|
{... additional findings ...}
|
|
|
|
## Recommendations
|
|
|
|
### Use
|
|
|
|
- **{Library/Pattern/Tool}** - {One line why}
|
|
- **{Library/Pattern/Tool}** - {One line why}
|
|
|
|
### 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}*
|
|
```
|
|
|
|
---
|
|
|
|
<category_guides>
|
|
|
|
## Category-Specific Guidance
|
|
|
|
### ecosystem.md
|
|
|
|
**Purpose:** Map the library/framework landscape for this domain
|
|
|
|
**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)?
|
|
|
|
**Structure emphasis:**
|
|
- Compare 2-4 main options
|
|
- Clear "use X when..." guidance
|
|
- Version currency (is it maintained?)
|
|
- Integration considerations
|
|
|
|
### architecture.md
|
|
|
|
**Purpose:** Document standard project structure and patterns
|
|
|
|
**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?
|
|
|
|
**Structure emphasis:**
|
|
- Directory structure recommendations
|
|
- Component organization patterns
|
|
- State management approaches
|
|
- Integration patterns with related systems
|
|
|
|
### pitfalls.md
|
|
|
|
**Purpose:** Catalog what NOT to do and why
|
|
|
|
**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?
|
|
|
|
**Structure emphasis:**
|
|
- Clear problem → consequence → solution
|
|
- Real examples of failures
|
|
- Detection (how to know if you're doing this)
|
|
- Prevention (how to avoid)
|
|
|
|
### standards.md
|
|
|
|
**Purpose:** Document best practices and quality expectations
|
|
|
|
**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?
|
|
|
|
**Structure emphasis:**
|
|
- Measurable quality criteria
|
|
- Testing strategies that work
|
|
- Performance targets
|
|
- Common standards/conventions
|
|
|
|
</category_guides>
|
|
|
|
<difference_from_phase_research>
|
|
## How This Differs from Phase-Level Research
|
|
|
|
**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?"
|
|
|
|
**research.md (phase-level):**
|
|
- Written AFTER roadmap exists
|
|
- Informs specific phase implementation
|
|
- Implementation-level detail
|
|
- Answers "how do we implement this phase?"
|
|
|
|
Project research is strategic (shapes the roadmap).
|
|
Phase research is tactical (shapes the implementation).
|
|
</difference_from_phase_research>
|
|
|
|
<quality_bar>
|
|
## Quality Expectations
|
|
|
|
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
|
|
|
|
**Avoid:**
|
|
- Generic advice that applies to anything
|
|
- Recommendations without reasoning
|
|
- Outdated information (pre-2024 unless fundamental)
|
|
- Confidence without verification
|
|
</quality_bar>
|