research

name	research
description	Answer a bounded question with current cited evidence. Triggers: "research", "investigate this question", "find evidence". (Investigating a repository routes to codebase-recon.)
practices	["pragmatic-programmer","ddd-bounded-context"]
hexagonal_role	driving-adapter
consumes	["research-question"]
produces	["research-report"]
context_rel	[]
skill_api_version	1
allowed-tools	Read, Grep, Glob, Bash, Write
metadata	{"capabilities":["research"],"effects":["write_research_report"],"canonical_status":"canonical","disposition":"keep_specialist","tier":"execution","dependencies":[]}
context	{"window":"fork","intent":{"mode":"questions"},"sections":{"exclude":["HISTORY","TASK"]},"intel_scope":"topic"}
output_contract	skills/research/schemas/findings.json

Research

Answer one bounded question with current evidence. Research informs a caller; it does not select work, approve a plan, mutate lifecycle state, or decide what happens next.

Contract

1. State the question, decision it informs, scope, non-goals, and evidence required for a useful answer.
2. Search the smallest relevant local sources. For changing external facts, use current primary sources.
3. Verify structural or semantic-search leads against authoritative content.
4. Separate observation, inference, contradiction, and unknown.
5. Lead with the answer and cite every load-bearing claim.
6. Report unchecked scope and stop.

Use the current agent inline by default. Parallel readers or alternate runtimes are optional execution choices only when the caller authorizes them. Prior research, CASS, MS, codebase recon, and pattern mining are advisory context sources, not required phases. Hydrate only the sources the current decision needs and return cited evidence with source identity and freshness; never build or maintain a merged context store.

Commit-level citation for code claims

A claim about what code does cites the commit it was observed at, plus file:line — code moves, and a citation without a revision decays silently into a claim about a repository that no longer exists. For the working tree, record the current HEAD and whether the cited file carries uncommitted changes. The named failure mode is the floating citation: a path and line that resolved when written, drifted after a refactor, and now lends false authority to a stale answer. A reader must be able to run git show <commit>:<path> and see the cited lines; a code claim that cannot survive that replay is reported as unverified, not asserted.

Done means observable capability

Research is done when its capability flags are answerable, not when effort feels sufficient. At the start, derive from the bounded question a short list of capability statements — "can name the module that owns X, with citation", "can state whether Y is reachable from Z, or that this is unknown". The stop condition: every flag is either satisfied with evidence or explicitly reported unknown with what was searched. Hours spent and files read are not flags. The named failure mode is effort-shaped doneness — stopping because the search was long, and shipping an answer whose load-bearing claim was never actually established. If a flag stays unsatisfiable inside scope, say so and stop; widening the question mid-search is a new question, and the caller owns it.

Multiple caller-supplied reports

When the caller supplies several reports for one bounded question, synthesize them as evidence inside this same Research invocation:

1. Build a source ledger before comparing claims. Preserve each report's path or supplied identifier, title, author/runtime when known, and revision or date when supplied. Assign a short local label without replacing that identity.