msd-core/get-shit-done/templates/project-research.md

Project Research Template

Template for .planning/research/{category}.md - project-level domain research written by subagents.

---

File Template

# {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>