deep-research

Deep Research

Orchestrate parallel research sub-agents, then write one coherent cited report. Research is parallel; writing is single-point — never let multiple agents write report sections.

Step 0 — Always first

1. Run date +%Y-%m-%d via Bash. Never assume the current year from training data.
2. Triage:
   • Answerable with 1-2 searches? → STOP, just use WebSearch directly. Do not use this skill.
   • Enumeration task (N items × M fields, e.g. "compare 20 frameworks")? → still this skill, but use table-oriented decomposition (one sub-agent per item batch).
   • Open-ended investigation? → continue below.
3. Pick depth (default standard; user can override with words like "quick"/"exhaustive"):

Mode	Sub-agents (round 1)	Max follow-up rounds	Sources target
quick	2-3	0	8+
standard	3-5	1	15+
deep	5-8	2	25+

These are hard budgets. Reflection (Phase 4) can spend them but never exceed them.

Workspace

All state lives on disk at ./research/<slug>/ — never only in context (survives compaction):

research/<slug>/
├── brief.md         # research brief — the single contract for all phases
├── findings/        # F1.md, F2.md ... one per sub-agent, structured evidence
└── REPORT.md        # final deliverable

On resume: re-read brief.md + list findings/, skip completed angles, continue.

Phase 1 — Scope

Ask at most one round of clarifying questions (AskUserQuestion), only if genuinely ambiguous: audience, time frame, region, decision at stake. If the user said "just run it" or intent is clear, skip asking and write assumptions into the brief instead.

Then write brief.md: refined question, scope boundaries (in/out), assumptions, depth mode, today's date. This brief — not the raw conversation — is what every later phase measures against.

Phase 2 — Plan

Decompose the brief into 3-8 independent research angles. Pull from these lenses as applicable: core facts/definitions · recent developments (last 12 months) · quantitative data/benchmarks · counter-arguments & failure cases · practitioner experience (forums, issues) · academic work · key players/alternatives.

List angles in brief.md under ## Angles. For deep mode or contested topics, show the angle list to the user for a quick confirm before spending budget.

Phase 3 — Parallel research

Spawn one sub-agent per angle in a single message (parallel). Build each prompt from the locked template in reference/subagent-prompt.md — reproduce it verbatim, replacing only the {variables}. Each sub-agent:

• researches ONE angle only, using WebSearch/WebFetch and the free endpoints in reference/sources.md
• writes structured findings to findings/F<n>.md (claim / quote / URL / date / confidence per item)
• returns only a 3-5 line summary to you — raw page content must never enter your context

If a sub-agent fails or returns thin results, note it and move on; do not block other angles.

Phase 4 — Reflect (gap check)

Read all findings/*.md. Against brief.md, ask: which parts of the brief have no evidence? Which major claims rest on a single source? Where do sources conflict?

• Gaps found AND follow-up budget remains → spawn targeted sub-agents with delta-queries (same template, narrower angle). Repeat once per remaining round.
• No budget left or coverage sufficient → proceed. Record unresolved gaps; they go in the report's "Open questions".

Phase 5 — Write (single-point)

You alone write REPORT.md in one pass, following reference/report.md. Core rules:

• Every non-obvious claim carries an inline citation [n] mapping to a Sources section; citation URLs come only from findings files — never from memory.
• Where sources conflict, present both sides with dates; prefer newer + primary sources.
• Mark single-source claims with [single source], speculation with [speculative].
• End with: Open questions · Sources (numbered, with access date).

For deep mode, before finalizing do one critique pass: reread the report as a skeptical reviewer (unsupported claims? stale data? missing counter-view?) and fix in place.

Finally, give the user a 5-10 line summary of key conclusions and the report path.