Deep research

Contract

Field	Bound contract
Trigger	User asks to research a topic and produce a thorough sourced report.
Authority	Reversible local: writes only ./research/{type}-{topic}-{YYYY-MM-DD}.md (or the optional output-path override) and an optional PDF beside it; rollback is version control or undo. No remote mutation. Spawns 3-20 read-only sub-agents.
Side effect	Writes ./research/{type}-{topic}-{YYYY-MM-DD}.md; optionally exports a PDF beside it. Sub-agents perform read-only web search and page fetch. Output path can be overridden with the optional output-path input.
Done	A prose-first cited Markdown report exists at the output path, containing key findings, strategic recommendations, and risks/uncertainties, with every claim cited.

Inputs

• Topic and research type, supplied by the user or inferred from the prompt. Research types: market, domain, technical, competitive, product, academic, person/org, financial, legal, trend, community. If none fit, infer a type and design a matching axis breakdown.
• Specific questions or goals the research must answer (optional for well-scoped prompts; required for vague prompts).
• Geographic, time, or segment constraints (optional).
• Output path override (optional; default ./research/{type}-{topic}-{YYYY-MM-DD}.md).
• PDF export request (optional).
• Web access is required; if unavailable, halt.

Procedure

1. Get today's date with date +%Y-%m-%d; use it for date-filtered searches and recency references throughout. Done when: today's date is obtained and used for date-filtered searches.
2. Scope. If the prompt is specific and well-scoped (topic, type, and goals clear), infer the research type, state assumptions explicitly in the report header, and proceed. If vague or ambiguous, ask the user one question at a time with 2-4 options: what type, what specific questions or goals, and any geographic/time/segment constraints. Check whether a report on this topic already exists in the output directory; if found, ask whether to extend or start fresh. Set the output path to the supplied output-path override when one is given, otherwise to ./research/{type}-{topic}-{YYYY-MM-DD}.md (lowercase, hyphens). Write the report header now (topic, type, goals, date, assumptions, methodology note). Done when: the output path is set and the report header is written with topic, type, goals, date, assumptions, and methodology note.
3. Core research: parallel fan-out. Spawn 3-20 sub-agents in a single message, one per research axis for the chosen type. Each sub-agent searches its axis on the web, fetches the sources it cites, writes findings as prose paragraphs with inline citations (not bullet lists), and returns URL, accessed date, and a confidence level per claim. Each sub-agent tags every source as Primary (official docs, filings, peer-reviewed), Established (major publications, analyst firms), or Low (blogs, forums, single opinions) and flags Low-tier sources prominently. Sub-agents do not wait for each other. Append each sub-agent's findings to the output file under the matching section heading immediately as it completes. Never batch. Done when: every core-research sub-agent's findings are appended to the output file immediately as completed.
4. Competitive/landscape analysis: parallel fan-out. Spawn 3-5 sub-agents covering the landscape axes for the chosen type with the same citation discipline. Append results immediately. Done when: every landscape sub-agent's findings are appended immediately.
5. Deep dive: parallel fan-out. Spawn sub-agents covering the deep-dive axes for the chosen type. Append results immediately. Done when: every deep-dive sub-agent's findings are appended immediately.
6. Outline refinement (deep mode only, selected when the user says "thorough", "exhaustive", or "comprehensive"). After steps 3-5, review whether evidence warrants restructuring: did findings contradict the initial scope, did an important angle emerge, are any sections underpowered or overloaded. If yes, adapt the outline, run 2-3 targeted gap-fill searches time-boxed to 5 minutes, and record what changed in the methodology note. Skip in quick mode (narrow, time-sensitive: run steps 2 auto-scope, 3, 7) and standard mode (steps 2-5, 7; step 6 is deep-only). Done when: the outline is refined with gap-fill searches run and changes recorded, or the step is skipped per mode.
7. Synthesis. Read the full output file and write the synthesis section: Key Findings (5 critical insights as prose paragraphs, each with a source reference), Strategic Recommendations (3-5 ranked by impact, each with rationale and evidence), Risks and Uncertainties (data gaps, low-confidence claims, unresolvable source conflicts, domain/market risks to monitor), and Next Steps (follow-up research, whether the initial request is fulfilled or needs another scope loop, decisions this research enables). Use extended reasoning here: reconciling conflicting multi-source data and ranking recommendations requires deep inference. Keep the fact/synthesis distinction throughout: "According to [Source], X" for sourced claims; "This suggests Y" for analysis. Done when: the synthesis section contains Key Findings, Strategic Recommendations, Risks and Uncertainties, and Next Steps with the fact/synthesis distinction maintained.
8. Critique pass (deep mode only). Red-team the synthesis: what is missing, what could be wrong, what alternative explanations exist, what biases might be present. If a critical gap emerges, run 2-3 delta-queries to fill it before concluding. Done when: the synthesis is red-teamed with delta-queries run for critical gaps, or the step is skipped per mode.
9. PDF export (optional, only if the user requests it). Check converter availability with which pandoc and which md-to-pdf. Try pandoc first (pandoc <output-path> -o <pdf-path>), then md-to-pdf (md-to-pdf <output-path>). If neither is available, tell the user to install pandoc or md-to-pdf. Done when: the PDF is exported next to the Markdown or the user is told which converter to install, or the step is skipped when no PDF was requested.

Failure and recovery

• No web access: halt immediately and tell the user; do not produce a report.
• Unsourced assertion: a claim without a source URL is a guess, not a finding; remove it or find a source. Never fabricate a citation; if a source does not exist, write "No sources found for X" and flag the gap.
• Critical claim (market size, growth rate, competitive positioning) from a single source: label it confidence:Low or find a second independent source. Do not assert it as established.
• Source conflict: flag it explicitly rather than silently picking one; record it in Risks and Uncertainties if unresolvable.
• Sub-agent returns no findings for its axis: write "No sources found for X" under that section; do not leave it empty or guess.
• Partial result: the output file always reflects whatever has been written so far (write-as-you-go), so a halt mid-run leaves a partial cited report, not a blank file. Rollback is unnecessary; the only mutation is the local report file and optional PDF, both reversible by deletion.

Output

A prose-first cited Markdown report at the resolved output path: the output-path override when supplied, otherwise ./research/{type}-{topic}-{YYYY-MM-DD}.md. The report is at least 80% prose (bullets only for true lists) with sections for scoped findings by axis, Key Findings, Strategic Recommendations, Risks and Uncertainties, and Next Steps. Every claim carries a source URL; critical claims carry 2+ sources or a confidence:Low label. Optionally a PDF beside the Markdown when requested and a converter is available.