feynman/prompts/deepresearch.md

description, args, section, topLevelCli

description	args	section	topLevelCli
Run a thorough, source-heavy investigation on a topic and produce a durable research brief with inline citations.	<topic>	Research Workflows	true

Run deep research for: $@

This is an execution request, not a request to explain or implement the workflow instructions. Execute the workflow. Do not answer by describing the protocol, do not explain these instructions, do not restate the protocol, and do not ask for confirmation. Do not stop after planning. Your first actions should be tool calls that create directories and write the plan artifact.

Required Artifacts

Derive a short slug from the topic: lowercase, hyphenated, no filler words, at most 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
• outputs/<slug>.provenance.md or papers/<slug>.provenance.md

If any capability fails, continue in degraded mode and still write a blocked or partial final output and provenance sidecar. Never end with chat-only output. Never end with only an explanation in chat. Use Verification: BLOCKED when verification could not be completed.

Step 1: Plan

Create outputs/.plans/<slug>.md immediately. The plan must include:

• Key questions
• Evidence needed
• Scale decision
• Task ledger
• Verification log
• Decision log

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

Also save the plan with memory_remember using key deepresearch.<slug>.plan if that tool is available. If it is not available, continue without it.

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

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, you MUST NOT spawn researcher subagents unless the user explicitly asks for comprehensive coverage, current landscape, benchmarks, or production deployment. Do not 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

Avoid crash-prone PDF parsing in this workflow. Do not call alpha_get_paper and do not fetch .pdf URLs unless the user explicitly asks for PDF extraction. Prefer paper metadata, abstracts, HTML pages, official docs, and web snippets. If only a PDF exists, cite the PDF URL from search metadata and mark full-text PDF parsing as blocked instead of fetching it.

If direct search was chosen:

• Skip researcher spawning entirely.
• Search and fetch sources yourself.
• Use multiple search terms/angles before drafting. Minimum: 3 distinct queries for direct-mode research, 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, such as outputs/.plans/<slug>-T1.md.
• Keep subagent tool-call JSON small and valid.
• Do not place multi-paragraph instructions inside the subagent JSON.
• Use only supported subagent keys. Do not add extra keys such as artifacts unless the tool schema explicitly exposes them.
• Always set failFast: false.
• Do not name exact tool commands in subagent tasks unless those tool names are visible in the current tool set.
• Prefer broad guidance such as "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 shape:

{
  "tasks": [
    { "agent": "researcher", "task": "Read outputs/.plans/<slug>-T1.md and write <slug>-research-web.md.", "output": "<slug>-research-web.md" },
    { "agent": "researcher", "task": "Read outputs/.plans/<slug>-T2.md and write <slug>-research-papers.md.", "output": "<slug>-research-papers.md" }
  ],
  "concurrency": 4,
  "failFast": false
}

After evidence gathering, update the plan ledger and verification log. If research failed, record exactly what failed and proceed with a blocked or 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

Before citation, sweep 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 as inferences.

Step 5: Cite

If direct search/no researcher subagents was chosen:

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

If researcher subagents were used, run the verifier agent after the draft exists. This step is mandatory and must complete before any reviewer runs. Do not run the verifier and reviewer in the same parallel subagent call.

Use this shape:

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

After the verifier returns, verify on disk that outputs/.drafts/<slug>-cited.md exists. If the verifier wrote elsewhere, find the cited file and move or copy it to outputs/.drafts/<slug>-cited.md.

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 the reviewer subagent for simple direct-search runs.

If researcher subagents were used, only after outputs/.drafts/<slug>-cited.md exists, run the reviewer agent against it.

Use this shape:

{
  "agent": "reviewer",
  "task": "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.",
  "output": "<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.

When applying reviewer fixes, do not issue one giant edit tool call with many replacements. Use small localized edits only 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 instead.

The final candidate is outputs/.drafts/<slug>-revised.md if it exists; otherwise it is 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 provenance next to it as <slug>.provenance.md:

# Provenance: [topic]

- **Date:** [date]
- **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:** [files used]

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 should be brief: link the final file, provenance file, and any blocked checks.