Workflow: Research Phase

<purpose> Create and execute a research prompt for phases with unknowns. Produces FINDINGS.md that informs PLAN.md creation. </purpose>

<when_to_use>

• Technology choice unclear
• Best practices needed
• API/library investigation required
• Architecture decision pending </when_to_use>

<process> <step name="identify_unknowns"> Ask: What do we need to learn before we can plan this phase? - Technology choices? - Best practices? - API patterns? - Architecture approach? </step> <step name="create_research_prompt"> Use templates/research-prompt.md. Write to `.planning/phases/XX-name/RESEARCH.md`

Include:

• Clear research objective
• Scoped include/exclude lists
• Source preferences (official docs, Context7, 2024-2025)
• Output structure for FINDINGS.md </step>

<step name="execute_research"> Run the research prompt: - Use web search for current info - Use Context7 MCP for library docs - Prefer 2024-2025 sources - Structure findings per template </step> <step name="create_findings"> Write `.planning/phases/XX-name/FINDINGS.md`: - Summary with recommendation - Key findings with sources - Code examples if applicable - Metadata (confidence, dependencies, open questions, assumptions) </step> <step name="confidence_gate"> After creating FINDINGS.md, check confidence level.

If confidence is LOW: Use AskUserQuestion:

• header: "Low Confidence"
• question: "Research confidence is LOW: [reason]. How would you like to proceed?"
• options:
  • "Dig deeper" - Do more research before planning
  • "Proceed anyway" - Accept uncertainty, plan with caveats
  • "Pause" - I need to think about this

If confidence is MEDIUM: Inline: "Research complete (medium confidence). [brief reason]. Proceed to planning?"

If confidence is HIGH: Proceed directly, just note: "Research complete (high confidence)." </step>

<step name="open_questions_gate"> If FINDINGS.md has open_questions:

Present them inline: "Open questions from research:

• [Question 1]
• [Question 2]

These may affect implementation. Acknowledge and proceed? (yes / address first)"

If "address first": Gather user input on questions, update findings. </step>

<step name="offer_next"> ``` Research complete: .planning/phases/XX-name/FINDINGS.md Recommendation: [one-liner] Confidence: [level]

What's next?

1. Create phase plan (PLAN.md) using findings
2. Refine research (dig deeper)
3. Review findings

NOTE: FINDINGS.md is NOT committed separately. It will be committed with phase completion.
</step>

</process>

<success_criteria>
- RESEARCH.md exists with clear scope
- FINDINGS.md created with structured recommendations
- Confidence level and metadata included
- Ready to inform PLAN.md creation
</success_criteria>