/research

description: Run or re-run research phase for current spec
argument-hint: [spec-name] [--quick|--interactive]
allowed-tools: "*"

Research Phase

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

Read `${CLAUDE_PLUGIN_ROOT}/references/normal-mode-gates.md` before gathering context. Use it for exact mode parsing, missing discovery, contract reload, interview persistence, and delegation checks.

Checklist

Create a task for each item and complete in order:

1. **Gather context** -- resolve spec, read goal and existing files 2. **Interview gate** -- critical frontier and approval, or authorized quick bypass 3. **Execute parallel research** -- dispatch team of research-analyst + Explore agents 4. **Merge results** -- synthesize partial files into research.md 5. **Artifact review** -- automatic spec-reviewer loop in authorized quick mode 6. **Walkthrough & approval** -- display summary, get user approval 7. **Finalize** -- update state, commit, stop

Step 1: Gather Context

1. If `$ARGUMENTS` contains a spec name, use `ralph_find_spec()` to resolve it; otherwise use `ralph_resolve_current()`. Store the resolved spec directory as `SPEC_PATH`. 2. If no active spec, error: "No active spec. Run /ralph-specum:new <name> first." 3. Check the resolved spec directory exists 4. Read `.ralph-state.json` if it exists 5. Read `.progress.md` to understand the goal 6. Reject simultaneous exact `--quick` and `--interactive` tokens. Normalize `.ralph-state.json` with `phase_gate.py mode`; exact `--quick` enables persistent quick mode, exact `--interactive` clears it, and no flag resets legacy invalid state. 7. Run skill discovery pass 1 if the state lacks it. Reuse the current pass when present.

Step 2: Skill Load, Critical Grill, and Approval

Apply `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md` in full to resolve the design-tree frontier under the persisted gate state.

In both interactive and exact quick mode, reload the complete selected-skill manifest and every required current-work resource, hash them, record the current manifest, then call `begin-interview` for phase `research`. A core load failure blocks either mode.

If normalized `quickMode` is true, the helper records the authorized quick bypass; continue to Step 3 without questions.

In interactive mode:

1. Apply `${CLAUDE_PLUGIN_ROOT}/skills/interview-framework/SKILL.md` with phase `research`. 2. Build critical decision candidates from research direction, material constraints, systems in scope, and alternatives whose comparison would change later artifacts. 3. Inspect repository facts, prior specs, existing technology, and available commands. Do not ask setup, administrative, discoverable, or low-impact questions. 4. Ask the whole unblocked critical frontier, at most four questions per `AskUserQuestion` call. 5. Persist partial answers, handle control-only and bare-skip replies through the helper, and require explicit final approval. Use `classify-reply` before applying every reply, `revise --decision-id` for final-approval revisions, and `confirm --source approve-and-delegate` only for the explicit approval selection. 6. On approval, run `check-delegation` and continue immediately to Step 3 in the same response.

Treat this exploration territory as hints for the design tree, not a script:

• **Research direction** -- which unknowns or alternatives would materially change later artifacts?
• **Systems in scope** -- which boundaries, integrations, or user journeys need evidence?
• **Constraints and risk** -- which security, privacy, performance, or compatibility claims need validation?
• **Success evidence** -- what observations would distinguish viable approaches?

Apply domain-language modeling from the interview framework throughout the grill. Append each completed frontier round to `.progress.md`, then pass the confirmed decision brief as `Interview Context`.

Pass the approved brief and full skill manifest to artifact agents.

Step 3: Execute Parallel Research (Team-Based)

<mandatory> **PARALLEL EXECUTION IS MANDATORY - NO EXCEPTIONS.**

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

Key rules:

• Minimum 2 agents (1 research-analyst + 1 Explore). There are ZERO exceptions.
• ALL Task 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]
...

Follow the full team lifecycle: Clean up stale team (MANDATORY TeamDelete first) -> Create team -> Create tasks -> Spawn teammates (ALL in ONE message) -> Wait -> Shutdown -> Collect results -> Clean up team.

Immediately before each `research-analyst` Task call, run `phase_gate.py check-delegation`. Include the `[RALPH_PHASE_GATE]` marker, complete selected-skill manifest, and approved decision brief in its prompt. The PreToolUse hook repeats this check. `Explore` is read-only and remains allowed without a marker.

**Fallback**: If TeamCreate fails with "already leading" error, call `TeamDelete()` and retry `TeamCreate` once. If still fails, fall back to direct Task calls without a team. </mandatory>

Step 4: Delegate Result Merge

After all parallel tasks complete, run `check-delegation` and delegate the unified `$SPEC_PATH/research.md` write to a fresh `research-analyst`. Pass the absolute state and helper paths, complete `[RALPH_PHASE_GATE]` tuple (`state`, `phase`, `interviewId`, `discoveryRevision`, `contextDigest`), verbatim manifest, fresh artifact agent ID, matching load/write-check instructions, complete appr