| name | research-dossier |
| description | Answer a question from primary sources and record every source checked under `research/`. Use when the user asks for a topic researched, for the evidence behind a claim, or when a decision needs facts you would otherwise guess at. |
Two artifacts, both required: an answer someone can act on, and a trail someone can re-walk.
Done when every claim in the answer carries a footnote, and every source you opened appears in resources/ with a verdict.
Cite what already exists. When answering requires running something new — a benchmark, a script, a test — that is a prototype: build it there, then cite its result here.
Where it goes
Put the folder where the repo already keeps such notes, matching that convention. Absent one, use research/. Say where you put it.
The folder's internal shape is fixed either way:
{notes-root}/YYYY-MM-DD-{slug}/
├── outcome.md
└── resources/
└── {nn}-{query-slug}.md # one file per search query
Read today's date from the system. {slug} is three to five kebab-case words naming the question.
Steps
- Split the question. Write the sub-questions that must each be answered before the whole one is. These become your queries.
- Search one query at a time. Open that query's
resources/ file before you read anything, and log each result as you judge it — mid-flight, not reconstructed at the end.
- Read the source that owns the claim. Official docs, specs, first-party APIs, the paper itself — and locally, the installed source in
node_modules, the lockfile, the repo's own code. A package's shipped source outranks its documentation. A secondary write-up is a pointer to a primary source, not a substitute for one: follow it back and cite what it points at.
- Write
outcome.md. Where sources disagree, say so in the body, name the one you trust, and say why.
outcome.md
---
date: 2026-08-22
question: <verbatim, as the user asked it>
answer: <one or two sentences; the thing they can act on>
sources:
- <url, or pinned local reference>
---
Long-form answer in markdown, with references as footnotes.[^1]
[^1]: [Title](url), section name.
[^2]: lodash@4.17.21 · src/index.js:340
sources lists only what you cited. Everything you opened and rejected lives in resources/.
Cite a local source as {package}@{version} · {path}:{line}, or {repo}@{sha} · {path}:{line} for the repo's own code. A bare path rots the moment the dependency moves.
Downstream documents cite your sources, not you
This folder is a trail, and a trail is deletable. Anything durable that comes out of it, an ADR above all, restates the finding and cites what you cited: the vendor's reference, the spec, the pinned declarations, the manual page, a commit-pinned permalink. A document that points at research/ instead is only checkable while this folder survives. Leaving the primary source easy to lift, one link per claim, is what makes that possible.
resources/{nn}-{query-slug}.md
# {the query, verbatim as run}
- Tool: <search engine, ripgrep, npm view, gh api, …>
- Params: <flags, filters, date range, site: scoping, paths searched, pages read>
| Source | Verdict | Why | Summary |
| --- | --- | --- | --- |
| [title](url) | used | first-party spec for X | one line of what it contributes |
| zod@3.23.8 · src/types.ts:1204 | used | the shipped implementation | one line of what it contributes |
| [title](url) | discarded | 2019 blog restating the spec | — |
Verdict is used or discarded. Every source you opened gets a row, including the ones that wasted your time — the trail earns its keep by stopping the next run re-opening them.
