Deep Research

Also save the plan with writing to a file on disk so it survives context truncation.

Present the plan to the user and ask them to confirm before proceeding. If the user wants changes, revise the plan first.

2. Scale decision

Never spawn subagents for work you can do in 5 tool calls.

3. Spawn researchers

Launch parallel researcher subagents via the task tool (agent_type: "general-purpose"). Each gets a structured brief with:

• Objective: what to find
• Output format: numbered sources, evidence table, inline source references
• Tool guidance: which search tools to prioritize
• Task boundaries: what NOT to cover (another researcher handles that)
• Task IDs: the specific ledger rows they own and must report back on

Assign each researcher a clearly disjoint dimension — different source types, geographic scopes, time periods, or technical angles. Never duplicate coverage.

{
  tasks: [
    { agent: "researcher", task: "...", output: "<slug>-research-web.md" },
    { agent: "researcher", task: "...", output: "<slug>-research-papers.md" }
  ],
  concurrency: 4,
  failFast: false
}

Researchers write full outputs to files and pass references back — do not have them return full content into your context. Researchers must not silently merge or skip assigned tasks. If something is impossible or redundant, mark the ledger row blocked or superseded with a note.

4. Evaluate and loop

After researchers return, read their output files and critically assess:

• Which plan questions remain unanswered?
• Which answers rest on only one source?
• Are there contradictions needing resolution?
• Is any key angle missing entirely?
• Did every assigned ledger task actually get completed, blocked, or explicitly superseded?

If gaps are significant, spawn another targeted batch of researchers. No fixed cap on rounds — iterate until evidence is sufficient or sources are exhausted.

Update the plan artifact (outputs/.plans/<slug>.md) task ledger, verification log, and decision log after each round. When the work spans multiple rounds, also append a concise chronological entry to CHANGELOG.md covering what changed, what was verified, what remains blocked, and the next recommended step.

Most topics need 1-2 rounds. Stop when additional rounds would not materially change conclusions.

5. Write the report

Once evidence is sufficient, YOU write the full research brief directly. Do not delegate writing to another agent. Read the research files, synthesize the findings, and produce a complete document:

# Title

## Executive Summary
2-3 paragraph overview of key findings.

## Section 1: ...
Detailed findings organized by theme or question.

## Section N: ...

## Open Questions
Unresolved issues, disagreements between sources, gaps in evidence.

When the research includes quantitative data (benchmarks, performance comparisons, trends), generate charts using Mermaid diagram syntax in markdown. Use Mermaid diagrams for architectures and processes. Every visual must have a caption and reference the underlying data.

Before finalizing the draft, do a claim sweep:

• map each critical claim, number, and figure to its supporting source or artifact in the verification log
• downgrade or remove anything that cannot be grounded
• label inferences as inferences
• if code or calculations were involved, record which checks were actually run and which remain unverified

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

6. Cite

Spawn the verifier agent to post-process YOUR draft. The verifier agent adds inline citations, verifies every source URL, and produces the final output:

{ agent: "verifier", task: "Add inline citations to <slug>-draft.md using the research files as source material. Verify every URL.", output: "<slug>-brief.md" }

The verifier agent does not rewrite the report — it only anchors claims to sources and builds the numbered Sources section.

7. Verify

Spawn the reviewer agent against the cited draft. The reviewer checks for:

• Unsupported claims that slipped past citation
• Logical gaps or contradictions between sections
• Single-source claims on critical findings
• Overstated confidence relative to evidence quality

{ agent: "reviewer", task: "Verify <slug>-brief.md — flag any claims that lack sufficient source backing, identify logical gaps, and check that confidence levels match evidence strength. This is a verification pass, not a peer review.", output: "<slug>-verification.md" }

If the reviewer flags FATAL issues, fix them in the brief before delivering. MAJOR issues get noted in the Open Questions section. MINOR issues are accepted. After fixes, run at least one more review-style verification pass if any FATAL issues were found. Do not assume one fix solved everything.

8. Deliver

Copy the final cited and verified output to the appropriate folder:

• Paper-style drafts → papers/
• Everything else → outputs/

Save the final output as <slug>.md (in outputs/ or papers/ per the rule above).

Write a provenance record alongside it as <slug>.provenance.md:

# Provenance: [topic]

- **Date:** [date]
- **Rounds:** [number of researcher rounds]
- **Sources consulted:** [total unique sources across all research files]
- **Sources accepted:** [sources that survived citation verification]
- **Sources rejected:** [dead links, unverifiable, or removed]
- **Verification:** [PASS / PASS WITH NOTES — summary of reviewer findings]
- **Plan:** outputs/.plans/<slug>.md
- **Research files:** [list of intermediate <slug>-research-*.md files]

Background execution

If the user wants unattended execution or the sweep will clearly take a while:

• Launch the full workflow via the task tool with mode: "background"
• Report the async ID and how to check status with the read_agent tool