/research-inline

Research (Inline Reference)

This file is read by the alignment check, plan-chunks and `/craft:research` to run the discover flow inline in the current loop, never through the Skill tool. The standalone `/craft:research` command Reads this same file from its Step 2.

Inputs

• `QUERY` - the ask: a topic when standalone, a research question from the alignment check or the planner.
• `STORY` - absolute path of the story file. Absent when standalone.
• `DOOR` - `alignment` or `planner`. Absent when standalone.
• `DEPTH` - `--quick` or none. The research command's `--deep` and `--exhaustive` never reach this file; the command acts on them itself after Step 7.
• `PROJECT` - set by the caller. With a story, it is the folder above the story's `.craft/`.

Step 1: Draft the Question and Branches

Draft a short research question from `QUERY`. A topic typed at the standalone command is already a question; a story's outside premise is not, so state it as one.

Then break the question into 3-5 branches (sub-questions) that cover it from different angles. Use your own knowledge to decompose - no searching needed. Think about:

• What is X? (fundamentals)
• How does X work? (mechanics)
• What are the alternatives? (landscape)
• What are the trade-offs? (decision support)
• What do practitioners report? (real-world experience)
• What's the current state of the art? (freshness)

Not every question needs all angles. A focused question ("best auth library for Next.js") might need 3 branches. A broad one ("how should we architect real-time sync") might need 5.

Step 2: The Two-Readings Test

Ask: "Would a different reading of the ask produce a different set of branches?" Run it on every decompose, standalone and refresh included.

"A website that works like a Claude Code plugin" and "a plugin published as a website" send research to two different places - that fires the test. A topic with one sensible reading does not.

**When the test does not fire:** print exactly one line and start:

`Researching: <question>. Branches: <a>, <b>, <c>.`

**When it fires:** Read `${CLAUDE_PLUGIN_ROOT}/commands/references/auq-grammar.md` and mirror the fork gate it models: short prose first, then one widget.

AskUserQuestion:
  header: "1 of 1"
  question: "<The outside thing, the reading the branches assume, the research question and its branches. Which reading did you mean?>"
  options:
    - label: "<The drafted reading in plain words> (Recommended)"
      description: "<The branches this reading researches>"
    - label: "<The other reading the test found>"
      description: "<Where it sends the research instead>"

The drafted reading is first and carries `(Recommended)`. Author no escape option; the harness's own "Chat about this" is the only exit. An answer in the user's own words rewrites the branches from those words and the run starts - no second ask.

Step 3: Create the Research Folder

This runs after Step 2, so the slug follows the confirmed reading. If the slug is already taken by a different question, add a distinguishing suffix.

Create `$PROJECT/.craft/research/{topic-slug}/` using Bash `mkdir -p`.

Write initial `_plan.md` stub with `status: in-progress`:

---
query: "original query"
date: {today}
status: in-progress
depth: 1
stale_after: {today + 3 months}
---

# Research: {Topic}

> In progress - agents researching...

Step 4: Dispatch Researchers

**Spawn one researcher agent per branch in parallel** via the Agent tool:

subagent_type: "craft:researcher"
description: "Research: {short branch name}"
prompt: |
  ## Your Assignment

  **Topic:** {full research topic}
  **Branch:** {branch name}
  **Question:** {specific sub-question}
  **Write findings to:** {$PROJECT/.craft/research/{topic-slug}/{NN}-{branch-slug}.md}
  **Branch template (read and follow exactly):** {CLAUDE_PLUGIN_ROOT}/commands/references/research-branch-template.md

  Extract findings for this question. Read the branch template first and follow its
  format and producer rules exactly. Write your branch file to the path above. Return
  only your lightweight summary to me.

Assign branch numbers (01, 02, 03...) in the order you decomposed them - order is just a label; the synthesizer re-ranks. Resolve `{CLAUDE_PLUGIN_ROOT}` to the actual plugin path before passing it (so the haiku researcher, which may not inherit the env var, gets a usable path).

**Launch ALL agents simultaneously.** Do not wait for one to finish before launching the next.

**If `DEPTH` is `--quick`:** Still spawn parallel agents, but add to each prompt: "Limit to 3-5 searches. Focus on the top 2-3 most authoritative sources. Be concise."

Step 5: Collect and Build the Manifest

As agents complete, collect their lightweight summaries (branch name, file path, source counts, finding counts, conflict counts). **Do NOT rank, synthesize, or write `_plan.md` yourself** - that is the synthesizer's job, and keeping it out of this main loop is the entire point.

Build a **manifest**: the list of branch file paths you dispatched researchers to write (e.g. `01-foo.md, 02-bar.md, 03-baz.md`). You pass this to the synthesizer so it can detect missing or malformed branches rather than silently synthesizing a partial set.

Step 6: Spawn the Synthesizer

Spawn the **research-synthesizer** agent (once) via the Agent tool. It reads every branch file and writes `_plan.md` + `_sources.md` directly to disk:

subagent_type: "craft:research-synthesizer"
description: "Synthesize: {topic}"
prompt: |
  ## Your Assignment

  **research_folder:** {$PROJECT/.craft/research/{topic-slug}/}
  **manifest:** {comma-separated branch file paths you dispatched, e.g. 01-foo.md, 02-bar.md, 03-baz.md}
  **query:** {original query}
  **topic:** {topic display name}
  **depth:** 1
  **Branch template:** {CLAUDE_PLUGIN_ROOT}/commands/references/research-branch-template.md

  Verify the manifest, read every branch file, and write _plan.md + _sources.md per