research git:20260903.10f0277A

Immutable. This exact content is served forever at /api/v1/blob/7a5d0c9513a3cf9e.

---
name: research
description: 'Answer one bounded question, cited. Not for dissecting a codebase; that is codebase-recon or reverse-engineer. Triggers: "research", "investigate this question", "find evidence".'
---
# 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.

## Prompt

```text
Research: does `ao gate check --scope head` in cli/cmd/ao/gate_composition.go
actually run scripts/check-skill-python-ratchet.sh, or only the schema
and format gates? I'm deciding whether to add a new Python file under
skills/foo/scripts/ and need a cited answer before I do.
```

## It's working if

Observable in the trace, without reading the prose:

- Every load-bearing claim cites a commit and `file:line`, checkable with
  `git show <sha>:<path>`.
- Each capability flag derived from the bounded question is answered with
  evidence, or reported as `unknown` explicitly.
- `contradictions` and `unknowns` stay visible in the output rather than
  resolved by assertion.
- The report ends with `checked` and `unchecked` scope, carrying no
  approval or next-action field.

## 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.
2. Extract each load-bearing claim with its source label and original evidence
   reference. Normalize wording only for comparison; never merge citations or
   make agreement erase provenance.
3. Group comparable claims into **agreement**, **contradiction**, and **unknown**.
   Agreement means independent reports support the same claim. Contradiction
   preserves the conflicting claims and evidence. Unknown means the reports do
   not establish the fact or the underlying source was not checked. Reports that
   repeat one upstream source are agreement in wording, not independent
   corroboration; preserve that shared provenance.
4. Verify load-bearing claims against authoritative content when the bounded
   question requires it. A report's conclusion is advisory, not authority.
5. Produce one cited synthesis that states what the reports jointly support,
   where they disagree, and what remains unknown. Report checked and unchecked
   sources, then stop.

Do not recursively launch another Research pass, invent a synthesis umbrella,
or start a new runtime merely because multiple reports exist. Additional readers
remain caller-authorized execution choices, not part of this procedure.

## Output

For a quick question, return the cited answer directly. When the caller asks
for a durable artifact, write one report containing:

- question and scope;
- answer;
- evidence references;
- contradictions and unknowns;
- checked and unchecked areas.

For a durable synthesis of multiple reports, also include `source_ledger` and
`comparison` (`agreements`, `contradictions`, and `unknowns`) as defined by the
output schema. Single-report outputs may omit those optional fields.

Do not emit approval, confidence gates, retry instructions, owner, next action,
or delivery state.