• 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"

• 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

• 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?)

• 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)

"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."

1. [specific sub-question 1]
2. [specific sub-question 2]
3. [specific sub-question 3]
4. [up to 6 total]

• [topic 1]
• [topic 2]

• [what would comprehensive coverage look like?]
• [minimum: each sub-question has ≥1 source]

**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.

| Complexity | Max rounds | When to use |
|---|---|---|
| **simple** | 2 | Single-factual question, narrow scope, 1-2 sub-questions. Example: "What is the latest version of Python?" |
| **moderate** | 3 | Multi-faceted question, 3-4 sub-questions, comparison or how-to. Example: "Compare Qdrant vs pgvector for RAG" |
| **complex** | 5 | Broad scope, 5-6 sub-questions, requires deep synthesis across domains. Example: "Comprehensive analysis of the self-hosting vs managed API tradeoff for AI infrastructure" |

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*.

**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**

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.

• Original question and research plan
• Current research state (what's already found)
• Round number
• What's still missing

1. First empty result: Try a broader query or different keywords (synonyms, related terms, different phrasing)
2. Second consecutive empty: Try a fundamentally different angle — different domain, different language, or reframe the sub-question entirely. Inject: "Previous search also returned no results. Try a very different query with different keywords, or broaden your search terms."
3. Third consecutive empty: Move on. This sub-question may not have publicly searchable answers. Document it as a gap in the synthesis rather than burning more rounds on dead-end queries.

• Thin content: landing pages, aggregator stubs, <100 words of substantive text
• Irrelevant: keyword overlap without topical relevance. Use word-boundary matching for topic terms — "port" should not match "transport" or "support"
• Duplicate URLs: already fetched in a previous round
• Non-text: video-only pages, image boards, login walls with no preview

• What facts in this source address a sub-question from the research plan?
• Ignore noise, navigation, ads, boilerplate
• Prefer specific data, statistics, named sources, dates over vague claims
• Record the source URL and title with each extracted fact. Assign each unique source a numbered citation

  [1]

  ,

  [2]

  , etc. on first encounter — reuse the same number for subsequent facts from the same source. This produces cleaner inline citations than full URLs (especially on mobile/messaging platforms) and matches academic/magazine citation style. Deduplicate by URL: the same URL seen twice gets the same number.
• Classify source quality for each source:

  primary

  (official docs, model cards, SEC filings, original papers),

  secondary

  (tech journalism, analyst reports, reviews),

  tertiary

  (Wikipedia, aggregators, forum posts). This tier appears in the final source table and signals evidence strength to the reader.
• Grade each fact's evidence basis as you extract (see below) — you can't tag a report you didn't grade while reading

[LABEL]

[VERIFIED]

[SOURCED]

[REASONED]

[ESTIMATED]

• Lead on

  [VERIFIED]

  /

  [SOURCED]

  . Present

  [REASONED]

  /

  [ESTIMATED]

  claims as indicative ("likely", "suggests", "on these figures") — never as hard fact.
• Use these four exact labels — never an improvised synonym (

  [Official]

  ,

  [Expert]

  ,

  [Consensus]

  → these are

  [SOURCED]

  , or

  [VERIFIED]

  only if independently corroborated).
• Don't restate precision you don't have — a source's "about half" is

  ~50% [SOURCED]

  , not

  50.0%

  .
• Never fabricate to fill a gap — an unanswerable sub-question is a documented gap, not a

  [REASONED]

  guess dressed as fact.

primary

secondary

tertiary

[VERIFIED]

[SOURCED]

[REASONED]

[ESTIMATED]

[SOURCED]

[VERIFIED]

• [what's still missing for round N+1 to target]

Synthesis rules:
- **Deduplicate** — if multiple sources say the same thing, cite the best one (or cite both for corroboration)
- **Resolve contradictions** — if sources disagree, present both with attribution. Do not arbitrate silently.
- **Inline citations** — every factual claim references its source using the numbered citation `[N]` assigned in §3c, matching the source table
- **Evidence basis** — tag each material fact `[VERIFIED]` / `[SOURCED]` / `[REASONED]` / `[ESTIMATED]` (see §3c). A fact becomes `[VERIFIED]` only once ≥2 *independent* sources corroborate it; a single source is `[SOURCED]`. Corroboration during dedup is what promotes `[SOURCED]` → `[VERIFIED]`.
- **Update gap list** — what sub-questions are still unanswered or thin?

evidence.json

references/structured-evidence-format.md

• Forced claim precision (every assertion gets a kind + polarity + snippet)
• Refute polarity requirement surfaced counter-evidence the iterative loop missed
• Source quality tiers revealed evidence-strength gaps (too many tertiary sources)
• Explicit gaps + contradictions sections in the final report
• Full traceability: claim ID → snippet → source URL

references/structured-evidence-format.md

• primary (3× weight): official docs, model cards, SEC filings, API pricing pages, original papers
• secondary (2× weight): tech journalism, analyst reports, benchmark aggregators
• tertiary (1× weight): Reddit, forums, Wikipedia, blog aggregators — useful for refute polarity and real-world anecdotes, but never the sole support for a factual claim if a primary/secondary source exists

• Healthy: ≥30% primary, ≤30% tertiary → proceed
• Acceptable: ≥1 primary for key claims, <50% tertiary → note thin primary coverage as a gap
• Weak: 0 primary, >50% tertiary → flag in Gaps section and attempt to fetch primary sources (official docs, model cards, pricing pages) before finalizing. If primary sources are unavailable, qualify tertiary-sourced claims explicitly ("community reports suggest..." not "X is true")

Given the research plan's success criteria:

• Are all key sub-questions addressed with at least one source?
• Are there significant gaps or unanswered aspects?
• Is the evidence sufficient and corroborated?
• Am I approaching the token budget? (tight context = prioritize synthesis)

Reply YES (stop) or NO (continue) + one-sentence reason.

• All sub-questions have ≥1 source → YES
• Most of the complexity cap used (e.g. round 2 of 2 for simple, round 3 of 3 for moderate) and remaining gaps are minor → YES
• Complexity cap reached (simple=2, moderate=3, complex=5) → YES
• Token budget approaching limit → YES (synthesize with what you have)
• Web search returning diminishing returns (same URLs, no new info) → YES

• Major sub-questions unanswered → NO
• Contradictions unresolved → NO
• Only 1-2 rounds done and topic is broad → NO

Research date: [date] · Rounds: [N] · Sources: [N] · Category: [type]

• List all findings grouped by sub-question
• Include source URLs and keep each finding's evidence-basis tag
• Add note: "This is a raw findings compilation; synthesis was not completed."
• Never output "No information could be gathered" if any sources were fetched — always compile what exists.

execute_code

1. Benchmark the asking price against recent transaction comparables (Cushman & Wakefield, CBRE, Savills, JLL — cap rates + price per tsubo)
2. Model alternative uses (e.g., office as-is vs hotel converted) with full P&L: revenue → operating expenses → NOI
3. Estimate conversion costs (per-tsubo renovation rates, per-room costs)
4. Compute return metrics: NOI yield vs market cap rates, payback period
5. Sensitivity table: 3 revenue scenarios × 3 cost scenarios
6. Break-even analysis: what price/ADR/occupancy achieves market yield?

references/real-estate-investment-analysis.md

references/structured-evidence-format.md

1. Create a vault per

   notebooklm-mode

   at

   <project_folder>/research-<topic>/

2. Save each source as a numbered file in

   sources/

   with verbatim extracts
3. Use

   ingest_source.py

   to write + index atomically
4. After the report, tell the user: "Sources saved to vault at [path]. You can ask follow-up questions grounded in these sources — say 'notebooklm mode' to query the vault."

delegate_task(
  goal="Research [sub-topic] as part of a deep-research project. Run web searches, extract content, and return findings with source URLs and titles.",
  context="You are a research subagent. Topic: [sub-topic]. Sub-questions: [list]. Use web_search and web_extract. Return structured findings with citations.",
  toolsets=["web"]
)

• Only use subagents when sub-topics are genuinely independent
• Collect results from all subagents, then synthesize yourself
• Never delegate the synthesis step — the orchestrator must see all findings
• Subagent summaries are self-reports — verify source URLs exist before citing

• Fetch 3-5 URLs per round (not all 10 search results) to avoid rate-limiting
• If

  web_extract

  fails on a URL, note it and move on — don't retry endlessly
• If

  web_search

  returns no results, apply the progressive empty-search refinement protocol (§3a) — first try broader keywords, then a fundamentally different angle, then move on
• Track fetched URLs across rounds to avoid re-processing

• Skipping the research plan — without sub-questions, the loop has no direction and the stopping check has no baseline. Always plan first.
• Stale year in queries — always inject date grounding. Models default to training-cutoff years.
• Re-fetching same URLs — track analyzed URLs across rounds. Wastes time and tokens.
• Over-searching — most topics converge in 2-3 rounds. Don't pad to the complexity cap if the stopping check says YES at round 1 or 2. The cap is a ceiling, not a target.
• Under-searching — broad topics with 1 round produce shallow reports. If the stopping check says NO, continue.
• No quality filter — including thin/irrelevant sources dilutes the report. Filter before extraction.
• Listing instead of synthesizing — the report should synthesize findings, not list them. Resolve contradictions, identify themes, draw conclusions.
• Missing citations — every factual claim in the final report must have an inline citation — either

  [N]

  matching the source table, or

  (Source: URL, "Title")

  for claims from sources not in the numbered table.
• Missing evidence-basis tags — a material fact with a citation but no

  [VERIFIED]

  /

  [SOURCED]

  /

  [REASONED]

  /

  [ESTIMATED]

  tag is half-graded. Tag it, and include the Evidence key so the tags decode.
• Improvised evidence labels — use only the four canonical tags. A synonym like

  [Official]

  ,

  [Confirmed]

  , or

  [Consensus]

  breaks the discipline; map it to one of the four.
• Overclaiming basis — don't tag a single-source fact

  [VERIFIED]

  , and don't restate precision the source didn't give. When torn between two labels, pick the weaker one.
• Synthesis failure produces nothing — always use the fallback report if synthesis fails. Raw findings > no output.
• Ignoring contradictions — if sources disagree, present both. Don't silently pick one.
• Fabricating sources — never invent URLs, titles, or facts. If a sub-question can't be answered, document it as a gap — never a

  [REASONED]

  guess dressed as a sourced fact.
• No counter-evidence search — only searching for supporting evidence produces biased research. Round 2+ must include at least one counter-evidence query. If none found, say so explicitly.
• Missing gaps/contradictions sections — the report must surface what's unknown and where sources disagree. Omitting these sections hides uncertainty from the reader and signals incomplete research.
• No source quality classification — unclassified sources make it impossible to judge evidence strength. Always tag primary/secondary/tertiary in the source table.
• Tertiary source overreliance — if 0 primary sources and >50% tertiary, the evidence base is weak. Flag it in the Gaps section and attempt to fetch primary sources (official docs, model cards, pricing pages) before finalizing. Tertiary sources are valuable for refute polarity and real-world anecdotes, but should never be the sole support for a factual claim when primary/secondary sources exist. Qualify tertiary-sourced claims: "Community reports suggest..." not "X is true."
• Conflating claims with context — facts about the research subject (claims) vs boundary conditions (scope limits, methodology notes, availability gaps) are different things. Use the writing_context concept from the structured evidence format to separate them.
• Burying the comparison table — the overview/comparison table goes right after the executive summary, not after the detailed analysis. Readers need the at-a-glance picture first; the detailed sections are supporting reasoning. Putting the table last forces readers to scroll through analysis before seeing the answer.
• Subagent synthesis — never delegate the synthesis step. The orchestrator must see all findings to synthesize honestly.
• CBD rents for non-CBD locations — when modeling real estate income, do not apply Marunouchi/Otemachi Grade A office rents (¥70K–100K/tsubo) to secondary locations like Koto-ku. Use submarket-appropriate rents (¥20K–30K/tsubo for mid-tier Koto-ku). This single mistake can inflate projected NOI by 3× and make a bad deal look good.
• Clarification loop — if the user responds to a clarification with more vagueness, do not clarify again. Proceed to research with the best interpretation of intent. At most one clarification round.
• Complexity misclassification — don't classify as "complex" just because the topic sounds impressive. A 6-sub-question plan on a narrow factual topic is "moderate." Complexity is about the breadth of synthesis needed, not the perceived importance of the topic.
• Token budget complacency — the budget check is not a formality. On complex multi-round research with long web extractions, context can fill up before the complexity cap is reached. Summarize aggressively when the budget is tight.