research

name	research
description	Use when running or re-running discovery research for the active spec.
argument-hint	[spec-name]
allowed-tools	Read Write Edit Bash Agent AskUserQuestion
disable-model-invocation	true

Research Phase

Run parallel research for the active spec. You are a coordinator, not a researcher -- delegate ALL work to subagents.

Coordinator Checklist

Complete these coordination steps in order; do not create user-facing implementation tasks from this checklist:

1. Gather context -- resolve spec, read goal and existing files
2. Interview -- brainstorming dialogue (skip if --quick)
3. Execute parallel research -- dispatch team of research-analyst + Explore agents
4. Merge results -- synthesize partial files into research.md
5. Artifact review -- spec-reviewer validation loop (only if --quick)
6. Walkthrough & approval -- display summary, get user approval
7. Finalize -- update state, commit, stop

Step 1: Gather Context

1. Run curdx-flow snapshot --spec "$ARGUMENTS" when $ARGUMENTS begins with a spec name; otherwise run curdx-flow snapshot.
2. If snapshot.active is false, error: "No active spec. Run /curdx-flow:new first."
3. Use snapshot.spec.fsPath as $SPEC_PATH.
4. Read snapshot.state, snapshot.topology, and .progress.md to understand the goal.
5. Read references/workflow-contract.md, references/agent-output-contract.md, and references/context-and-dispatch-policy.md.

Step 2: Interview (skip if --quick)

Check if --quick appears in $ARGUMENTS. If present, skip to Step 3.

Read Context from .progress.md

Read .progress.md and parse:

1. Intent Classification (TRIVIAL, REFACTOR, GREENFIELD, MID_SIZED) for question counts
2. Prior interview responses to skip already-answered questions

Intent-Based Question Counts:

• TRIVIAL: 1-2 | REFACTOR: 3-5 | GREENFIELD: 5-10 | MID_SIZED: 3-7

Brainstorming Dialogue

