---
name: deep-research
description: Run a thorough, source-heavy investigation on any topic. Use when the user asks for deep research, a comprehensive analysis, an in-depth report, or a multi-source investigation. Produces a cited research brief with provenance tracking.
---

# Deep Research

Execute a source-heavy investigation on a topic and produce a durable, cited brief with a provenance sidecar. This is an **execution skill**, not an explainer — your first actions should be tool calls that create directories and write the plan artifact.

## Do not

- Do not answer by describing the protocol.
- Do not restate or summarize these instructions in chat.
- Do not stop after planning — continue immediately through gathering and drafting.
- Do not ask the user for confirmation unless they explicitly requested plan review.
- Do not end with chat-only output. Every run leaves artifacts on disk.

## Subagent mapping

See `../_platform-mapping.md`. Roles used: `researcher` (evidence gathering), `verifier` (URL + citation verification), `reviewer` (adversarial review). Dispatch via `Task` tool (Claude Code) or `task` tool (OpenCode).

## Required artifacts

Derive a short slug from the topic (lowercase, hyphenated, no filler words, ≤5 words).

Every run must leave these files on disk:

- `outputs/.plans/<slug>.md`
- `outputs/.drafts/<slug>-draft.md`
- `outputs/.drafts/<slug>-cited.md`
- `outputs/<slug>.md` (or `papers/<slug>.md` for paper-style briefs)
- `outputs/<slug>.provenance.md` (or `papers/<slug>.provenance.md`)

If any capability fails, continue in **degraded mode** and still write a blocked/partial final output and provenance sidecar. Set `Verification: BLOCKED` when verification could not complete. Never end with only an explanation in chat.

## Step 1 — Plan

Create `outputs/.plans/<slug>.md` immediately. Required sections:

- **Key questions** — what the brief must answer
- **Evidence needed** — for each question, what kind of source satisfies it
- **Scale decision** — direct-search OR subagent-delegated (see Step 2)
- **Task ledger** — one row per sub-question; status `pending | done | blocked | superseded`
- **Verification log** — critical claims that will need citation verification
- **Decision log** — key calls made during the run

Make the scale decision before assigning owners. For a narrow "what is X" explainer, the plan must use lead-owned direct search only — do not allocate researcher subagents in the task ledger.

After writing the plan, continue immediately. Do not pause for approval.

**Optional cross-session persistence.** If the runtime has a memory primitive (Claude Code `auto-memory`, a `memory_remember` tool, or equivalent), also mirror the plan there under key `deepresearch.<slug>.plan`. If no such primitive exists, continue — the disk file is the canonical copy. See `../_platform-mapping.md`.

## Step 2 — Scale

**Use direct search for:**

- Single fact or narrow question, including "what is X" explainers
- Work you can answer with 3–10 tool calls

For "what is X" explainer topics, **do not spawn researcher subagents** unless the user explicitly asks for comprehensive coverage, current landscape, benchmarks, or production deployment. Don't inflate a simple explainer into a multi-agent survey.

**Use subagents only when decomposition clearly helps:**

- Direct comparison of 2–3 items: 2 `researcher` subagents
- Broad survey or multi-faceted topic: 3–4 `researcher` subagents
- Complex multi-domain research: 4–6 `researcher` subagents

## Step 3 — Gather evidence

**PDF warning.** Avoid crash-prone PDF parsing. Do not fetch `.pdf` URLs unless the user explicitly asked for PDF extraction. Prefer paper metadata, abstracts, HTML pages, official docs, and web snippets. If only a PDF exists, cite its URL from search metadata and mark full-text parsing as blocked.

**If direct search was chosen:**

- Skip subagent spawning entirely.
- Search and fetch sources yourself using `WebSearch` / `WebFetch` (Claude Code) or equivalents.
- Use **at least 3 distinct queries**, covering definition/history, mechanism/formula, and current usage/comparison (when relevant).
- Record the exact search terms used in `<slug>-research-direct.md`.
- Write notes to `<slug>-research-direct.md`.
- Continue to synthesis.

**If subagents were chosen:**

- Write a per-researcher brief first: `outputs/.plans/<slug>-T1.md`, `outputs/.plans/<slug>-T2.md`, etc.
- Keep the subagent dispatch payload small and valid — no multi-paragraph instructions inside the JSON.
- Always set `failFast: false` if your runtime exposes it.
- Do not name exact tool commands in subagent tasks unless those tool names are visible in the current tool set.
- Prefer broad guidance like "use paper search and web search"; if a PDF parser or paper fetch fails, the researcher must continue from metadata, abstracts, and web sources and mark PDF parsing as blocked.

