| 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
- State the question, decision it informs, scope, non-goals, and evidence
required for a useful answer.
- Search the smallest relevant local sources. For changing external facts,
use current primary sources.
- Verify structural or semantic-search leads against authoritative content.
- Separate observation, inference, contradiction, and unknown.
- Lead with the answer and cite every load-bearing claim.
- 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:
- 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.
