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 absolute sense, only whether the cited source backs it up. This stage is universal — every tier, including Simple (one cheap verifier for a single-fact claim closes the grounding gap without a special case).

Load-bearing heuristic: a claim is load-bearing if a recommendation, decision, or comparison in the document rests on it. Non-load-bearing color/context claims are not verified.

Dedup semantically-equivalent claims first, then verify the top-K load-bearing claims; if more exist, log which were not independently verified — a visible note, never a silent truncation.

Layer 1 — deterministic pre-filter (no LLM, always runs, all tiers):

• Every load-bearing claim carries a source tag → else flag ungrounded.
• The cited URL resolves (HTTP check, e.g. WebFetch or a HEAD request) → else flag as a possibly-fabricated source.

Layer 2 — blinded verifier (fast/cheap model; entailment only; default 1 verifier per claim): for each load-bearing claim that passed layer 1, dispatch one fresh-context verifier:

1. Read the prompt template at ./verifier-prompt.md.
2. Fill in only the claim text and the cited URL — no author, no framing that this is "our" research (the blinding kills self-preference bias).
3. Dispatch via the Agent tool: subagent_type: "general-purpose", using a fast/cheap model.
4. Collect its three-way verdict: { verdict: SUPPORTED | UNSUPPORTED | INCONCLUSIVE, supporting_span, confidence, reason }.

Layer 3 — escalate on doubt (not always-on): a clean SUPPORTED verdict with a verbatim span is accepted immediately — no escalation. Only on UNSUPPORTED / INCONCLUSIVE / low-confidence, escalate that single claim: first to a 3-way fast/cheap-model ensemble (majority verdict, same ./verifier-prompt.md template); if still split, to one fresh blinded stronger-model verifier (same template, same blinding/re-fetch contract) whose verdict is final — keeping the grounding chain independent of the author model end-to-end. Verifiers and escalations are excluded from the 10-cap — their own budget, separate from the main research fan-out (~1 verifier per load-bearing claim; 3-way only when contested).

Verdict handling:

• SUPPORTED → keep the claim, tagged with its verified span/source.
• UNSUPPORTED → the source doesn't actually support the claim → feeds Step 4.5.
• INCONCLUSIVE → never drop the claim for a fetch failure. Retry once / follow one redirect / fall back to the researcher's original quote; if still unreadable, keep the claim but flag it "source unverifiable" with lowered confidence, and feed it to Step 4.5 for a better source.

Step 4.5: Gap-Closing Round (if needed)

If Step 4 surfaced load-bearing claims resting on a single source, unresolved, or UNSUPPORTED / unresolved-INCONCLUSIVE from the grounding verify stage, dispatch one narrow follow-up round of 1–2 targeted agents aimed only at those gaps (not a second full fan-out) to find a legitimate supporting source, then re-synthesize and re-verify. Cap: 1–2 rounds total. Record each: bd note <id> "reflection round N: chasing <gaps>". If a claim still can't be grounded after this round, remove it from the findings and revise any recommendation resting on it — never leave it dangling; record the drop in the document's Refuted / Discarded Claims section with the reason. If no gaps, skip.

Step 5: Write the Document

Research documents are written to .internal/research/ — the project-local, gitignored knowledge base. Not configurable.

Filename: YYYY-MM-DD-<topic-slug>.md

Write the document using the structure in ./document-template.md (read it now).

Create the Research Knowledge-Bead

Creating the knowledge-bead is part of this step, not a separate one — it happens the moment the document is written, never deferred to later.

Secret/PII scan first: before creating the bead, scan the one-line summary and the doc path for secrets or PII (tokens, keys, credentials, personal data) — same discipline as the kv migration engine and memory-curator. If either looks like a secret, flag it and skip bead creation. Never write a secret/token/PII into a bead description or metadata: bead descriptions are queryable and ride Dolt history, which outlives bd forget.

printf '%s' "<distilled 0.5-2.5KB summary: what the research established, key evidence, verdicts>" | \
bd create "<one-line summary of the research>" -t research -l kb,<1-3 topic labels from scripts/kb-label-vocab.txt> \
  --defer 2099-01-01 --metadata "$(jq -nc --arg d "<docpath>" '{doc:$d}')" --body-file - --silent

The description carries the distilled findings — a reader should act on it without opening the doc.

Labels: kb plus 1–3 topics from the controlled vocabulary (scripts/kb-label-vocab.txt) — the guard requires at least one topic label, at most three, and every label present in the vocab.

Quality Checklist

Before writing — and again as a self-grade before closing, running one Step-4.5 round if any axis fails — verify your document passes these checks:

