diff --git a/commands/gsd/create-roadmap.md b/commands/gsd/create-roadmap.md
index 218a7391a..38bf97d3a 100644
--- a/commands/gsd/create-roadmap.md
+++ b/commands/gsd/create-roadmap.md
@@ -24,6 +24,7 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project.
 <context>
 @.planning/PROJECT.md
 @.planning/config.json
+@.planning/research/SUMMARY.md (if exists)
 </context>
 
 <process>
diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md
index 5221d5a24..56f7631be 100644
--- a/commands/gsd/new-project.md
+++ b/commands/gsd/new-project.md
@@ -303,7 +303,15 @@ Project initialized:
 
 ## ▶ Next Up
 
-**[Project Name]** — create roadmap
+Choose your path:
+
+**Option A: Research first** (recommended for new domains)
+Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls.
+
+`/gsd:research-project`
+
+**Option B: Create roadmap directly** (for familiar domains)
+Skip research if you know this domain well or have a clear spec.
 
 `/gsd:create-roadmap`
 
diff --git a/commands/gsd/research-project.md b/commands/gsd/research-project.md
new file mode 100644
index 000000000..d4fc211c7
--- /dev/null
+++ b/commands/gsd/research-project.md
@@ -0,0 +1,134 @@
+---
+name: gsd:research-project
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - WebSearch
+  - mcp__context7__*
+---
+
+<objective>
+Comprehensive domain research before roadmap creation.
+
+Answers the questions that inform quality roadmaps:
+- What's the standard stack for this type of product?
+- What features do users expect?
+- How are these systems typically structured?
+- What do projects in this domain commonly get wrong?
+
+Run after `/gsd:new-project`, before `/gsd:create-roadmap`.
+
+Output: `.planning/research/` folder with ecosystem knowledge.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/research-project.md
+@~/.claude/get-shit-done/templates/research-project/SUMMARY.md
+@~/.claude/get-shit-done/templates/research-project/STACK.md
+@~/.claude/get-shit-done/templates/research-project/FEATURES.md
+@~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
+@~/.claude/get-shit-done/templates/research-project/PITFALLS.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/config.json (if exists)
+</context>
+
+<process>
+
+<step name="validate">
+```bash
+# Verify project exists
+[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
+
+# Check if roadmap already exists
+[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md already exists. Research is typically done before roadmap creation."
+
+# Check if research already exists
+[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+</step>
+
+<step name="check_existing">
+**If RESEARCH_EXISTS:**
+
+Use AskUserQuestion:
+- header: "Research exists"
+- question: "Research folder already exists. What would you like to do?"
+- options:
+  - "View existing" — Show current research summary
+  - "Replace" — Run fresh research (will overwrite)
+  - "Cancel" — Keep existing research
+
+If "View existing": Read and display `.planning/research/SUMMARY.md`, then exit
+If "Cancel": Exit
+If "Replace": Continue with workflow
+</step>
+
+<step name="execute_research">
+Follow the research-project.md workflow:
+- Analyze PROJECT.md to determine domain
+- Identify research questions based on domain
+- Spawn parallel research agents
+- Aggregate results into `.planning/research/`
+- Create SUMMARY.md with roadmap implications
+</step>
+
+<step name="done">
+```
+Research complete:
+
+- Summary: .planning/research/SUMMARY.md
+- Stack: .planning/research/STACK.md
+- Features: .planning/research/FEATURES.md
+- Architecture: .planning/research/ARCHITECTURE.md
+- Pitfalls: .planning/research/PITFALLS.md
+
+---
+
+## ▶ Next Up
+
+**Create roadmap** — informed by research
+
+`/gsd:create-roadmap`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<when_to_use>
+**Use research-project for:**
+- Greenfield projects in established domains (community, e-commerce, SaaS)
+- When "what features should exist" is partially unknown
+- Complex integrations requiring ecosystem knowledge
+- Domains where best practices matter (auth, payments, real-time)
+- Any project where you'd Google "how to build a [X]" before starting
+
+**Skip research-project for:**
+- Well-defined specs ("build exactly this API")
+- Simple tools/utilities with clear scope
+- Adding features to existing codebases (use research-phase instead)
+- Domains you've built in many times before
+</when_to_use>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] Domain identified from project description
+- [ ] Research questions determined and approved
+- [ ] Parallel research agents spawned
+- [ ] All research documents created in .planning/research/
+- [ ] SUMMARY.md includes roadmap implications
+- [ ] Research committed to git
+- [ ] User knows next step (create-roadmap)
+</success_criteria>
diff --git a/get-shit-done/templates/research-project/ARCHITECTURE.md b/get-shit-done/templates/research-project/ARCHITECTURE.md
new file mode 100644
index 000000000..19d49dd82
--- /dev/null
+++ b/get-shit-done/templates/research-project/ARCHITECTURE.md
@@ -0,0 +1,204 @@
+# Architecture Research Template
+
+Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
+
+<template>
+
+```markdown
+# Architecture Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Standard Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+├───────┴────────────┴────────────┴────────────┴──────────────┤
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    [Component]                       │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│                        [Layer Name]                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+
+## Recommended Project Structure
+
+```
+src/
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+└── [folder]/           # [purpose]
+```
+
+### Structure Rationale
+
+- **[folder]/:** [why organized this way]
+- **[folder]/:** [why organized this way]
+
+## Architectural Patterns
+
+### Pattern 1: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+**Example:**
+```typescript
+// [Brief code example showing the pattern]
+```
+
+### Pattern 2: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+**Example:**
+```typescript
+// [Brief code example showing the pattern]
+```
+
+### Pattern 3: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+## Data Flow
+
+### Request Flow
+
+```
+[User Action]
+    ↓
+[Component] → [Handler] → [Service] → [Data Store]
+    ↓              ↓           ↓            ↓
+[Response] ← [Transform] ← [Query] ← [Database]
+```
+
+### State Management
+
+```
+[State Store]
+    ↓ (subscribe)
+[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
+```
+
+### Key Data Flows
+
+1. **[Flow name]:** [description of how data moves]
+2. **[Flow name]:** [description of how data moves]
+
+## Scaling Considerations
+
+| Scale | Architecture Adjustments |
+|-------|--------------------------|
+| 0-1k users | [approach — usually monolith is fine] |
+| 1k-100k users | [approach — what to optimize first] |
+| 100k+ users | [approach — when to consider splitting] |
+
+### Scaling Priorities
+
+1. **First bottleneck:** [what breaks first, how to fix]
+2. **Second bottleneck:** [what breaks next, how to fix]
+
+## Anti-Patterns
+
+### Anti-Pattern 1: [Name]
+
+**What people do:** [the mistake]
+**Why it's wrong:** [the problem it causes]
+**Do this instead:** [the correct approach]
+
+### Anti-Pattern 2: [Name]
+
+**What people do:** [the mistake]
+**Why it's wrong:** [the problem it causes]
+**Do this instead:** [the correct approach]
+
+## Integration Points
+
+### External Services
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| [service] | [how to connect] | [gotchas] |
+| [service] | [how to connect] | [gotchas] |
+
+### Internal Boundaries
+
+| Boundary | Communication | Notes |
+|----------|---------------|-------|
+| [module A ↔ module B] | [API/events/direct] | [considerations] |
+
+## Sources
+
+- [Architecture references]
+- [Official documentation]
+- [Case studies]
+
+---
+*Architecture research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**System Overview:**
+- Use ASCII diagrams for clarity
+- Show major components and their relationships
+- Don't over-detail — this is conceptual, not implementation
+
+**Project Structure:**
+- Be specific about folder organization
+- Explain the rationale for grouping
+- Match conventions of the chosen stack
+
+**Patterns:**
+- Include code examples where helpful
+- Explain trade-offs honestly
+- Note when patterns are overkill for small projects
+
+**Scaling Considerations:**
+- Be realistic — most projects don't need to scale to millions
+- Focus on "what breaks first" not theoretical limits
+- Avoid premature optimization recommendations
+
+**Anti-Patterns:**
+- Specific to this domain
+- Include what to do instead
+- Helps prevent common mistakes during implementation
+
+</guidelines>
diff --git a/get-shit-done/templates/research-project/FEATURES.md b/get-shit-done/templates/research-project/FEATURES.md
new file mode 100644
index 000000000..431c52ba5
--- /dev/null
+++ b/get-shit-done/templates/research-project/FEATURES.md
@@ -0,0 +1,147 @@
+# Features Research Template
+
+Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
+
+<template>
+
+```markdown
+# Feature Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Feature Landscape
+
+### Table Stakes (Users Expect These)
+
+Features users assume exist. Missing these = product feels incomplete.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+### Differentiators (Competitive Advantage)
+
+Features that set the product apart. Not required, but valuable.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
+
+### Anti-Features (Commonly Requested, Often Problematic)
+
+Features that seem good but create problems.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+| [feature] | [surface appeal] | [actual problems] | [better approach] |
+
+## Feature Dependencies
+
+```
+[Feature A]
+    └──requires──> [Feature B]
+                       └──requires──> [Feature C]
+
+[Feature D] ──enhances──> [Feature A]
+
+[Feature E] ──conflicts──> [Feature F]
+```
+
+### Dependency Notes
+
+- **[Feature A] requires [Feature B]:** [why the dependency exists]
+- **[Feature D] enhances [Feature A]:** [how they work together]
+- **[Feature E] conflicts with [Feature F]:** [why they're incompatible]
+
+## MVP Definition
+
+### Launch With (v1)
+
+Minimum viable product — what's needed to validate the concept.
+
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+- [ ] [Feature] — [why essential]
+
+### Add After Validation (v1.x)
+
+Features to add once core is working.
+
+- [ ] [Feature] — [trigger for adding]
+- [ ] [Feature] — [trigger for adding]
+
+### Future Consideration (v2+)
+
+Features to defer until product-market fit is established.
+
+- [ ] [Feature] — [why defer]
+- [ ] [Feature] — [why defer]
+
+## Feature Prioritization Matrix
+
+| Feature | User Value | Implementation Cost | Priority |
+|---------|------------|---------------------|----------|
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
+
+**Priority key:**
+- P1: Must have for launch
+- P2: Should have, add when possible
+- P3: Nice to have, future consideration
+
+## Competitor Feature Analysis
+
+| Feature | Competitor A | Competitor B | Our Approach |
+|---------|--------------|--------------|--------------|
+| [feature] | [how they do it] | [how they do it] | [our plan] |
+| [feature] | [how they do it] | [how they do it] | [our plan] |
+
+## Sources
+
+- [Competitor products analyzed]
+- [User research or feedback sources]
+- [Industry standards referenced]
+
+---
+*Feature research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Table Stakes:**
+- These are non-negotiable for launch
+- Users don't give credit for having them, but penalize for missing them
+- Example: A community platform without user profiles is broken
+
+**Differentiators:**
+- These are where you compete
+- Should align with the Core Value from PROJECT.md
+- Don't try to differentiate on everything
+
+**Anti-Features:**
+- Prevent scope creep by documenting what seems good but isn't
+- Include the alternative approach
+- Example: "Real-time everything" often creates complexity without value
+
+**Feature Dependencies:**
+- Critical for roadmap phase ordering
+- If A requires B, B must be in an earlier phase
+- Conflicts inform what NOT to combine in same phase
+
+**MVP Definition:**
+- Be ruthless about what's truly minimum
+- "Nice to have" is not MVP
+- Launch with less, validate, then expand
+
+</guidelines>
diff --git a/get-shit-done/templates/research-project/PITFALLS.md b/get-shit-done/templates/research-project/PITFALLS.md
new file mode 100644
index 000000000..9d66e6a6c
--- /dev/null
+++ b/get-shit-done/templates/research-project/PITFALLS.md
@@ -0,0 +1,200 @@
+# Pitfalls Research Template
+
+Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
+
+<template>
+
+```markdown
+# Pitfalls Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Critical Pitfalls
+
+### Pitfall 1: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 2: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+### Pitfall 3: [Name]
+
+**What goes wrong:**
+[Description of the failure mode]
+
+**Why it happens:**
+[Root cause — why developers make this mistake]
+
+**How to avoid:**
+[Specific prevention strategy]
+
+**Warning signs:**
+[How to detect this early before it becomes a problem]
+
+**Phase to address:**
+[Which roadmap phase should prevent this]
+
+---
+
+[Continue for all critical pitfalls...]
+
+## Technical Debt Patterns
+
+Shortcuts that seem reasonable but create long-term problems.
+
+| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
+|----------|-------------------|----------------|-----------------|
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
+
+## Integration Gotchas
+
+Common mistakes when connecting to external services.
+
+| Integration | Common Mistake | Correct Approach |
+|-------------|----------------|------------------|
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+| [service] | [what people do wrong] | [what to do instead] |
+
+## Performance Traps
+
+Patterns that work at small scale but fail as usage grows.
+
+| Trap | Symptoms | Prevention | When It Breaks |
+|------|----------|------------|----------------|
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
+
+## Security Mistakes
+
+Domain-specific security issues beyond general web security.
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+| [mistake] | [what could happen] | [how to avoid] |
+
+## UX Pitfalls
+
+Common user experience mistakes in this domain.
+
+| Pitfall | User Impact | Better Approach |
+|---------|-------------|-----------------|
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+| [pitfall] | [how users suffer] | [what to do instead] |
+
+## "Looks Done But Isn't" Checklist
+
+Things that appear complete but are missing critical pieces.
+
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+- [ ] **[Feature]:** Often missing [thing] — verify [check]
+
+## Recovery Strategies
+
+When pitfalls occur despite prevention, how to recover.
+
+| Pitfall | Recovery Cost | Recovery Steps |
+|---------|---------------|----------------|
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
+
+## Pitfall-to-Phase Mapping
+
+How roadmap phases should address these pitfalls.
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+| [pitfall] | Phase [X] | [how to verify prevention worked] |
+
+## Sources
+
+- [Post-mortems referenced]
+- [Community discussions]
+- [Official "gotchas" documentation]
+- [Personal experience / known issues]
+
+---
+*Pitfalls research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Critical Pitfalls:**
+- Focus on domain-specific issues, not generic mistakes
+- Include warning signs — early detection prevents disasters
+- Link to specific phases — makes pitfalls actionable
+
+**Technical Debt:**
+- Be realistic — some shortcuts are acceptable
+- Note when shortcuts are "never acceptable" vs. "only in MVP"
+- Include the long-term cost to inform tradeoff decisions
+
+**Performance Traps:**
+- Include scale thresholds ("breaks at 10k users")
+- Focus on what's relevant for this project's expected scale
+- Don't over-engineer for hypothetical scale
+
+**Security Mistakes:**
+- Beyond OWASP basics — domain-specific issues
+- Example: Community platforms have different security concerns than e-commerce
+- Include risk level to prioritize
+
+**"Looks Done But Isn't":**
+- Checklist format for verification during execution
+- Common in demos vs. production
+- Prevents "it works on my machine" issues
+
+**Pitfall-to-Phase Mapping:**
+- Critical for roadmap creation
+- Each pitfall should map to a phase that prevents it
+- Informs phase ordering and success criteria
+
+</guidelines>
diff --git a/get-shit-done/templates/research-project/STACK.md b/get-shit-done/templates/research-project/STACK.md
new file mode 100644
index 000000000..cdd663ba2
--- /dev/null
+++ b/get-shit-done/templates/research-project/STACK.md
@@ -0,0 +1,120 @@
+# Stack Research Template
+
+Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
+
+<template>
+
+```markdown
+# Stack Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Recommended Stack
+
+### Core Technologies
+
+| Technology | Version | Purpose | Why Recommended |
+|------------|---------|---------|-----------------|
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+| [name] | [version] | [what it does] | [why experts use it for this domain] |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+| [name] | [version] | [what it does] | [specific use case] |
+
+### Development Tools
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| [name] | [what it does] | [configuration tips] |
+| [name] | [what it does] | [configuration tips] |
+
+## Installation
+
+```bash
+# Core
+npm install [packages]
+
+# Supporting
+npm install [packages]
+
+# Dev dependencies
+npm install -D [packages]
+```
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| [our choice] | [other option] | [conditions where alternative is better] |
+| [our choice] | [other option] | [conditions where alternative is better] |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| [technology] | [specific problem] | [recommended alternative] |
+| [technology] | [specific problem] | [recommended alternative] |
+
+## Stack Patterns by Variant
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+**If [condition]:**
+- Use [variation]
+- Because [reason]
+
+## Version Compatibility
+
+| Package A | Compatible With | Notes |
+|-----------|-----------------|-------|
+| [package@version] | [package@version] | [compatibility notes] |
+
+## Sources
+
+- [Context7 library ID] — [topics fetched]
+- [Official docs URL] — [what was verified]
+- [Other source] — [confidence level]
+
+---
+*Stack research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**Core Technologies:**
+- Include specific version numbers
+- Explain why this is the standard choice, not just what it does
+- Focus on technologies that affect architecture decisions
+
+**Supporting Libraries:**
+- Include libraries commonly needed for this domain
+- Note when each is needed (not all projects need all libraries)
+
+**Alternatives:**
+- Don't just dismiss alternatives
+- Explain when alternatives make sense
+- Helps user make informed decisions if they disagree
+
+**What NOT to Use:**
+- Actively warn against outdated or problematic choices
+- Explain the specific problem, not just "it's old"
+- Provide the recommended alternative
+
+**Version Compatibility:**
+- Note any known compatibility issues
+- Critical for avoiding debugging time later
+
+</guidelines>
diff --git a/get-shit-done/templates/research-project/SUMMARY.md b/get-shit-done/templates/research-project/SUMMARY.md
new file mode 100644
index 000000000..c336b8a8e
--- /dev/null
+++ b/get-shit-done/templates/research-project/SUMMARY.md
@@ -0,0 +1,170 @@
+# Research Summary Template
+
+Template for `.planning/research/SUMMARY.md` — executive summary of project research with roadmap implications.
+
+<template>
+
+```markdown
+# Project Research Summary
+
+**Project:** [name from PROJECT.md]
+**Domain:** [inferred domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Executive Summary
+
+[2-3 paragraph overview of research findings]
+
+- What type of product this is and how experts build it
+- The recommended approach based on research
+- Key risks and how to mitigate them
+
+## Key Findings
+
+### Recommended Stack
+
+[Summary from STACK.md — 1-2 paragraphs]
+
+**Core technologies:**
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+- [Technology]: [purpose] — [why recommended]
+
+### Expected Features
+
+[Summary from FEATURES.md]
+
+**Must have (table stakes):**
+- [Feature] — users expect this
+- [Feature] — users expect this
+
+**Should have (competitive):**
+- [Feature] — differentiator
+- [Feature] — differentiator
+
+**Defer (v2+):**
+- [Feature] — not essential for launch
+
+### Architecture Approach
+
+[Summary from ARCHITECTURE.md — 1 paragraph]
+
+**Major components:**
+1. [Component] — [responsibility]
+2. [Component] — [responsibility]
+3. [Component] — [responsibility]
+
+### Critical Pitfalls
+
+[Top 3-5 from PITFALLS.md]
+
+1. **[Pitfall]** — [how to avoid]
+2. **[Pitfall]** — [how to avoid]
+3. **[Pitfall]** — [how to avoid]
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+### Phase 1: [Name]
+**Rationale:** [why this comes first based on research]
+**Delivers:** [what this phase produces]
+**Addresses:** [features from FEATURES.md]
+**Avoids:** [pitfall from PITFALLS.md]
+
+### Phase 2: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+**Uses:** [stack elements from STACK.md]
+**Implements:** [architecture component]
+
+### Phase 3: [Name]
+**Rationale:** [why this order]
+**Delivers:** [what this phase produces]
+
+[Continue for suggested phases...]
+
+### Phase Ordering Rationale
+
+- [Why this order based on dependencies discovered]
+- [Why this grouping based on architecture patterns]
+- [How this avoids pitfalls from research]
+
+### Research Flags
+
+Phases likely needing deeper research during planning:
+- **Phase [X]:** [reason — e.g., "complex integration, needs API research"]
+- **Phase [Y]:** [reason — e.g., "niche domain, sparse documentation"]
+
+Phases with standard patterns (skip research-phase):
+- **Phase [X]:** [reason — e.g., "well-documented, established patterns"]
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [HIGH/MEDIUM/LOW] | [reason] |
+| Features | [HIGH/MEDIUM/LOW] | [reason] |
+| Architecture | [HIGH/MEDIUM/LOW] | [reason] |
+| Pitfalls | [HIGH/MEDIUM/LOW] | [reason] |
+
+**Overall confidence:** [HIGH/MEDIUM/LOW]
+
+### Gaps to Address
+
+[Any areas where research was inconclusive or needs validation during implementation]
+
+- [Gap]: [how to handle during planning/execution]
+- [Gap]: [how to handle during planning/execution]
+
+## Sources
+
+### Primary (HIGH confidence)
+- [Context7 library ID] — [topics]
+- [Official docs URL] — [what was checked]
+
+### Secondary (MEDIUM confidence)
+- [Source] — [finding]
+
+### Tertiary (LOW confidence)
+- [Source] — [finding, needs validation]
+
+---
+*Research completed: [date]*
+*Ready for roadmap: yes*
+```
+
+</template>
+
+<guidelines>
+
+**Executive Summary:**
+- Write for someone who will only read this section
+- Include the key recommendation and main risk
+- 2-3 paragraphs maximum
+
+**Key Findings:**
+- Summarize, don't duplicate full documents
+- Link to detailed docs (STACK.md, FEATURES.md, etc.)
+- Focus on what matters for roadmap decisions
+
+**Implications for Roadmap:**
+- This is the most important section
+- Directly informs create-roadmap workflow
+- Be explicit about phase suggestions and rationale
+- Include research flags for each suggested phase
+
+**Confidence Assessment:**
+- Be honest about uncertainty
+- Note gaps that need resolution during planning
+- HIGH = verified with official sources
+- MEDIUM = community consensus, multiple sources agree
+- LOW = single source or inference
+
+**Integration with create-roadmap:**
+- This file is loaded as @context in create-roadmap
+- Phase suggestions here become starting point for roadmap
+- Research flags inform detect_research_needs step
+
+</guidelines>
diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md
index 33bbc8feb..bcfc06d74 100644
--- a/get-shit-done/workflows/create-roadmap.md
+++ b/get-shit-done/workflows/create-roadmap.md
@@ -9,7 +9,8 @@ that delivers value. The roadmap provides structure, not detailed tasks.
 1. ~/.claude/get-shit-done/templates/roadmap.md
 2. ~/.claude/get-shit-done/templates/state.md
 3. Read `.planning/PROJECT.md` if it exists
-   </required_reading>
+4. Read `.planning/research/SUMMARY.md` if it exists
+</required_reading>
 
 <process>
 
@@ -27,6 +28,39 @@ If proceeding without brief, gather quick context:
 - What's the rough scope?
 </step>
 
+<step name="load_research">
+Check for project research:
+
+```bash
+[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+
+**If RESEARCH_EXISTS:**
+
+Read `.planning/research/SUMMARY.md` and extract:
+- Suggested phase structure from "Implications for Roadmap" section
+- Research flags for each suggested phase
+- Key findings that inform phase ordering
+
+```
+Research found. Using findings to inform roadmap:
+
+Suggested phases from research:
+1. [Phase from research] — [rationale]
+2. [Phase from research] — [rationale]
+3. [Phase from research] — [rationale]
+
+Research confidence: [HIGH/MEDIUM/LOW]
+
+Proceeding with research-informed phase identification...
+```
+
+**If NO_RESEARCH:**
+
+Continue without research context. Phase identification will rely on PROJECT.md and domain expertise only.
+
+**Note:** Research is optional. Roadmap can be created without it, but research-informed roadmaps tend to have better phase structure and fewer surprises.
+</step>
 
 <step name="detect_domain">
 Scan for available domain expertise:
@@ -83,6 +117,15 @@ Select (comma-separate for multiple):
 <step name="identify_phases">
 Derive phases from the actual work needed.
 
+**If research exists (.planning/research/SUMMARY.md):**
+- Start with suggested phases from research
+- Validate against PROJECT.md requirements
+- Adjust based on domain expertise (if any)
+- Research already identified dependencies and pitfalls — use them
+
+**If no research:**
+- Derive phases from PROJECT.md and domain expertise only
+
 **Check depth setting:**
 ```bash
 cat .planning/config.json 2>/dev/null | grep depth
diff --git a/get-shit-done/workflows/research-project.md b/get-shit-done/workflows/research-project.md
new file mode 100644
index 000000000..ec159af9d
--- /dev/null
+++ b/get-shit-done/workflows/research-project.md
@@ -0,0 +1,315 @@
+<purpose>
+Comprehensive domain research before roadmap creation.
+
+Answers the questions that inform quality roadmaps:
+- What's the standard stack for this type of product?
+- What features do users expect?
+- How are these systems typically structured?
+- What do projects in this domain commonly get wrong?
+
+This research shapes the roadmap. Without it, phases are guesses based on intuition.
+With it, phases reflect how experts actually build these systems.
+</purpose>
+
+<when_to_use>
+**Use for:**
+- Greenfield projects in established domains
+- When "what features should exist" is partially unknown
+- Complex integrations requiring ecosystem knowledge
+- Any project where you'd research before starting
+
+**Skip for:**
+- Well-defined specs with clear scope
+- Simple utilities
+- Brownfield features (use research-phase instead)
+</when_to_use>
+
+<required_reading>
+**Read these files NOW:**
+
+1. ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
+2. ~/.claude/get-shit-done/templates/research-project/STACK.md
+3. ~/.claude/get-shit-done/templates/research-project/FEATURES.md
+4. ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
+5. ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
+6. .planning/PROJECT.md
+</required_reading>
+
+<process>
+
+<step name="analyze_project">
+Read PROJECT.md and extract:
+
+1. **Domain**: What type of product is this?
+   - Community platform, e-commerce, SaaS tool, developer tool, mobile app, game, etc.
+
+2. **Stated stack**: Did user specify technologies?
+   - If yes: research how to use that stack for this domain
+   - If no: research what stack is standard for this domain
+
+3. **Core value**: What's the one thing that must work?
+
+4. **Requirements**: What did user explicitly request?
+
+5. **Constraints**: Any limitations on choices?
+
+Present analysis:
+```
+Domain analysis:
+
+- Type: [inferred domain]
+- Stack: [stated or "to be determined"]
+- Core: [core value from PROJECT.md]
+- Key requirements: [list]
+
+Does this look right? (yes / adjust)
+```
+</step>
+
+<step name="determine_research_questions">
+Based on domain, generate 4 research questions:
+
+| Dimension | Question Template |
+|-----------|-------------------|
+| Stack | "What's the standard 2025 stack for building [domain]?" |
+| Features | "What features do [domain] products have? What's table stakes vs. differentiating?" |
+| Architecture | "How are [domain] systems typically structured? What are the major components?" |
+| Pitfalls | "What do [domain] projects commonly get wrong? What are the critical mistakes?" |
+
+**Customize questions based on project specifics:**
+
+- If stack is stated: "How do you build [domain] with [stack]? What supporting libraries?"
+- If specific features mentioned: "How do experts implement [feature] in [domain]?"
+- If constraints exist: "What's the best approach for [domain] given [constraint]?"
+
+Present questions for approval:
+```
+Research questions:
+
+1. Stack: [question]
+2. Features: [question]
+3. Architecture: [question]
+4. Pitfalls: [question]
+
+Proceed with these questions? (yes / adjust)
+```
+</step>
+
+<step name="spawn_research_agents">
+Spawn 4 parallel Task agents using subagent_type: "general-purpose".
+
+**Agent prompt template:**
+
+```
+Research question: [question]
+
+Domain: [domain from analyze_project]
+Project context: [summary from PROJECT.md]
+
+Instructions:
+1. Use Context7 to find relevant library documentation
+2. Use WebSearch to find current best practices (2024-2025)
+3. Cross-verify all WebSearch findings with authoritative sources
+4. Focus on actionable recommendations, not theoretical overview
+
+Output format:
+- Direct answer to the question
+- Specific recommendations with rationale
+- Code examples where relevant
+- Sources with confidence levels (HIGH/MEDIUM/LOW)
+
+Constraints:
+- Prefer official docs and Context7 over blog posts
+- Mark anything unverified as LOW confidence
+- Be specific: versions, library names, patterns
+```
+
+**Spawn all 4 agents in parallel:**
+
+```
+Spawning research agents:
+
+1. Stack research → [running]
+2. Features research → [running]
+3. Architecture research → [running]
+4. Pitfalls research → [running]
+
+This may take 2-3 minutes...
+```
+
+Wait for all agents to complete.
+</step>
+
+<step name="aggregate_results">
+Create `.planning/research/` directory:
+
+```bash
+mkdir -p .planning/research
+```
+
+**For each research dimension, create document using templates:**
+
+1. **STACK.md** — From stack agent results
+   - Use template from templates/research-project/STACK.md
+   - Populate with agent findings
+   - Include version numbers and rationale
+
+2. **FEATURES.md** — From features agent results
+   - Use template from templates/research-project/FEATURES.md
+   - Categorize as table stakes / differentiators / anti-features
+   - Note complexity and dependencies
+
+3. **ARCHITECTURE.md** — From architecture agent results
+   - Use template from templates/research-project/ARCHITECTURE.md
+   - Include system diagrams (ASCII)
+   - Document component responsibilities
+
+4. **PITFALLS.md** — From pitfalls agent results
+   - Use template from templates/research-project/PITFALLS.md
+   - Include warning signs and prevention
+   - Note which phase should address each pitfall
+
+5. **SUMMARY.md** — Synthesize all results
+   - Use template from templates/research-project/SUMMARY.md
+   - Executive summary of all findings
+   - **Critical: Include "Implications for Roadmap" section**
+   - Suggest phase structure based on research
+</step>
+
+<step name="roadmap_implications">
+In SUMMARY.md, include explicit roadmap guidance:
+
+```markdown
+## 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]
+
+2. **[Phase name]** — [rationale from research]
+   - Implements: [architecture component from ARCHITECTURE.md]
+   - Uses: [stack element from STACK.md]
+
+3. **[Phase name]** — [rationale from research]
+   ...
+
+**Phase ordering rationale:**
+- [Why this order based on dependencies discovered]
+- [Why this grouping based on architecture patterns]
+
+**Research flags for phases:**
+- Phase [X]: Likely needs deeper research (reason)
+- Phase [Y]: Standard patterns, unlikely to need research
+```
+
+This section directly feeds into create-roadmap.
+</step>
+
+<step name="confidence_assessment">
+Add confidence section to SUMMARY.md:
+
+```markdown
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [HIGH/MEDIUM/LOW] | [reason - e.g., "verified with Context7"] |
+| Features | [HIGH/MEDIUM/LOW] | [reason - e.g., "based on competitor analysis"] |
+| Architecture | [HIGH/MEDIUM/LOW] | [reason - e.g., "standard patterns, well-documented"] |
+| Pitfalls | [HIGH/MEDIUM/LOW] | [reason - e.g., "from post-mortems and community"] |
+
+**Overall confidence:** [HIGH/MEDIUM/LOW]
+
+**Gaps to address during planning:**
+- [Any areas where research was inconclusive]
+- [Topics that need phase-specific research later]
+```
+</step>
+
+<step name="git_commit">
+Commit research:
+
+```bash
+git add .planning/research/
+git commit -m "$(cat <<'EOF'
+docs: research [domain] ecosystem
+
+Researched stack, features, architecture, and pitfalls for [project name].
+
+Key findings:
+- Stack: [one-liner]
+- Architecture: [one-liner]
+- Critical pitfall: [one-liner]
+
+Ready for roadmap creation.
+EOF
+)"
+```
+</step>
+
+<step name="present_results">
+```
+Research complete:
+
+## Files Created
+
+- .planning/research/SUMMARY.md — Executive summary + roadmap implications
+- .planning/research/STACK.md — Recommended technologies
+- .planning/research/FEATURES.md — Feature landscape
+- .planning/research/ARCHITECTURE.md — System structure patterns
+- .planning/research/PITFALLS.md — Common mistakes to avoid
+
+## Key Findings
+
+**Stack:** [one-liner from STACK.md]
+**Architecture:** [one-liner from ARCHITECTURE.md]
+**Critical pitfall:** [most important from PITFALLS.md]
+
+## Suggested Phases
+
+[List from SUMMARY.md Implications for Roadmap section]
+
+---
+
+## ▶ Next Up
+
+**Create roadmap** — using research findings
+
+`/gsd:create-roadmap`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<research_quality>
+**Good research answers:**
+- What specific libraries/versions to use (not just "use React")
+- What features users expect (not just "add features")
+- How components connect (not just "it has a backend")
+- What specific mistakes to avoid (not just "be careful")
+
+**Research is ready when:**
+- Each document has specific, actionable content
+- Sources are cited with confidence levels
+- Roadmap implications are explicit
+- A developer could start planning immediately
+</research_quality>
+
+<success_criteria>
+- [ ] PROJECT.md analyzed, domain identified
+- [ ] Research questions customized and approved
+- [ ] 4 parallel agents spawned and completed
+- [ ] STACK.md created with specific recommendations
+- [ ] FEATURES.md created with prioritized features
+- [ ] ARCHITECTURE.md created with system structure
+- [ ] PITFALLS.md created with prevention strategies
+- [ ] SUMMARY.md created with roadmap implications
+- [ ] Confidence assessment included
+- [ ] Research committed to git
+</success_criteria>