| name | research |
| description | Research a topic, technology, library, or decision using the strongest search tool available in the session. Use when asked to "research X", "compare X vs Y", "find the best library/tool for X", "what's the latest on X", "how does <external service or API> work", or whenever an answer depends on external facts (versions, APIs, pricing, benchmarks, best practices) that must be current and cited rather than recalled from memory. Prefers specialized MCP search tools over generic web search and always ends by producing a complete, verified, cited research report. |
Research
Goal: turn a question into a current, verified, cited answer. Model memory
has a training cutoff and no sources — never answer a time-sensitive or
external-fact question from memory alone.
When to use
- "Research X", "compare X vs Y", "what's the best library for X?".
- Choosing a dependency, API, service, or architecture that external facts decide.
- Anything where "latest", "current", version numbers, pricing, or dates matter.
- A pipeline stage (
spec, plan) hits an open question only the outside world
can answer.
Not for questions the repo itself answers — use explore-source / code search
for those.
Step 1 — Frame the question
Before any search, pin down (ask the user only if the answer changes the work):
- Decision: what will this research be used for? Research feeding "pick a
library" needs comparison criteria; "how does this API work" needs docs.
- Freshness: does it need this week's state (releases, pricing) or stable
knowledge (algorithms, standards)?
- Depth: quick answer, comparison table, or deep report? Match effort to it.
Step 2 — Pick the strongest search tool available
Inventory the session's tools first — list what's actually connected (MCP
servers, built-ins) instead of defaulting to the generic web search. Then pick
the highest rung available on this ladder:
- Specialized search MCP — e.g. Exa, Perplexity, Tavily, Brave/Kagi
Search, Firecrawl. These return richer, fresher, less SEO-polluted results
than generic search; if one is connected, it is the default for open-web
questions.
- Domain-specific MCP when the question has a domain — library/API docs:
Context7, DeepWiki; repos/issues/PRs: a GitHub MCP; internal knowledge:
Notion/Confluence/Slack MCPs. A docs tool beats web search for "how do I use
library X" every time.
- Built-in web search + URL fetch — the fallback when no MCP search is
connected. Still fine; just expect more noise.
- Browser automation — last resort, only for pages that need JS rendering
or a login the fetch tools can't handle.
Practicalities:
- If the harness defers/lazy-loads tools, load everything you expect to
need in one batch (search + fetch + docs), not one at a time.
- If no search tool is available, say so explicitly and answer from memory
with a clear caveat: state your knowledge cutoff and mark every claim
(unverified — no search tool available). Never present memory as research.
Step 3 — Search wide, then deep
- Run 2–4 query angles, not one: the direct question, the comparison form
("X vs Y"), the problem form ("how to "), and the authority form
(
<library> changelog, site:docs.<vendor>.com).
- Query in English unless the topic is region-specific — coverage is far
better. Answer in the user's language.
- For freshness-critical topics, include the current year in at least one query
and check result dates.
- For a big research task (many subtopics, "deep dive"), delegate the fan-out
to subagents if the agent supports them: one subagent per angle, each
returning conclusions + source URLs, never raw page dumps. Synthesize and
verify in the main thread yourself. If the platform can't spawn subagents,
do the same fan-out inline in the main thread (
../WORKFLOW.md →
In-stage subagents — delegation is an optimization, never a precondition).
Step 4 — Read primary sources, not snippets
- Fetch and read the pages behind the top results — search snippets truncate
and mislead. 3–5 good sources beat 20 skimmed ones.
- Prefer primary sources: official docs, changelogs/release notes, the
repo's README/issues, specs, vendor pricing pages — over blog posts and
aggregator listicles.
- Record for each source: URL, publish/last-updated date, and the exact
version numbers or figures it states.
Step 5 — Verify before you conclude
- Every load-bearing claim needs ≥2 independent sources, or 1 primary
source. A claim repeated by ten blogs that all cite the same post counts
as one source.
- Watch for staleness: a 2-year-old "best X" post may predate the current
major version. When sources conflict, the newer primary source wins — and
say the conflict existed.
- Anything that fails verification is reported as
(unverified), not silently
dropped or asserted.
Step 6 — Write the report
Research is not done until it ends in a complete report — a standalone
document a reader who wasn't in the chat can rely on. Write it to
docs/research/<YYYY-MM-DD>-<slug>.md (date and time from date). The one
exception: a trivial single-fact lookup ("what's the latest version of X?")
may deliver the full report structure inline in the chat instead of a file.
---
doc: research
question: <the original question, verbatim>
updated: <YYYY-MM-DD HH:MM +TZ>
tools: <search tools actually used>
---
# <Title — the question answered as a statement>
## TL;DR
<the answer + recommendation in 2–4 sentences>
## Scope & decision context
<what was asked, what decision this feeds, what was in/out of scope>
## Method
<query angles run, tools used, why these sources were trusted>
## Findings
### <subtopic or criterion>
<claims in prose, each with an inline citation [n] into Sources>
## Comparison <!-- only when the question was a comparison -->
| Option | <criterion> | <criterion> | Sources |
|---|---|---|---|
## Recommendation
<what to do and why; the trade-offs accepted; what would change the call>
## Caveats & open questions
- <what's unverified, disputed, or likely to change — and by when>
## Sources
| # | Source | Type (primary/secondary) | Published/updated | URL |
|---|---|---|---|---|
- Every claim carries its source; every source carries its date and type.
- Sections that don't apply (e.g. Comparison) are dropped, not left empty —
but TL;DR, Findings, Caveats, and Sources are always present.
- In the conversation, deliver answer-first: the TL;DR, the key findings,
and the path to the report file — not a paste of the whole report.
- Never write to
tasks/ — only pipeline stages do. If a stage requested
this research, hand back the TL;DR + report path and let that stage record
what it needs in its own artifact.
Rules
- No memory-only answers to time-sensitive questions — search or say you can't.
- Prefer the specialized MCP search tool over generic web search when connected.
- Primary sources over commentary; dates and versions quoted exactly.
- State "as of " for anything volatile (pricing, versions, rankings).
- Stop when the decision is answerable — research serves the decision, not the
other way around.
- Always finish with the complete report (Step 6); an answer without the
report is an unfinished research task.
