/research-catalog

name: research-catalog
description: Whenever you do real external research (WebFetch, WebSearch, or Explore-agent fetches of URLs outside the repo), catalog it in docs/research/ before sending the synthesis back to the user. Credits the sources, captures the findings, and creates a traceable link from the decision back to the evidence.

Research catalog and credit

> **No em-dashes.** Nothing this skill writes may contain an em-dash; use a comma, colon, or parentheses instead. Enforced by a repo hook that flags em-dashes in generated `.md`. See `/flagrare:write-docs`.

External research is someone else's work. The papers, blog posts, vendor docs, and open-source projects we lean on were written by named humans (or named orgs), and the project owes them three things: visible credit, a usable citation back, and a record of which decision their work informed. This skill is the way the project pays that debt.

It also pays a second debt, to the project's own future. ADRs say *what* was decided. Without a catalog of the research behind those decisions, the *why* drifts out of reach within months. This skill captures the evidence base alongside the decision, in a stable in-repo location, so a contributor six months from now can trace any non-obvious choice back to the work that justified it.

When to invoke

Run this skill **immediately after** a research session that pulled in external sources, and **before** the synthesis is sent back to the user. Sources count as "external" when they came from:

• a WebFetch or WebSearch tool call
• an Explore-agent prompt that asked the agent to fetch URLs
• a referenced paper, blog post, vendor doc, or open-source repository you actually read

It does **not** apply to:

• Lookups inside the repo (`git log`, `grep`, file reads).
• Re-stating prior research without re-fetching anything.
• Trivial single-query lookups like "what's the latest version of X" or "is package Y on npm".
• Internal reasoning that doesn't lean on a citable external source.
• **Research that informed the project's dev tooling or workflow rather than the project's subject matter.** A catalog entry in `docs/research/` documents *why the product is built the way it is*, not *how the team chose to build it*. If you researched a commit-message convention, a testing framework's idioms, a changelog-formatting style, a build tool's options, or an agent-skill's calibration, that research belongs with the tooling it informed (a doc in the tool's own repo, a comment in the relevant config, a memory entry in the agent's working files). It does not belong in the project's research log alongside research about the project's actual domain.

The trigger is the conjunction of two things:

1. *Did external work inform the answer the user is about to read?* If no, don't catalog. 2. *Is the work the user is about to read part of the project's premise, its subject matter, the problem domain it tackles, the design decisions about what it does for its users?* If no, don't catalog *here*, catalog with the tooling instead, or skip cataloging entirely if the tooling lives elsewhere with its own provenance.

The rule of thumb: if a stranger reading `docs/research/` learns something about *what the product is and why it's designed this way*, the entry belongs. If they only learn *how the team built it*, it doesn't.

Procedure

1. Pick a slug

Format: `YYYY-MM-DD-topic` in kebab-case. Examples:

• `2026-05-18-llm-persona-best-practices`
• `2026-03-14-vercel-ai-sdk-providers`

If you've already done research on a related topic *today*, append to that file rather than creating a new one. New sources get appended to its `## Sources` section; the synthesis section grows.

2. Create or open `docs/research/<slug>.md`

If `docs/research/` does not exist, create it now. Use the file template below.

3. Fill in one source entry per source

Only catalog sources that actually informed the synthesis. Don't pad the list with sources you skimmed and abandoned. Don't pad with sources you "could have used." The catalog reflects what the answer was *built from*, not what was *available*.

4. Update `docs/research/README.md`

If this file does not exist, create it using the index template below. Add a row linking the new catalog file. Keep the index in reverse chronological order (newest at the top).

5. Cross-link in the consuming artifact

Wherever the findings actually land, an ADR, a memory file, a code comment, a TSDoc block, reference the catalog file. The cross-link is what closes the loop. If a decision can't point at the research that justified it, the catalog isn't doing its job.

A typical cross-link looks like:

> *Based on research in [`docs/research/2026-05-18-llm-persona-best-practices.md`](../research/2026-05-18-llm-persona-best-practices.md).*

File template

# Research: <human-readable topic>

- **Slug:** `<YYYY-MM-DD-topic>`
- **Date:** YYYY-MM-DD
- **Status:** complete | in-progress
- **Triggered by:** <what prompted this, a task #, an ADR draft, a question raised in chat>
- **Informed:** <where the findings landed, link to ADRs, src files, memory entries, etc. Fill in as cross-links are made.>

## Question

<One paragraph stating the actual question being researched. Be specific. "Best practices for LLM persona instructions" is OK; "LLM stuff" is not.>

## Sources

### [<Title>](<URL>)
- **Authors / Org:** <names if known, or "Anthropic", "OpenAI", etc. If anonymous or uncredited, say so.>
- **Type:** vendor doc | academic paper | engineering blog | open-source project | spec | news article | other
- **Published:** <YYYY-MM-DD if known, else "unknown" or "ongoing">
- **Accessed:** YYYY-MM-DD
- **Relevance:** high | medium | low
- **What this contributed:** <2-4 sentences. What did this source give us that the synthesis depends on? Not a summary of the source, a description of its contribution to OUR answer.>
- **Quoted:** (optional, when a finding hinges on s