git:20260903.10f0277 to git:20260911.c655850

101 added, 102 removed. Audit A to A.

---

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".'

+ description: 'Trace code or test a recurring pattern to answer one cited question. Use when: uncertainty needs evidence. Not for external feature teardowns; use reverse-engineer.'

practices:

- pragmatic-programmer

- ddd-bounded-context

hexagonal_role: driving-adapter

consumes:

- research-question

produces:

- research-report

+ - codebase-recon.v1

+ - pattern-mining.v1

context_rel: []

skill_api_version: 1

+ user-invocable: true

allowed-tools: Read, Grep, Glob, Bash, Write

metadata:

- capabilities: [research]

- effects: [write_research_report]

+ capabilities: [research, codebase_recon, pattern_mining]

+ effects: [write_research_report, write_recon_pack, write_pattern_evidence]

canonical_status: canonical

disposition: keep_specialist

tier: execution

dependencies: []

context:

window: fork

intent:

- mode: questions

+ mode: task

sections:

exclude:

- HISTORY

- - TASK

- output_contract: skills/research/schemas/findings.json

+ output_contract: cited answer; findings.json for ordinary durable reports; validated codebase-recon.v1 or pattern-mining.v1 for selected evidence modes

---

# 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:

+ Answer the caller's bounded question with cited evidence. Choose ordinary

+ investigation, repository tracing or pattern evidence according to the question;

+ these are optional modes, not a sequence. A quick answer needs no report file.

- - 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.

+ ## Investigation

- ## Contract

+ 1. State the question and the decision it informs. Reuse the accepted scope and

+ identify what evidence would answer it; do not expand the objective mid-search.

+ 2. Inspect the smallest relevant sources. For changing external facts, use

+ current primary sources. Verify search hits against the actual source.

+ 3. Distinguish observation, inference, contradiction and unknown. Every material

+ claim cites evidence; source agreement does not erase shared provenance.

+ 4. Lead with the answer, then show evidence and remaining gaps. Each part of the

+ question is answered or explicitly unknown with the searched scope disclosed.

- 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.

+ Code claims cite the observed commit plus `file:line`. For uncommitted content,

+ state HEAD and the changed-file status; do not claim the working bytes can be

+ replayed from HEAD. Keep source identity and freshness visible. Search output,

+ CASS, MS and prior reports are leads, not authority or required phases. Use the

+ current agent by default; additional readers and runtimes require caller

+ selection or existing authorization.

- 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.

+ For several supplied reports, retain each source's identifier, author/runtime

+ when known and revision/date. Compare claims as agreement, contradiction or

+ unknown while preserving their original evidence. Repeated quotations of one

+ upstream source are not independent corroboration. Verify decisive claims at

+ their source and return one synthesis; do not launch recursive synthesis passes.

- ## Commit-level citation for code claims

+ ## Repository tracing

- 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.

+ For a repository model or audit, start from its declared entry points in docs,

+ build manifests or command help and verify them against executable paths.

+ Follow a relevant flow through entry, domain logic, integration and tests;

+ prefer a completed trace to a shallow directory inventory. Report an interrupted

+ trace at its exact file/line and explain what is missing. Choose a useful lens

+ such as persistence, authorization, CLI, build or test without requiring a sweep

+ of every lens.

- ## Done means observable capability

+ An inline investigation may use dirty working-tree evidence with explicit limits.

+ When a durable `codebase-recon.v1` pack is selected, its stricter contract applies:

- 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.

+ - Write `codebase-recon.json` and a cited `codebase-recon.md` companion at the

+ caller's chosen location, default `.agents/scratch/codebase-recon/<run-id>/`.

+ Keep mental model, bounded audit, pattern evidence and synthesis distinct.

+ - Bind the exact current full commit OID, at least one complete baseline flow,

+ claims with kind, confidence and evidence, and inspected/uninspected scope. Fact and inference citations

+ resolve to repository-relative regular files at that commit; the companion

+ report includes line references. Unknowns remain explicit.

+ - The manifest `report` names the companion and its lowercase SHA-256. The

