---
name: research
description: Use when a question needs reading legwork against primary sources and the findings should be written down, such as how a third-party API behaves, how a protocol works, or how a vendor compares. Not for library API syntax, which is find-docs.
---

# Research

Delegate reading to a background agent so the main thread keeps working, and land the findings as a
cited Markdown file.

**This is not the skill for library or framework API questions.** Version-specific syntax,
configuration options, and SDK signatures belong to `find-docs`, which queries Context7 directly and
is faster and more accurate for exactly that. Reach for `research` when the question is *not* a
documented library API: how a third-party service actually behaves, how a protocol or file format
works, how two vendors compare, what a spec requires.

## Process

Spin up a **background agent** so you keep working while it reads. Its brief:

1. **Investigate against primary sources**: official documentation, the source code itself, the
   specification, the first-party API. Not a secondary write-up of one. Follow every claim back to
   the source that owns it, and where a claim only exists in a blog post, say so rather than
   promoting it.
2. **Write the findings to a single Markdown file**, citing the source for each claim as a link.
3. **Save it where this repo already keeps such notes.** Match the existing convention; where there
   is none, use `.claude/docs/research/<topic>.md` and say where it landed.

Where the question has an answer that is genuinely contested or version-dependent, the file records
the disagreement rather than picking a winner silently.

## Done when

- Every claim in the file carries a link to the primary source that owns it.
- Anything that could only be found in a secondary source is labelled as such.
- The file's location was reported.