@hanzlaa/rcode 3.4.3 → 3.4.5

package/rihal/workflows/new-project-research-decision.md

@@ -0,0 +1,247 @@
+<purpose>
+Sub-step of new-project.md — Step 6 Research Decision. Decides whether to run domain research agents, handles existing research, and synthesizes findings before requirements.
+</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:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Researching [domain] ecosystem...
+```
+
+Create research directory:
+
+```bash
+mkdir -p .planning/research
+```
+
+**Determine milestone context:**
+
+- 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 rihal-project-researcher agents:
+
+```
+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.
+</milestone_context>
+
+<question>
+What's the standard 2026 stack for [domain]?
+</question>
+
+<files_to_read>
+- .planning/PROJECT.md (Project context and goals)
+</files_to_read>
+
+${AGENT_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
+</output>
+", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", 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>
+
+<files_to_read>
+- .planning/PROJECT.md
+</files_to_read>
+
+${AGENT_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
+</output>
+", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", 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>
+
+<files_to_read>
+- .planning/PROJECT.md
+</files_to_read>
+
+${AGENT_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
+</output>
+", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", 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>
+
+<files_to_read>
+- .planning/PROJECT.md
+</files_to_read>
+
+${AGENT_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
+</output>
+", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", description="Pitfalls research")
+```
+
+After all 4 agents complete, 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_SYNTHESIZER}
+
+<output>
+Write to: .planning/research/SUMMARY.md
+Synthesize into: recommended stack, table stakes vs differentiators, architecture outline, top pitfalls to avoid.
+</output>
+", subagent_type="rihal-research-synthesizer", model="${SYNTHESIZER_MODEL}", description="Synthesize research")
+```
+
+**Commit research (guarded):**
+
+```bash
+git add .planning/research/ 2>/dev/null \
+  && git commit -m "docs: add project research" 2>/dev/null \
+  || echo "ℹ .planning/ gitignored — research written, not committed"
+```
+
+Display research complete banner and key findings:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► 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.
+