+ companion has one `` marker and

+ `manifest_commit`, `manifest_mode`, `flows_sha256`, `claims_sha256`, and

+ `coverage_sha256` markers; section digests hash the `jq -cS` output for each

+ section, including its trailing newline.

+ - Discover validated priors with

+ `skills/research/scripts/codebase-recon/validate-output.sh --repo-root <target> --discover-priors`.

+ Prefer a verified delta when it answers the request. Delta evidence needs a

+ valid ancestor chain, `baseline_verified: true` and the exact changed paths

+ between the prior and current commits; do not relabel a directory scan as delta.

+ - Run `skills/research/scripts/codebase-recon/validate-output.sh --repo-root

+ <target> <recon.json>` before handoff. It checks both artifacts and rechecks

+ their identities, HEAD and source state; dirty source outside `.agents/` cannot

+ satisfy this commit-bound pack. Return a validation failure without disguising

+ it as a completed recon pack.

- ### Multiple caller-supplied reports

+ Preserve earlier `.agents/recon/<run-id>/` packs and their exact cited identities.

+ Prior discovery checks both legacy and current roots; never move or delete old

+ proof to match a new layout. See the [recon scenarios](references/codebase-recon/codebase-recon.feature).

- When the caller supplies several reports for one bounded question, synthesize

- them as evidence inside this same Research invocation:

+ ## Pattern evidence

- 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.

+ For a recurring implementation shape, test whether the similarity represents a

+ reusable rule. Record replayable searches, examined hits and exclusions. Align

+ independent implementations by their role in the behavior, then separate required

+ invariants, legitimate variation and incidental syntax. Copies of one lineage

+ do not count as independent evidence.

- 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.

+ A `pattern-mining.v1` promotion needs at least three distinct anchored exemplars,

+ a candidate formed before inspecting a separate holdout, a passing holdout and

+ successful back-application of every refinement to the original exemplars.

+ Every invariant needs supporting alignment. Otherwise preserve the result as

+ `outcome: hypothesis` with `route: no-action`; do not package weak evidence as a rule.

- ## Output

+ For this selected durable mode, write `pattern-mining.json` to

+ `.agents/scratch/pattern-mining/<run-id>/` or an authorized caller location and

+ run `skills/research/scripts/pattern-mining/validate-output.sh <pattern.json>`.

+ Preserve the schema's `outcome`, `exemplars`, `invariants`, `variations`,

+ `incidental`, `holdout`, `back_application` and `route` fields. The compatibility route

+ value `operationalize` on a valid promotion refers to

+ [Skill Builder's distillation mode](../skill-builder/SKILL.md#distill-expertise);

+ it is not a retired skill invocation or automatic dispatch.

- For a quick question, return the cited answer directly. When the caller asks

- for a durable artifact, write one report containing:

+ Recommend the least committed useful shape: no action, a reference/checklist

+ line, a template, helper or gate. A gate needs demonstrated cost of violation,

+ not merely recurrence. Research returns evidence; adoption remains an explicit

+ caller decision. See [pattern scenarios](references/pattern-mining/pattern-mining.feature).

- - question and scope;

- - answer;

- - evidence references;

- - contradictions and unknowns;

- - checked and unchecked areas.

+ ## Output and boundaries

- 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.

+ Return a cited answer directly unless a durable output was requested or the

+ selected evidence contract requires one. Ordinary durable reports follow

+ [findings.json](schemas/findings.json): question, scope, answer, evidence,

+ contradictions, unknowns, checked and unchecked areas. Multi-report synthesis

+ also retains `source_ledger` and `comparison`. Selected recon and pattern modes

+ retain their own validated formats instead of forcing them into this schema.

- Do not emit approval, confidence gates, retry instructions, owner, next action,

- or delivery state.

+ Use only authorized sources and destinations. For restricted or mined episode

+ material, follow [Memory's access and storage boundary](../memory/SKILL.md).

+ Research selects no work, owns no merged context store, mutates no lifecycle

+ state and issues no semantic verdict. The native caller owns implementation,

+ judgment and completion of the authorized outcome.