--- description: Run a thorough, source-heavy investigation on a topic and produce a durable research brief with inline citations. args: section: Research Workflows topLevelCli: 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/.md` - `outputs/.drafts/-draft.md` - `outputs/.drafts/-cited.md` - `outputs/.md` or `papers/.md` - `outputs/.provenance.md` or `papers/.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/.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..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. - Write notes to `-research-direct.md`. - Continue to synthesis. If subagents were chosen: - Write a per-researcher brief first, such as `outputs/.plans/-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: ```json { "tasks": [ { "agent": "researcher", "task": "Read outputs/.plans/-T1.md and write -research-web.md.", "output": "-research-web.md" }, { "agent": "researcher", "task": "Read outputs/.plans/-T2.md and write -research-papers.md.", "output": "-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/-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/-draft.md` to `outputs/.drafts/-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: ```json { "agent": "verifier", "task": "Add inline citations to outputs/.drafts/-draft.md using the research files as source material. Verify every URL. Write the complete cited brief to outputs/.drafts/-cited.md.", "output": "outputs/.drafts/-cited.md" } ``` After the verifier returns, verify on disk that `outputs/.drafts/-cited.md` exists. If the verifier wrote elsewhere, find the cited file and move or copy it to `outputs/.drafts/-cited.md`. ## Step 6: Review If direct search/no researcher subagents was chosen: - Review the cited draft yourself. - Write `-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/-cited.md` exists, run the `reviewer` agent against it. Use this shape: ```json { "agent": "reviewer", "task": "Verify outputs/.drafts/-cited.md. Flag unsupported claims, logical gaps, single-source critical claims, and overstated confidence. This is a verification pass, not a peer review.", "output": "-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/-revised.md` instead. The final candidate is `outputs/.drafts/-revised.md` if it exists; otherwise it is `outputs/.drafts/-cited.md`. ## Step 7: Deliver Copy the final candidate to: - `papers/.md` for paper-style drafts - `outputs/.md` for everything else Write provenance next to it as `.provenance.md`: ```markdown # 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/.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.