research

name	research
description	Research a factual, codebase, product, or external-documentation question using primary sources and return an evidence-backed answer. Use when the user asks to investigate, compare docs, find current behavior, answer a research ticket, or gather facts before a spec, prototype, or implementation.

Research

Answer a bounded question with evidence. Prefer primary sources over commentary, and trace every important claim back to the source that owns it.

If the host can run a background agent and the question is broad enough to benefit from parallel reading, delegate the reading pass while you keep the main thread focused. If not, do the same workflow directly.

Process

1. Pin the question

Write a one-sentence research question before collecting evidence. Include:

• The decision the research should support.
• The scope: repo-local, external documentation, product behavior, market/tooling, or a mix.
• The expected output location if this came from a ticket or wayfinding map.

Ask one concise question only when the research target is too ambiguous to begin.

2. Collect primary sources

Use the strongest available sources for the claim:

• Repo source, tests, configs, logs, migrations, specs, tickets, and commit history for project-local behavior.
• Official documentation, source repositories, API references, standards, release notes, changelogs, schemas, or first-party examples for external behavior.
• The user's supplied artifacts for product, design, or business context.

Use secondary sources only as pointers to primary sources. Do not base the final answer on a blog post, forum reply, generated summary, or search-result snippet when an owning source is available.

3. Check the evidence

• Compare at least two independent primary anchors for risky or surprising claims when possible.
• Note versions, dates, flags, environment constraints, and repository state when they affect the answer.
• Run small local commands or tests when they can verify repo behavior cheaply.
• Separate observed facts from inference.

For fast-changing external facts, verify current documentation before answering.

4. Save durable findings

If this research is tied to a local research ticket, spec, or wayfinding map, update that artifact or write a short report under docs/research/<slug>.md when no repo convention exists. Create the folder only when a durable artifact is useful. Every durable report includes one ## Artifact Graph section with a stable Artifact ID, Role: research, and exactly Standalone: true or one Parent. A ticket-owned report points to that research ticket, and the ticket adds the reciprocal Produces link in the same change.

For quick questions, a concise final answer with evidence is enough.

Output

Use this shape when the answer is more than a quick reply:

## Answer

<Direct answer in one or two paragraphs.>

## Evidence

- <Source path or citation> - <fact supported by that source>.

## Unknowns

- <Remaining uncertainty, or "None".>

## Next Step

<Decision, prototype, spec update, or implementation step this research enables.>

Keep the output proportionate. Do not dump notes, transcripts, or long quotes unless the user asked for raw research materials.