Overview
Research a topic across many sources and return a cited, structured synthesis in the conversation. Breadth of angle, depth of cross-reference, and citation discipline are what separate this from a search snippet. Keep output in chat — write a file only when asked.
Five search angles
Cover at least 3 every run; name them in the plan and tag each search.
| Angle | Looks for |
|---|---|
| Official | Primary docs, specs, vendor sources, peer-reviewed papers |
| Comparative | "X vs Y", alternatives, head-to-head analyses |
| Criticism | Limitations, known issues, failure stories |
| Currency | Recent developments, changelogs, trend pieces (include the year in queries) |
| Community | HN, Reddit, blogs, Stack Overflow — signal, not authority |
Modes
| Mode | Trigger | Searches | Output |
|---|---|---|---|
quick |
"quick read on X", low-stakes | 3-5 | One paragraph + 3-5 sources; lighter gates |
| default | standard single-domain topic | 5-10+ | Full synthesis template |
comparison |
"compare X and Y", "pros and cons" | 10-15 | Matrix required at top of report |
landscape |
"survey the landscape of X", broad space | 10+ | Parallel subagents → consensus (PLAYBOOK) |
For opinion-shaped asks ("should I use X?") where you already have a grounded take: answer directly first, then offer to escalate. Ten searches in response to a request for a confident opinion wastes the user's turn.
Workflow — each step gates the next
- Local-first —
rg "<topic>" .and Read the obvious matches before any web search. If local material already covers it, default to UPDATE rather than CREATE. State what you found; "no local hits" is a fine result. - Plan — Post the interpretation, the angles you'll use, and the mode, then start searching. The posted plan is what step 5 measures against.
- Disambiguate (when needed) — For ambiguous proper nouns and acronyms, run one broad search to fix the referent and state it. Ask the user if it's still unclear. When a query centers on a name you recognize from a fast-moving area — AI models, developer tools, anything that shifts within months — the name itself is the thing to verify: search before answering, and include it as the user wrote it in at least one query. Partial background is exactly what makes an out-of-date answer sound authoritative, so familiarity is not a reason to skip the search.
- Search — 5+ searches minimum. Broad → specific → tension ("X criticism", "X vs alternatives") → currency. WebFetch every source you'll cite substantively — a search-results snippet is not a read. Prefer primary > secondary > tertiary. When two sources disagree, carry the disagreement into the report instead of silently picking one.
- Sufficiency gate — Post one line:
searches: N | angles: <list> | full reads: M | gaps: <list>. If a planned section has no material behind it, search again or cut it — don't pad. - Synthesize — Use the template below; adapt section names to the topic. Check the last round of findings against the plan from step 2; when they conflict, revise the Tl;dr rather than burying the conflict lower down.
- Cite-verify — Every cited URL must trace to a page you fetched this run. Walk each non-trivial claim to its source, then restate the user's original question and cut sections that don't serve it.
Synthesis template
# [Topic] — Research Summary
> Interpreted as: [if ambiguity was present]
## Tl;dr
[2-3 sentences answering the original question.] *Confidence: high/med/low — why.*
## Overview / Core Information
Definition, how it works, key concepts. *Confidence: ...*
## Comparison Matrix [REQUIRED when comparing 3+ items, place right after Tl;dr]
| Item | Dimension 1 | Dimension 2 | Notes |
|------|-------------|-------------|-------|
## Trade-offs and Criticism
Limitations, valid criticisms, when not to use this. *Confidence: ...*
## Current Landscape
Recent developments, adoption signal, direction. Note disagreements. *Confidence: ...*
## What we still don't know [when gaps are non-trivial]
- Open question
## Sources [group under sub-headers when >5]
- [Title (YYYY-MM-DD)](url) — what this contributed
Source rules: 8-15+ for a substantive topic; every claim traceable; annotate each source with what it contributed; include publication dates; mix official, industry, and community.
Length: match the report to the question — a default-mode run is roughly one screen of prose plus the source list. Cut any template section the sources don't fill rather than padding it, and offer to expand a section instead of writing it speculatively.
Examples
✅ Good (quick mode, abbreviated — step numbers match the workflow above):
user: quick read on whether Bun is stable enough for a CLI tool
assistant:
[1] No local material. [2] Mode: quick. Angles: Official, Criticism, Currency.
[5] searches: 4 | angles: 3 | full reads: 3 | gaps: Windows support thin
Bun 1.x is stable for single-binary CLIs on macOS and Linux; Windows still
trails on a few Node APIs, so check your dependency list against the compat
table. *Confidence: med — official compat table + two 2026 issue threads; no
Windows production reports found.*
Sources: [bun.sh compat table (2026-06)](url) — API coverage · [GitHub issue (2026-05)](url) — Windows gaps · [HN thread (2026-04)](url) — field reports
❌ Bad: one search for "htmx" → "It's a lightweight JS library, alternative to React, some people like it. Sources: htmx.org" — no local check, no plan, no cross-reference, no confidence label, one source.
✅ Good (disagreement handled): "Source A (official docs, 2026) says the flag defaults on; Source B (widely-cited blog, 2024) says off. The default changed in v3 — B predates it." Both cited, dates carry the resolution.
Full default-mode (htmx) and comparison-mode walkthroughs: references/EXAMPLES.md.
Gotchas
- Fabricated citations are the dominant failure mode. Cite a URL only if you fetched it this run. If a fetch fails, find a reachable equivalent or drop the claim — never reconstruct a plausible-looking URL.
- WebFetch returns boilerplate or nothing on paywalled and JS-rendered pages. That counts as not read. Say so, or search for an accessible mirror; don't backfill from the search snippet and count it toward
full reads. - Top-ranked is not authoritative. SEO content farms and AI-written recaps outrank primary docs on most technical queries. Prefer official docs, .gov/.edu, and peer-reviewed sources for technical claims, and take the publication date from the page itself — search-result dates are often re-index dates.
- Pushback is not evidence. When the user disputes a sourced claim, run another search rather than reversing. Report what the new sources say, including "they still support the original claim."
- Multi-agent landscape runs drift hardest. Each subagent optimizes its own angle, so the consensus pass in step 6 is where the original question gets re-read — not the end.
- Three or more items still need the matrix, even in
quickmode. Prose comparison of 3+ options is unreadable; a five-row matrix costs less space than the paragraphs it replaces. - A stale year in a query silently poisons currency. Put the current year in currency-angle queries — undated results skew years old.
- Summaries reproduce source passages without marking them. When a sentence is the source's wording, quote it and attribute it; otherwise reword in your own indirect speech. One short marked phrase per source is the pattern — the worked example in references/EXAMPLES.md shows it.
Integration
- track-session — for long research projects, save the plan and source list to SESSION_PROGRESS.md so the run is resumable.
- track-roadmap — research informs roadmap decisions; cite the summary in the entry.
- Research informs a decision; it doesn't make one. Reading the codebase is step 1, user preferences come from AskUserQuestion, and the design call stays with the user.
Multi-agent landscape mode, the save-as-note handoff, and troubleshooting: references/PLAYBOOK.md.