moonlight-lupin/agent-skills/deep-research

Deep Research — Iterative Research Engine

An autonomous, multi-step research engine that performs exhaustive information gathering and synthesis. Unlike a single web_search, this skill implements an iterative loop where the agent plans, searches, extracts, synthesizes, and decides when to stop — producing a cited report with structured evidence, source quality tiers, and explicit gaps/contradictions sections.

See references/structured-evidence-format.md for the evidence.json layer and references/docsgpt-concepts.md for adaptive-depth concept mapping.

When to use

• User asks for "deep research", "research report", "comprehensive analysis"
• User wants a written report on a topic (not just a quick answer)
• Question requires multi-source synthesis with citations
• User says "look into X in depth" or "write a report on X"

When NOT to use

• Entity vetting/dossiers → use entity-research (has sanctions screening, structured lenses)
• Recurring news digests → use news-monitoring (has cron, dedup, multi-language)
• Source-grounded Q&A from collected sources → use notebooklm-mode (has vault + RAG)
• Quick factual question → just use web_search directly
• Single-source extraction → use web_search + web_extract

Architecture

User question
  → Step 0: Clarification (optional — assess if question is too vague)
  → Step 1: Plan (sub-questions, key topics, success criteria, category, language, complexity)
  → Step 2: Date grounding + language anchor
  → Step 3: Iterative loop (max rounds = complexity cap: simple=2, moderate=3, complex=5)
      ├─ 3a: Generate gap-driven queries (incl. refute queries from round 2+, empty-search refinement)
      ├─ 3b: Search (web_search) + fetch (web_extract)
      ├─ 3c: Quality filter + extraction + source quality classification + numbered citations
      ├─ 3d: Synthesize into cumulative research state (with token budget check)
      ├─ 3e: Structured evidence (optional: evidence.json for 5+ sources)
      └─ 3f: Stopping check (LLM evaluates coverage + token budget)
  → Step 4: Final report (overview-first structure, see template)
  → Step 5: Stats summary

Report output order (overview-first): Executive Summary → comparison/overview table → detailed analysis per sub-question → contradictions → gaps → conclusion → source table. Readers get the answer and the at-a-glance comparison before the detailed reasoning.

Step 0 — Clarification (optional)

Before planning, assess whether the question is specific enough to research productively. This step prevents wasting rounds on a question that's too vague.

When to clarify:

• The question is 1-5 words with no scope ("research AI", "tell me about quantum computing")
• The question could mean very different things depending on intent ("is X good?" — good for what? for whom?)
• The question lacks a clear angle ("look into climate change" — scientific? policy? economic?)

When NOT to clarify:

