/craft-research

name: research
description: "Ad-hoc research command. Parallel researcher agents investigate sub-questions, write branch files to disk, orchestrator ranks and synthesizes. Resumable across sessions."
argument-hint: "[query | topic-slug | continue | --quick | --deep]"

Research

Ad-hoc research tool. Not part of the craft pipeline - use it whenever you want to understand something. Phase 1 produces comprehensive research most users never need to go beyond. Phase 2 is the optional "go deeper" layer.

Project Root

Use `$CRAFT_PROJECT_ROOT` (set at session start) as the base path for all `.craft/` references. If not set, resolve by walking up from PWD to find the nearest `.craft/.global-state`.

**Cold fallback (uninitialized project):** if neither resolves, anchor to the git toplevel (`git rev-parse --show-toplevel`) when in a repo, else PWD - never a subdirectory. Research runs fine before `/craft:init`; artifacts land under the repo-root `.craft/research/`, not wherever the shell happens to sit.

Set `PROJECT` to the resolved root - env var, then walk-up, then git toplevel, then PWD, in that order. Never default to bare `.`.

Flow

Step 0: Determine Invocation Mode

Parse args to determine routing:

**Mode A - New research query:** Args contain a natural language query (not a known topic slug or "continue"). → Jump to **Step 2** (Discover).

**Mode B - Existing topic slug:** Args match an existing folder name in `$PROJECT/.craft/research/`. → Jump to **Step 1b** (Browse Topic).

**Mode C - "continue" keyword:** Args are exactly `continue`. → Jump to **Step 1c** (Resume).

**Mode D - Quick flags:** Args contain `--quick` or `--deep` or `--exhaustive` after the query. → Extract the query and depth flag. Jump to **Step 2** with depth preset.

**Mode E - No args:** Jump to **Step 1** (Dashboard).

Step 1: Research Dashboard

List existing research topics and their status.

Use **Glob** with pattern `$PROJECT/.craft/research/*/_plan.md` to find all research topics.

For each topic found:

• Use **Read** with `limit: 20` to extract frontmatter (query, date, status, depth)
• Check staleness: if `stale_after` exists and is past today's date, mark as `STALE`
• Check for pending elaboration: look for branch files with `status: complete` in frontmatter vs branches in `_plan.md`

**If no research exists:** > "No research yet. What would you like to research?" > > [Wait for user input, then jump to **Step 2**]

**If research exists:**

Use **AskUserQuestion**:

question: "You have [N] research topics. What would you like to do?"
header: "Research"
options:
  - label: "Start new research"
    description: "Research a new topic from scratch"
  - label: "Browse existing"
    description: "[list: topic1 (complete), topic2 (STALE), topic3 (depth 1 - can go deeper)]"
  - label: "Go deeper on existing"
    description: "Pick a topic and elaborate on specific branches"
    → only show if any topics have branch files eligible for Phase 2

**If "Start new research"** → Ask "What would you like to research?", then jump to **Step 2**. **If "Browse existing"** → Jump to **Step 1b** with topic picker. **If "Go deeper"** → Jump to **Step 1b** with intent to elaborate. **If user provides custom text** → Treat as a new research query, jump to **Step 2**.

Step 1b: Browse Topic

If multiple topics, use **AskUserQuestion** to pick one. If already selected (from Mode B), skip the picker.

Use **Read** to read the topic's `_plan.md`. Display the ranked overview to the user.

Use **AskUserQuestion**:

question: "What would you like to do with this research?"
header: "Topic"
options:
  - label: "Go deeper on a branch"
    description: "Pick a branch to elaborate further (Phase 2)"
  - label: "Verify findings"
    description: "Challenge claims against independent primary sources (runs /craft:research-verify)"
  - label: "Crystallize into an expert"
    description: "Create a reusable expert agent from this research"
  - label: "Re-research (refresh)"
    description: "This topic may be stale - run fresh research"
  - label: "Done browsing"
    description: "Back to what I was doing"

**If "Go deeper"** → Show ranked branches from `_plan.md`, let user pick one or more. Jump to **Step 4** (Deeper Research). **If "Verify findings"** → Invoke `/craft:research-verify {topic-slug}`. **If "Crystallize"** → Jump to **Step 6** (Crystallize Expert). **If "Re-research"** → Jump to **Step 2** with the original query from the topic's frontmatter. Existing folder gets archived to `{slug}--archived-{date}/`. **If "Done"** → End. **If custom text** → Treat as clarification or new query in context of this topic.

Step 1c: Resume In-Progress

Use **Glob** to find topics where `_plan.md` has `status: in-progress`.

If one topic → auto-select it. Check what phase it's in based on which files exist. If multiple → use **AskUserQuestion** to pick which topic to continue.

Resume from where it left off based on which files exist:

• **Branch files missing or incomplete** (no `status: complete`) → re-spawn those researcher agents (Step 2.2).
• **All branch files complete but `_plan.md` is still a stub / `status: in-progress`** → the run was interrupted before synthesis. Build the manifest from the existing branch files and spawn the synthesizer (Step 2.4). Do NOT synthesize in the main loop.

---

Step 2: Discover (Phase 1) - The Main Research

**This is the primary research product.** Most users stop here. The output should be comprehensive and valuable on its own.

2.1: Create Research Folder

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...

2.2: Decompose and Dispatch

Break the query into 3-5 sub-questions that cover the topi