research-driven-development

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 template at ./researcher-prompt.md
2. Use its content as the prompt parameter, appending the sub-question + the four contract parts above + bead context (bead ID, what decision this informs, prior knowledge from bd memories)
3. Use subagent_type: "general-purpose" (do NOT use "researcher" — that built-in agent's system prompt overrides the template)

Agent B: @explore (codebase) — one agent, conditional

Dispatch exactly one @explore agent (subagent_type: "Explore") only when the topic has codebase relevance ("how does X work here", "should we adopt Y"). It counts as one of the 10 and is not decomposed (it's already a broad codebase sweep), but gets the same 4-part contract:

Objective: find existing implementations, patterns, config, tests, and docs related to [topic] in this repo. Output: what exists, where (file:line), and how it relates. Boundaries: codebase only — no web. Report concisely.

Pure codebase question: dispatch only @explore.

Step 4: Synthesize + Verify Findings

After the agents return, you synthesize.

1. Merge findings — combine the sub-question results + codebase findings; merge semantic duplicates.
2. Verify grounding (dispatch the 3-layer stage below) — every load-bearing claim must clear layer 1 + layer 2 (escalating to layer 3 on doubt) before being kept. Tag each surviving load-bearing claim inline with its verified source ([S1]).
3. Assign confidence per finding — high (multiple primary sources agree) / medium (secondary or split) / low (single source / blog / contested), with a one-line rationale.
4. Resolve contradictions, keep the verdict — when sources conflict, determine which is authoritative and recommend. When the conflict is load-bearing, also record both positions in an optional Disagreements note — but never silently average, and never abdicate the call.
5. Identify gaps — list load-bearing claims that rest on a single source or are unresolved (feeds Step 4.5).
6. Extract actionable items — note recommended beads.

Grounding Verify Stage

The verifier's job is narrow — citation soundness, not truth-judgment: does the cited source actually contain a span that entails this claim? It never judges whether the claim is true in some absol