---
name: research
description: Investigate a question against high-trust primary sources and capture the cited findings as a Research artifact. Use when a topic needs documentation, API, specification, source-code, or other reading legwork.
---

# Research

Investigate one question and preserve the findings in one cited Research artifact.
Run in the current process.
Isolation and concurrency belong to the caller.

## 1. Resolve the artifact

Resolve the artifact destination before naming the file.
When the caller provides a destination directory, use it exactly.
Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
If that vault is unavailable, fall back to `./docs` in the current project.
Create the destination directory only when needed.

Before choosing a filename, read the destination's `AGENTS.md`.
Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context.
Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.

When the caller provides an existing ticket artifact path, use it exactly, do not allocate a filename, and complete that artifact in place.
Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research.

Done when one authoritative Research artifact path and its metadata are settled according to the destination convention.

## 2. Investigate the question

Use primary sources such as official documentation, specifications, source code, and first-party APIs rather than relying on secondary accounts.
Follow every substantive claim back to the primary source that owns it.
Use secondary material only to discover primary sources.
When no primary source establishes a needed claim, record that limitation instead of presenting the claim as settled.

Done when the question is answered as far as primary evidence permits and every substantive claim has an owning source or an explicit evidence gap.

## 3. Write the Research artifact

Write the findings to the resolved Markdown file and follow the destination's artifact conventions.
When the resolved file is an existing ticket artifact, preserve its workflow metadata and complete the result in that file.
Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session.
Do not create a source dump or research log.

Done when exactly one Research artifact exists at the resolved path and every substantive claim in it cites its source.

## 4. Return the result

Report the artifact path and a concise statement of what the research established or could not establish.

Done when the caller can locate the artifact and understand whether the question was resolved.