--- name: research description: >- Use when the user wants a tool, library, or API researched from canonical documentation into structured per-topic reference markdown files. Not documentation written from existing code or specs -> `write-docs`. Not a bug or incident -> `diagnose`. metadata: category: research allowed-tools: - Grep - Glob - Read - Write - WebSearch - WebFetch - mcp__context7__resolve-library-id - mcp__context7__query-docs model: sonnet --- ## Gotchas - Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask. - Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for. - Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed. - A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph. ## Step 1 — Scope against the working directory Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented. Read `references/topics.md` before narrowing, for the default topic list. ## Step 2 — Resolve against Context7 If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-`, and mark which topic areas it covered — those skip the web reads at step 4. If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt. ## Step 3 — Discover sources If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4. Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them. If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials. ## Step 4 — Read the sources `WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one. ## Step 5 — Deepen `WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality. ## Step 6 — Write Merge every set of notes, Context7 and web alike, by topic area. Read `references/file-format.md`, then write, in the output path: - `.md` for each topic area that has content, default or custom - `sources.md`, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, marked `no content extracted` Spell the `sources.md` field names exactly as `references/file-format.md` gives them. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing. If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.