53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
---
|
|
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.
|