Apply adaptive dialogue from ${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md. Ask context-driven questions one at a time, adapting to prior answers.

Research Exploration Territory (hints, not a script):

• Technical approach preference -- follow existing patterns or introduce new ones?
• Known constraints -- performance, compatibility, timeline, budget
• Integration surface area -- which systems, services, or APIs does this touch?
• Prior knowledge -- what does the user already know vs what needs discovery?
• Technologies to evaluate or avoid -- specific libraries, frameworks, or patterns

Research Approach Proposals

After dialogue, propose 2-3 research strategies. Examples (illustrative only):

• (A) Deep dive on specific technology/library comparison
• (B) Focus on existing codebase patterns with minimal external research
• (C) Broad survey across multiple alternatives before narrowing

Store Interview & Approach

Append to .progress.md under "Interview Responses":

### Research Interview (from research.md)
- [Topic 1]: [response]
- Chosen approach: [name] -- [brief description]

Pass combined context to subagent delegation as "Interview Context".

Step 3: Execute Parallel Research (Direct Agent, Teams Optional)

**PARALLEL EXECUTION IS MANDATORY - NO EXCEPTIONS.**

Read ${CLAUDE_PLUGIN_ROOT}/references/bounded-parallel-dispatch.md and follow the full dispatch pattern described there.

Key rules:

• Minimum 2 agents (1 research-analyst + 1 Explore). There are ZERO exceptions.
• ALL Agent calls MUST be in ONE message for true parallelism
• Each research-analyst handles ONE external topic; each Explore handles ONE codebase concern
• Break external research into MULTIPLE research-analyst teammates (do NOT combine)

Pre-Step: Identify and output research topics before spawning:

Research topics identified for parallel execution:
1. [Topic name] - [Agent type: research-analyst/Explore]
2. [Topic name] - [Agent type: research-analyst/Explore]
...

Default to direct Agent(...) calls. Agent Teams are experimental and disabled by default in Claude Code; use the team lifecycle only when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set and the TeamCreate / TaskCreate / TaskList / SendMessage tools are visible. If team tools are unavailable or fail, continue with direct Agent dispatch; this is normal, not degraded.

Direct path:

• Optional TaskCreate for each research topic. If unavailable or failing, continue without it.
• Spawn ALL research-analyst and Explore Agent(...) calls in ONE message, without team_name.
• Wait for Agent results, collect partial files, then continue to Step 4.

Optional Agent Teams path:

• TeamDelete() once -> TeamCreate(team_name: "research-$spec") -> optional TaskCreate per topic.
• Spawn ALL teammates in ONE message with team_name: "research-$spec" and unique name values.
• Wait via automatic teammate messages or one TaskList check, send shutdown_request to teammates, collect results, then TeamDelete().

Step 4: Merge Results

After ALL parallel tasks complete, merge into unified ./specs/$spec/research.md.

Read ${CLAUDE_PLUGIN_ROOT}/references/bounded-parallel-dispatch.md "Merging Results" section for the exact merge structure and process.

After merge, delete partial files: rm ./specs/$spec/.research-*.md

Step 5: Artifact Review (only in --quick mode)

**Review loop must complete before walkthrough. Max 3 iterations.**

If NOT --quick, skip to Step 6.

Invoke spec-reviewer via Agent tool to validate research.md. Follow the standard review loop:

• REVIEW_PASS: log to .progress.md, proceed to walkthrough
• REVIEW_FAIL (iteration < 3): log, extract feedback, re-invoke research-analyst with revision prompt, re-read, loop
• REVIEW_FAIL (iteration >= 3): log warning to .progress.md (graceful degradation), proceed
• No signal: treat as REVIEW_PASS (permissive)

Review delegation: Include full research.md content, iteration count, and prior findings. Upstream: none (research is first artifact).

Revision delegation: Re-invoke research-analyst with reviewer feedback. Focus on specific issues flagged.

Error handling: Reviewer no signal = REVIEW_PASS. Agent failure during revision = retry once, then use original.

Step 6: Walkthrough & Approval

**WALKTHROUGH IS REQUIRED - DO NOT SKIP.**

Read ./specs/$spec/research.md and display:

Research complete for '$spec'.
Output: $PWD/specs/$spec/research.md

## What I Found

**Summary**: [1-2 sentences from Executive Summary]

**Key Recommendations**:
1. [First recommendation]
2. [Second recommendation]
3. [Third recommendation]

**Feasibility**: [High/Medium/Low] | **Risk**: [High/Medium/Low] | **Effort**: [brief plain-language estimate]

User Approval (skip if --quick)

If --quick, skip to Step 7.

Ask ONE question: "How do you want to proceed?" with these options via AskUserQuestion:

1. Approve (Recommended) -- Accept artifact as-is, advance to next phase
2. Run review -- Spawn spec-reviewer to validate against rubrics, show findings, then loop back to this choice
3. Request changes -- Provide specific feedback to revise the artifact

If "Approve": proceed to Step 7. If "Run review": Invoke spec-reviewer via Agent tool with full research.md content (upstream: none). Display findings table. If REVIEW_PASS, note it. If REVIEW_FAIL, show feedback. Then loop back to this same 3-choice question (user decides next action). If "Request changes" or "Other": Ask what to change, invoke subagents with feedback, re-merge, re-display walkthrough, ask again with same 3 choices. Loop until approved.

Step 7: Finalize

Update State

1. Parse "Related Specs" table from research.md
2. Merge into .curdx-state.json (preserve all existing fields). $RELATED_SPECS_JSON is a JSON array literal (e.g. '[{"name":"foo","path":"./specs/foo"}]'):

   PATCH=$(node -e 'const s=process.argv[1]||"[]"; process.stdout.write(JSON.stringify({phase:"research",awaitingApproval:true,relatedSpecs:JSON.parse(s)}))' "$RELATED_SPECS_JSON")
   curdx-flow state merge \
     "$SPEC_PATH/.curdx-state.json" "$PATCH"
   

3. Update .progress.md with research completion

Commit Spec (if enabled)

Read commitSpec from .curdx-state.json. If true:

git add ./specs/$spec/research.md
git commit -m "spec($spec): add research findings"
git push -u origin $(git branch --show-current)

If commit or push fails, display warning but continue.

Stop

**STOP HERE. DO NOT PROCEED TO REQUIREMENTS.**

(Does not apply in --quick mode.)

1. Display: -> Next: Run /curdx-flow:requirements
2. End your response immediately
3. Wait for user to explicitly run /curdx-flow:requirements