• The question already has sub-questions or specific parameters
• The user explicitly says "just research it" or "don't ask, just go"
• The question is specific enough to generate productive search queries immediately
• The question is a simple factual lookup ("what is the latest version of X?", "when did Y happen?") — even if short, if the intent is clear, proceed
• The user is responding to a prior clarification (don't loop)

How: Present 1-3 short questions to the user that would narrow the scope. Keep it brief — this is a scope check, not an interview:

"Before I start researching, I'd like to clarify:

1. [narrowing question 1]

2. [narrowing question 2]

Please provide these details and I'll begin."

If the question is already specific, skip this step entirely and proceed to Step 1.

Step 1 — Research Plan

Before searching, break the question into a research plan. Output:

## Research Plan
Question: [user's question]
Date: [current date]
Language: [BCP 47 tag — e.g. en, zh-Hans, ja. Detect from query; user's explicit language preference overrides. Use consistently throughout the report.]
 
Sub-questions:
1. [specific sub-question 1]
2. [specific sub-question 2]
3. [specific sub-question 3]
4. [up to 6 total]
 
Key topics:
- [topic 1]
- [topic 2]
 
Success criteria:
- [what would comprehensive coverage look like?]
- [minimum: each sub-question has ≥1 source]
 
Report category: [factual | comparison | product | how-to | fact-check | explainer]
 
Complexity: [simple | moderate | complex]

Complexity assessment and adaptive depth: Classify the question's complexity to determine the maximum number of research rounds. This prevents over-searching simple questions and under-searching complex ones.

The complexity cap is a maximum, not a target. The stopping check (Step 3f) still governs early termination. A simple question that finds comprehensive answers in 1 round should stop at 1 — the cap of 2 means it can go to 2 if needed, not that it must.

Search budget (adapted from upstream research-input.ts presets + estimateMaxSearches): announce the budget in the plan — "Search budget: ≤N queries", N = per-round breadth × max rounds (script: estimate-budget --breadth B --rounds R). When round 2+ runs deep-dive chains (§3a), the upper bound is tree-mode: estimate-budget --breadth B --rounds R --halving, upstream's breadth-halving recursion. The budget is a ceiling the loop must not exceed; prefer the cheapest round that answers well, per the §3f stopping check.

Language anchoring: Detect the output language from the query and normalize to a BCP 47 tag (e.g. en, zh-Hans, zh-Hant, ja). Use it consistently throughout — executive summary, analysis, contradictions, gaps, conclusion. Source titles, URLs, proper nouns, and code may stay in their original language; search queries may use any language that helps evidence gathering. If the user explicitly switches language mid-research, update the anchor and use the new language for all subsequent output.

Report category detection:

• "vs", "compare", "better than" → comparison
• "best", "top", "recommend", "buy" → product
• "how to", "guide", "steps" → how-to
• "is it true", "verify", "fact check" → fact-check
• "what is", "explain", "overview" → explainer
• default → factual

Step 2 — Date Grounding

Inject the current date before any search. This is mandatory — LLMs default to training-cutoff years, producing stale queries.

Today's date is {current date as "DD Month YYYY"}. When a search query needs a year or refers to "latest"/"current"/"this year", use {current year} or relative wording — never a year inferred from training data.

Step 3 — Iterative Loop

Round structure

Each round follows: Query → Search → Extract → Synthesize → Check Stop

Run max N rounds where N = complexity cap from Step 1 (simple=2, moderate=3, complex=5). Most topics converge in 2-3 rounds. The cap is a ceiling, not a target.

Query rules, fetch budgets, quote anchoring, the synthesis template, the evidence store, and stop conditions are in references/step3-iterative-loop.md.

1. 3a — Query Generation (gap-driven) — Breadth comes from the Step 1 preset (simple=2, moderate=3, complex=4). Round 1 targets plan sub-questions; later rounds target gaps and recorded follow-ups.
2. 3b — Search and Fetch — Use the donsetch MCP search/fetch tools when the user asked for them; otherwise web_search / web_extract. Never abort over a provider preference.
3. 3b.1 — Evidence Persistence (mandatory for 5+ source reports) — From round 1, persist with init-run, register-source, add-claim, add-evidence, and check-quote on scripts/research_validation.py.
4. 3c — Quality Filter and Extraction — Discard low-quality results before extracting.
5. Verbatim snippet anchoring (mandatory for claims you store) — Every stored claim carries a verbatim contiguous excerpt from that source's page text.
6. Evidence basis — the four-label discipline — Tag every material fact with the basis you are asserting it on.
7. 3d — Synthesis — Fold this round's extractions into the cumulative research state.
8. 3e — Structured Evidence (recommended for reports with 5+ sources) — Write the evidence.json intermediate before the final report. Format: references/structured-evidence-format.md.
9. 3f — Stopping Check — After synthesis, decide whether the report is comprehensive enough. Otherwise open another round, up to the cap.

Step 4 — Final Report

Produce the final report. Minimum 800 words (scale with topic complexity).

Output order is overview-first: the reader gets the answer and the at-a-glance comparison before the detailed reasoning. Do not bury the comparison table after the per-topic analysis.

Carry each material fact's evidence-basis tag inline (§3c), lead on [VERIFIED] / [SOURCED], keep [REASONED] / [ESTIMATED] claims framed as indicative, and paste the Evidence key legend below the Sources table so the tags decode.

Synthesis prompt structure: When writing the final report, explicitly consult: (1) the original question, (2) the research plan (sub-questions, success criteria), (3) the cumulative research state from all rounds, (4) the evidence.json if produced, and (5) the numbered source list. Do not rely on the cumulative state alone if it has been compressed across many rounds — go back to the per-round findings to verify key claims. This prevents detail loss when the research state was aggressively summarized due to token budget pressure.

Structure

# [Report Title]
 
> **Research date:** [date] · **Rounds:** [N] · **Sources:** [N] · **Category:** [type]
 
## Executive Summary
[2-3 paragraph overview of key findings — the answer up front. If using structured evidence, note claim count and refute count here so the reader knows the evidence base.]
 
## [Comparison Table | Overview | Key Findings at a Glance]
[For comparison reports: a markdown table comparing options/entities across criteria. For factual/explainer reports: a numbered list of key findings with claim references. This section gives the reader the complete picture in one screen — the detailed analysis below is the supporting reasoning, not the main event. If using structured evidence, cite claim IDs like [c1], [c3] in table cells or list items.]
 
## [## Section per sub-question]
[Detailed analysis with inline citations — this is the supporting reasoning for the overview above. Each section traces back to the overview claims.]
 
### [### Subsections as needed]
[...]
 
## Contradictions
[If sources disagree, present both sides with attribution. Do not silently arbitrate. If no contradictions found, state "No direct contradictions between sources." This section is REQUIRED — its absence is a quality signal that counter-evidence wasn't searched.]