Defame1297
4011d149bc
grill-me, grill-with-docs, improve-codebase-architecture, tdd and triage each had their routing boundary written into README.md, which nothing loads at runtime, while the gate still reported all five descriptions as boundary-less. The boundaries move into the descriptions; write-docs' clause, which said 'those have dedicated skills' without naming one, now names them. research had moved its body out and then read both references unconditionally -- the anti-goal ADR-0020 names, where the word count moves and the per-run context does not. Both loads are genuinely conditional now, with the topic list and the four literal sources.md field names inlined, since the provenance validator matches those literally. Also restores the promote-the-prototype anti-pattern to prototype's ui.md, which the gate does not measure, so deleting it bought nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
2.8 KiB
research
Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
What it does
Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a sources.md provenance record.
Four gotchas at the top of SKILL.md shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub troubleshooting.md reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — sources.md included — and reports what it searched.
The frontmatter pins model: sonnet and a closed allowed-tools list. Notably it grants no subagent tool, so every WebFetch is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
Composition
Both reference files are read on condition, never on every run — SKILL.md inlines the minimum each step needs (the seven default topic areas at step 1, the four sources.md field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred.
Usage
/research
Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use write-docs; for a bug or incident, use diagnose.
Files
| File | Purpose |
|---|---|
SKILL.md |
The four gotchas and the six research steps |
references/topics.md |
Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule |
references/file-format.md |
Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body |