Example Claude Code dispatch shape (conceptual — adapt to the tool's actual schema):

```
Task(
  subagent_type="scholar",
  description="research-web",
  prompt="Read outputs/.plans/<slug>-T1.md and write <slug>-research-web.md"
)
Task(
  subagent_type="scholar",
  description="research-papers",
  prompt="Read outputs/.plans/<slug>-T2.md and write <slug>-research-papers.md"
)
```

Dispatch independent researchers in parallel (single message, multiple tool-use blocks).

After evidence gathering, update the plan ledger and verification log. If research failed, record exactly what failed and proceed with a blocked/partial draft.

## Step 4 — Draft

**Write the report yourself. Do not delegate synthesis.**

Save to `outputs/.drafts/<slug>-draft.md`.

Include:

- Executive summary
- Findings organized by question/theme
- Evidence-backed caveats and disagreements
- Open questions
- No invented sources, results, figures, benchmarks, images, charts, or tables

**Pre-citation sweep of the draft:**

- Every critical claim, number, figure, table, or benchmark must map to a source URL, research note, raw artifact path, or command/script output.
- Remove or downgrade unsupported claims.
- Mark inferences explicitly as inferences.

## Step 5 — Cite

**If direct search / no researcher subagents was chosen:**

- Do citation yourself.
- Verify reachable HTML/doc URLs with `WebFetch` or equivalent.
- Copy or rewrite the draft to `outputs/.drafts/<slug>-cited.md` with inline citations and a Sources section.
- Do not spawn a `verifier` subagent for direct-search runs.

**If researcher subagents were used:**

Run the `verifier` subagent after the draft exists. This is mandatory and must complete before any reviewer runs. Do not run verifier and reviewer in parallel.

Task shape (conceptual):

```
Task(
  subagent_type="oracle",  # or general-purpose with WebFetch
  description="verify-citations",
  prompt="Add inline citations to outputs/.drafts/<slug>-draft.md using the research files as source material. Verify every URL is reachable. Write the complete cited brief to outputs/.drafts/<slug>-cited.md."
)
```

After the verifier returns, confirm on disk that `outputs/.drafts/<slug>-cited.md` exists. If the verifier wrote elsewhere, find and move the cited file into place.

## Step 6 — Review

**If direct search / no researcher subagents was chosen:**

- Review the cited draft yourself.
- Write `<slug>-verification.md` with FATAL / MAJOR / MINOR findings and the checks performed.
- Fix FATAL issues before delivery.
- Do not spawn a `reviewer` subagent for direct-search runs.

**If researcher subagents were used:**

Only after `outputs/.drafts/<slug>-cited.md` exists, run the `reviewer` subagent against it.

Task shape (conceptual):

```
Task(
  subagent_type="general-purpose",
  description="review-cited-draft",
  prompt="Verify outputs/.drafts/<slug>-cited.md. Flag unsupported claims, logical gaps, single-source critical claims, and overstated confidence. This is a verification pass, not a peer review. Write to <slug>-verification.md."
)
```

If the reviewer flags FATAL issues, fix them before delivery and run one more review pass. Note MAJOR issues in Open Questions. Accept MINOR issues.

**Applying reviewer fixes:** small localized edits for 1–3 simple corrections. For section rewrites, table rewrites, or more than 3 substantive fixes, read the cited draft and write a corrected full file to `outputs/.drafts/<slug>-revised.md` — do not issue one giant multi-replacement edit.

The final candidate is `outputs/.drafts/<slug>-revised.md` if it exists; otherwise `outputs/.drafts/<slug>-cited.md`.

## Step 7 — Deliver

Copy the final candidate to:

- `papers/<slug>.md` for paper-style drafts
- `outputs/<slug>.md` for everything else

Write the provenance sidecar next to it:

```markdown
# Provenance: <topic>

- **Date:** YYYY-MM-DD
- **Rounds:** <number of research rounds>
- **Sources consulted:** <count and/or list>
- **Sources accepted:** <count and/or list>
- **Sources rejected:** <dead, unverifiable, or removed>
- **Verification:** PASS | PASS WITH NOTES | BLOCKED
- **Plan:** outputs/.plans/<slug>.md
- **Research files:** <list>
```

Before responding, verify on disk that all required artifacts exist. If verification could not be completed, set `Verification: BLOCKED` or `PASS WITH NOTES` and list the missing checks.

## Final response

Keep it brief: link the final file, the provenance file, and any blocked checks. Do not restate the report.
