Defame1297
03abcffb77
diagnose read its feedback-loops reference unconditionally, so every invocation paid for guidance most runs never used; the read is conditional again and the per-invocation cost drops from 1,278 to 831 words. Its HITL template moves to assets/ because it is copied out, not read as reference. prototype's two branch flows move into references/ for the same reason — only one branch is ever taken. research could not search the codebase it was asked to research without Grep and Glob. caveman's description had grown into a paragraph where one sentence carries the trigger. Four references pointed at things that do not exist: a to-prd skill, a /setup-matt-pocock-skills command, two cross-skill ../ links that only resolve in the source tree, and two places calling this project's Gitea host GitHub. Addresses #114.
3.9 KiB
name, description, metadata, allowed-tools, model
| name | description | metadata | allowed-tools | model | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| research | 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`. |
|
|
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.mdreads 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-<library-slug>, 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:
<topic>.mdfor each topic area that has content, default or customsources.md, always, one section per source in the schema that file gives — URL, description, contributing files, and status — including sources that yielded nothing, markedno 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.