# Subworkflow: new-project — Research Phase

<purpose>
Research phase of /rcode-new-project. Loaded from new-project.md via @-reference when user opts into research. Produces research artifacts that feed into Step 7 (Define Requirements) and Step 8 (Create Roadmap).

**Invariants from parent:** {project_name}, {planning_artifacts}, {researcher_model}, {synthesizer_model}, {user_preference_research}. Set in new-project.md Steps 1–5.5 before this loads.
</purpose>

## 6. Research Decision

**If auto mode:** Default to "Research first" without asking.

Use AskUserQuestion:

- header: "Research"
- question: "Research the domain ecosystem before defining requirements?"
- options:
  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
  - "Skip research" — I know this domain well, go straight to requirements

**If "Research first":**

Display stage banner:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 rcode ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Researching [domain] ecosystem...
```

Create research directory:

```bash
mkdir -p .planning/research
```

**Determine milestone context:**

Check if this is greenfield or subsequent milestone:

- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
- If "Validated" requirements exist → Subsequent milestone (adding to existing app)

Display spawning indicator:

```
◆ Spawning 4 researchers in parallel...
  → Stack research
  → Features research
  → Architecture research
  → Pitfalls research
```

Spawn 4 parallel rcode-project-researcher agents with path references:

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

<objective>
Identify the standard stack for [domain].

Why this matters: this research feeds requirements definition and roadmap
creation for {project_name}. A sufficient result lets the roadmap pick
concrete libraries (with versions and rationale) and sequence build phases —
not a vague survey of options.
</objective>

<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>
What's the standard 2025 stack for [domain]?
</question>

<files_to_read>
- {project_path} (Project context and goals)
</files_to_read>

${AGENT_SKILLS_RESEARCHER}

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

<quality_gate>
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Confidence levels assigned to each recommendation
</quality_gate>

<output>
Write to: .planning/research/STACK.md
Use template: .rcode/templates/research-project/STACK.md
</output>
", subagent_type="rcode-project-researcher", model="{researcher_model}", description="Stack research")

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

<objective>
Identify the feature landscape for [domain].

Why this matters: this research feeds requirements definition and roadmap
creation for {project_name}. A sufficient result lets requirements separate
table stakes from differentiators and anti-features — not an undifferentiated
feature list.
</objective>

<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>
What features do [domain] products have? What's table stakes vs differentiating?
</question>

<files_to_read>
- {project_path} (Project context)
</files_to_read>

${AGENT_SKILLS_RESEARCHER}

<downstream_consumer>
Your FEATURES.md feeds into requirements definition. 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 (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies between features identified
</quality_gate>

<output>
Write to: .planning/research/FEATURES.md
Use template: .rcode/templates/research-project/FEATURES.md
</output>
", subagent_type="rcode-project-researcher", model="{researcher_model}", description="Features research")

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

<objective>
Identify how [domain] systems are structured.

Why this matters: this research feeds requirements definition and roadmap
creation for {project_name}. A sufficient result lets the roadmap sequence
phases by component dependency and data flow — not a generic architecture
sketch.
</objective>

<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>
How are [domain] systems typically structured? What are major components?
</question>

<files_to_read>
- {project_path} (Project context)
</files_to_read>

${AGENT_SKILLS_RESEARCHER}

<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 with boundaries
- [ ] Data flow direction explicit
- [ ] Build order implications noted
</quality_gate>

<output>
Write to: .planning/research/ARCHITECTURE.md
Use template: .rcode/templates/research-project/ARCHITECTURE.md
</output>
", subagent_type="rcode-project-researcher", model="{researcher_model}", description="Architecture research")

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

<objective>
Identify the common mistakes in [domain] projects.

Why this matters: this research feeds requirements definition and roadmap
creation for {project_name}. A sufficient result lets the roadmap assign each
pitfall a prevention step in a specific phase — not a generic warning list.
</objective>

<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>
What do [domain] projects commonly get wrong? Critical mistakes?
</question>

<files_to_read>
- {project_path} (Project context)
</files_to_read>

${AGENT_SKILLS_RESEARCHER}

<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 to this domain (not generic advice)
- [ ] Prevention strategies are actionable
- [ ] Phase mapping included where relevant
</quality_gate>

<output>
Write to: .planning/research/PITFALLS.md
Use template: .rcode/templates/research-project/PITFALLS.md
</output>
", subagent_type="rcode-project-researcher", model="{researcher_model}", description="Pitfalls research")
```

**Sufficiency loop (per dimension, runs before synthesis):**

@.rcode/references/iterative-retrieval.md

After the 4 parallel researchers return, evaluate each dimension's returned
artifact (STACK / FEATURES / ARCHITECTURE / PITFALLS) for sufficiency against
that dimension's `<objective>` — does it cover every sub-question, are
recommendations specific (versions/rationale) not vague, and were any
`## RESEARCH INCONCLUSIVE` or blocked signals returned. For any dimension
that is insufficient, re-dispatch that dimension's `rcode-project-researcher`
with a follow-up prompt naming the specific gaps and including the prior
result, asking only for the missing pieces. This loop is hard-capped at 3
cycles per dimension (initial + up to 2 follow-ups). After the cap, proceed
with the best result for that dimension and note residual gaps in its
artifact. Only then continue to synthesis.

After all 4 agents complete and the sufficiency loop has settled, spawn
synthesizer to create SUMMARY.md:

```
Task(prompt="
<task>
Synthesize research outputs into SUMMARY.md.
</task>

<files_to_read>
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
</files_to_read>

${AGENT_SKILLS_SYNTHESIZER}

<output>
Write to: .planning/research/SUMMARY.md
Use template: .rcode/templates/research-project/SUMMARY.md
Commit after writing.
</output>
", subagent_type="rcode-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
```

Display research complete banner and key findings:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 rcode ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Key Findings

**Stack:** [from SUMMARY.md]
**Table Stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]

Files: `.planning/research/`
```

**If "Skip research":** Continue to Step 7.


## Next Up

- `/rcode-new-project-roadmap` — produce requirements and roadmap from research findings
