msd-core/commands/gsd/research-project.md

name, description, allowed-tools

name	description	allowed-tools
gsd:research-project	Research domain ecosystem before creating roadmap	Read Write Bash Task AskUserQuestion

Research domain ecosystem. Spawns 4 parallel gsd-project-researcher agents for comprehensive coverage.

Orchestrator role: Analyze project, generate research questions, spawn 4 parallel agents, synthesize SUMMARY.md.

Why subagents: Research burns context fast. Fresh 200k context per domain. Main context stays lean.

Note: For new projects, /gsd:new-project includes research as an optional step. Use this command to re-research or add research later.

@.planning/PROJECT.md @.planning/config.json (if exists)

1. Validate Prerequisites

[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md exists. Research is typically done before roadmap."
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"

2. Handle Existing Research

If RESEARCH_EXISTS: Use AskUserQuestion (View existing / Replace / Cancel)

3. Analyze Project

Read PROJECT.md, extract domain/stack/core value/constraints. Present for approval:

Domain analysis:
- Type: [domain]
- Stack: [stated or TBD]
- Core: [core value]
Does this look right? (yes / adjust)

4. Generate Research Questions

Dimension	Question
Stack	"What's the standard 2025 stack for [domain]?"
Features	"What features do [domain] products have?"
Architecture	"How are [domain] systems structured?"
Pitfalls	"What do [domain] projects get wrong?"

Present for approval.

5. Spawn Research Agents

mkdir -p .planning/research

Determine milestone context:

• If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
• If "Validated" requirements exist → Subsequent milestone (v1.1+)

Spawn all 4 in parallel with rich context:

Task(prompt="
<research_type>
Project Research — Stack dimension for [domain].
</research_type>

<milestone_context>
{greenfield OR subsequent}

Greenfield: Research the standard stack for building [domain] from scratch.
Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
</milestone_context>

<question>
[stack question from step 4]
</question>

<project_context>
[PROJECT.md summary]
</project_context>

<downstream_consumer>
Your STACK.md feeds into /gsd:create-roadmap. Be prescriptive:
- Specific libraries with versions
- Clear rationale for each choice
- What NOT to use and why
</downstream_consumer>

<quality_gate>
- [ ] Versions are current (not Claude's training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Confidence levels assigned
</quality_gate>

<output>
Write to: .planning/research/STACK.md
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
</output>
", subagent_type="gsd-project-researcher", description="Stack research")

Task(prompt="
<research_type>
Project Research — Features dimension for [domain].
</research_type>

<milestone_context>
{greenfield OR subsequent}

Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
Subsequent: How do [target features] typically work? What's expected behavior?
</milestone_context>

<question>
[features question from step 4]
</question>

<project_context>
[PROJECT.md summary]
</project_context>

<downstream_consumer>
Your FEATURES.md feeds into /gsd:define-requirements. Categorize clearly:
- Table stakes (must have or users leave)
- Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build)
</downstream_consumer>

<quality_gate>
- [ ] Categories are clear
- [ ] Complexity noted for each
- [ ] Dependencies between features identified
</quality_gate>

<output>
Write to: .planning/research/FEATURES.md
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
</output>
", subagent_type="gsd-project-researcher", description="Features research")

Task(prompt="
<research_type>
Project Research — Architecture dimension for [domain].
</research_type>

<milestone_context>
{greenfield OR subsequent}

Greenfield: How are [domain] systems typically structured? What are major components?
Subsequent: How do [target features] integrate with existing [domain] architecture?
</milestone_context>

<question>
[architecture question from step 4]
</question>

<project_context>
[PROJECT.md summary]
</project_context>

<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Component boundaries (what talks to what)
- Data flow (how information moves)
- Suggested build order (dependencies between components)
</downstream_consumer>

<quality_gate>
- [ ] Components clearly defined
- [ ] Boundaries explicit
- [ ] Build order implications noted
</quality_gate>

<output>
Write to: .planning/research/ARCHITECTURE.md
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
</output>
", subagent_type="gsd-project-researcher", description="Architecture research")

Task(prompt="
<research_type>
Project Research — Pitfalls dimension for [domain].
</research_type>

<milestone_context>
{greenfield OR subsequent}

Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
Subsequent: What are common mistakes when adding [target features] to [domain]?
</milestone_context>

<question>
[pitfalls question from step 4]
</question>

<project_context>
[PROJECT.md summary]
</project_context>

<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Warning signs (how to detect early)
- Prevention strategy (how to avoid)
- Which phase should address it
</downstream_consumer>

<quality_gate>
- [ ] Pitfalls are specific, not generic
- [ ] Prevention is actionable
- [ ] Phase mapping included
</quality_gate>

<output>
Write to: .planning/research/PITFALLS.md
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
</output>
", subagent_type="gsd-project-researcher", description="Pitfalls research")

Announce: "Spawning 4 research agents... may take 2-3 minutes."

6. Synthesize Results

After all agents complete, read their outputs and write .planning/research/SUMMARY.md:

• Read template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
• Synthesize executive summary from all 4 files
• Add confidence assessment

Critical: Include "Implications for Roadmap" section:

## Implications for Roadmap

Based on research, suggested phase structure:

1. **[Phase name]** — [rationale from research]
   - Addresses: [features from FEATURES.md]
   - Avoids: [pitfall from PITFALLS.md]
   - Uses: [stack element from STACK.md]

2. **[Phase name]** — [rationale from research]
   - Implements: [architecture component from ARCHITECTURE.md]
   ...

**Phase ordering rationale:**
- [Why this order based on dependencies discovered in ARCHITECTURE.md]
- [Why this grouping based on PITFALLS.md prevention strategies]

**Research flags for phases:**
- Phase [X]: Likely needs deeper research (reason)
- Phase [Y]: Standard patterns, unlikely to need research

This section directly feeds into /gsd:create-roadmap.

7. Commit Research

git add .planning/research/
git commit -m "docs: research [domain] ecosystem

Key findings:
- Stack: [one-liner]
- Architecture: [one-liner]
- Critical pitfall: [one-liner]"

8. Present Results

Research complete:

Files: SUMMARY.md, STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md

Key findings:
- Stack: [one-liner]
- Architecture: [one-liner]
- Critical pitfall: [one-liner]

---
## > Next Up
**Define requirements** - `/gsd:define-requirements`
<sub>`/clear` first</sub>
---

<success_criteria>

• PROJECT.md validated
• Domain identified and approved
• 4 gsd-project-researcher agents spawned in parallel
• All research files created
• SUMMARY.md synthesized with roadmap implications
• Research committed </success_criteria>