/research-driven-development

name: research-driven-development
description: Use when the user asks a question about a topic, requests research, or when understanding something is needed before planning. Triggers on "research this", "what is X", "how does Y work", "compare A vs B", "investigate", "deep dive", "look into".

Research-Driven Development

Dispatch parallel research agents, synthesize their findings, and write a persistent research document. Research is not complete until there is a written artifact — verbal answers without documents are prohibited.

**Announce at start:** "I'm using the research-driven-development skill to investigate this topic."

When to Use

• User asks a question about a technology, concept, or approach
• User says "research this", "deep dive", "investigate", "look into"
• User asks "what is X", "how does Y work", "compare A vs B"
• Before planning a non-trivial task that requires understanding first
• When you need to understand something before making a decision

When NOT to Use

• User asks about a specific file in the current codebase (just read it)
• The answer is a single fact you already know with certainty
• User explicitly asks for a quick verbal answer

Iron Law

> **NO RESEARCH WITHOUT A DOCUMENT.** > Every research task produces a written artifact. Verbal answers without persistent documents are prohibited. If you researched it, write it down.

Grounding Rule

> **Every load-bearing claim must be grounded by the verify stage (Step 4) before the document is written.**

Pipeline

Step 0: Scope check (conditional)
Step 1: Create bead + calibrate effort
Step 2: Check existing knowledge
Step 3: Decompose + dispatch parallel research agents
Step 4: Synthesize + verify findings
Step 4.5: Gap-closing round (if needed)
Step 5: Write document
Step 6: End-gate (top-level only) + close bead

Step 0: Scope Check (conditional)

If the question is already specific, **skip this step**. Fire it **only when you cannot name the sources you'd search or the decision the answer informs** — e.g. "research databases" (too vague). Do NOT fire when scope is already present — e.g. "compare Postgres vs SQLite for our embedded Dolt use case". This is disambiguation, not a quality gate — mandatory scope-gating just duplicates what a capable model already does; the "When NOT to Use" list still applies.

When it fires, ask 2–3 clarifying questions via your structured question tool (scope · use-case · the decision it informs), then weave the answers into the research question before Step 1.

Step 1: Create a Bead + Calibrate Effort

bd create "Research: <topic>" -t task -p 2
bd update <id> --claim

**Calibrate effort — the query tier picks the agent count (this is the throttle, not a vibe):**

| Tier | When | Agents | Searches | |------|------|--------|----------| | Simple fact-finding | one factual answer | 0–1 (no decomposition) | ~3–10 | | Comparison / decision | weigh 2+ options | 2–4 sub-questions, one agent each | ~10–15 each | | Complex / open-ended | broad or architectural | up to 10 sub-questions | as needed |

**Hard ceiling: at most 10 parallel agents per round.** `@explore` (Step 3), when dispatched, counts as one of the 10. Verifiers (Step 4) and gap-closing rounds (Step 4.5) are excluded from this cap — their own separate budget. **Concurrency reality:** the harness runs ~min(16, cores−2) agents concurrently, so main researchers + verifiers queue rather than all firing at once — 10 is the per-round design ceiling, not a concurrency promise. Scale effort to the question — do not over-dispatch.

Step 2: Check Existing Knowledge

Before launching new research, search for existing coverage:

# Check beads memories for prior context
bd memories <keyword>

# Query the knowledge-beads — the primary dedup index now (reference-class
# research lives here as deferred `research`-labeled beads, not in the old
# kv store or as a doc-grep)
bd list --label <topic> --status all
bd search "<keywords>" --status all

Read before you verdict: `bd list --label <topic> --status all --flat --long -n 10` prints bodies inline (>10 hits: narrow the query, never triage truncated titles). hits are pointers, not knowledge — a "comprehensive coverage already exists" verdict may only be issued after reading the hit bodies; a verdict from titles alone is not a verdict.

Same lookup researchers run; see the "Search the knowledge base first" step in `./researcher-prompt.md`.

**If comprehensive coverage already exists:** Reference it, add any new findings as updates, and close the bead. Do not duplicate existing research.

Step 3: Decompose + Dispatch Parallel Research Agents

**Decompose first** (skip for the Simple tier): break the topic into **3–6 complementary sub-questions** (for opinion/design topics, 2–3 perspectives) that collectively cover it. Assign **one researcher agent per sub-question** — never hand every agent the raw topic. Launch all agents in a **single message with multiple `Agent` tool calls** so they run concurrently. **Cap: 10 parallel agents (Step 1).**

The delegation contract (every dispatch)

Each agent's brief MUST state all four parts (Anthropic's delegation contract — vague briefs cause duplicated and missed work):

1. **Objective** — the specific sub-question, not the whole topic. 2. **Output format** — structured findings, and a **verbatim supporting quote for every load-bearing claim** (the grounding verifier re-fetches independently; this quote is only the fallback if that re-fetch is inconclusive). 3. **Tools / sources** — which to prefer (official docs over blogs). 4. **Boundaries** — what this agent owns vs. its neighbours, so sub-questions don't overlap.

Add to every brief: **start wide, then narrow** — open with a SHORT broad query, see what's available, then narrow. Never lead with a long, hyper-specific query.

Agent A: Researchers (web + documentation)

Dispatch via the `Agent` tool:

1. `Read` the prompt t