• Summary exists and is 2-3 sentences (not a paragraph)
• Every finding has evidence and citation soundness — no unsourced claims, and each load-bearing claim's source actually supports it, confirmed by the grounding verify stage's independent re-fetch (Step 4) — the Step 3 quote is only the fallback
• Factual accuracy — claims match their sources
• Sources section has 3+ entries with URLs (not "various sources"), including ≥1 primary/official source for each load-bearing claim
• Dates and versions noted for time-sensitive information
• Contradictions resolved — if sources disagreed, which is right and why
• Codebase context included — what exists now, not just what the web says
• Completeness — every sub-question answered
• Recommendations are actionable — "do X" not "consider doing X"
• Effort efficiency — agent count matched the query tier (no over-dispatch)

Step 6: End-Gate + Close the Bead

You are top-level unless the caller passed a nested marker — that's caller-declared, and the default is top-level (the no-signal case is a direct user research request).

Nested mode: skip the end-gate — return your findings to the caller.

Top-level mode: present the end-gate using your structured question tool. Three options:

1. Start brainstorming — invoke Skill(beads-superpowers:brainstorming), passing the research document path as design input.
2. Do further research — run another round (Step 3 fan-out or a Step 4.5 gap-closing round).
3. Accept & close the bead — continue below.

Capture what you learned. At close, record durable, evidence-backed insights (still true next month, tied to a file, test, or command). Never record guesses, one-offs, or secrets (tokens, keys, PII — every memory is injected into all future sessions). Update in place (bd remember --key <key>) rather than adding a near-duplicate.

bd remember "<kind>: <durable, evidence-backed insight>"   # kind: lesson / pattern / design / root-cause / research

bd close <id> --reason "Research complete: <1-line summary of finding>"

If research revealed follow-up work, create the recommended beads — stamp each per Agent-Filed Bead Discipline (beads-superpowers:verification-before-completion):

bd create "Follow-up: <title>" -t task -p <priority> --notes "Severity: <Critical|Important|Minor>
Confidence: <Confirmed|Speculative>
Evidence: <file:line / source / repro | none>"

Red Flags / Anti-Rationalization

Thought	Reality
"I already know the answer"	You might be wrong. Check sources. The document is for future sessions too.
"This is a simple question, I'll just answer verbally"	Iron Law: NO RESEARCH WITHOUT A DOCUMENT. Write it down.
"I'll skip the codebase search — this is a general topic"	The codebase might already have an implementation. Always check.
"I'll write the document later"	You won't. Write it now while the research is fresh.
"One source is enough"	Cross-reference across 3+ independent sources. Single-source findings get flagged.
"I'll skip the knowledge base check"	You might duplicate existing research. Always search first.
"The first pass answered it"	First passes miss the non-obvious. Run the Step-4 gap check.
"The source is about the right topic"	Topical ≠ supporting. The verify stage re-fetches the source independently and checks for a verbatim entailing span — don't rely on topical similarity.
"I'll hand the agents the whole topic"	Decompose. Give each agent one bounded sub-question + the 4-part contract.
"This needs 20 agents"	Cap at 10. Scale effort to the query tier.
"The cheaper recommendation is fine to default to"	Any recommendation that advises a shortcut, descope, material-risk trade-off, or security regression must be flagged as such — never the default path (Production-Grade Doctrine).

Example

User asks: "How does Dolt handle merge conflicts?"

1. bd create "Research: Dolt merge conflict handling" -t task -p 2
2. bd memories "dolt merge" → check for prior research
3. Dispatch researcher (via ./researcher-prompt.md): "Research Dolt merge conflict resolution..."
   Dispatch @explore: "Search codebase for Dolt merge, conflict..."
4. Synthesize: researcher found cell-level merge docs, explore found bd dolt pull usage
5. Write to .internal/research/2026-05-01-dolt-merge-conflict-handling.md
5a. Secret/PII scan the summary, then create the knowledge-bead:
    printf '%s' "Dolt uses cell-level 3-way merge on SQL tables: conflicts are detected per cell, not via line-based diff, so there are no textual conflict markers. This repo already exercises the merge path via bd dolt pull/push (see the doc for the full write-up)." | \
    bd create "Dolt uses cell-level 3-way merge on SQL tables (no textual conflict markers)" -t research -l kb,rdd,beads-tooling --defer 2099-01-01 --metadata '{"doc":".internal/research/2026-05-01-dolt-merge-conflict-handling.md"}' --body-file - --silent
6. bd close <id> --reason "Research complete: Dolt uses cell-level merge on SQL tables"

Integration

Invoked by: User on-demand, or during the research phase before planning. No other skill invokes this directly.

Invokes: brainstorming (via the top-level end-gate). Also dispatches @researcher and @explore agents in parallel internally.