skills/repo-scout/references/evidence-and-output.md

# Evidence and output contract

## Evidence levels (do not conflate)

- E0: lead/hypothesis from names, patterns or assumptions; do not present as confirmed.
- E1: code-supported concern with concrete reachability and counter-checks; may still
  need missing runtime/config context. Label the residual assumption.
- E2: source-level proof of an invariant/contract violation with sufficient surrounding
  control/data flow and prerequisites. Explicitly state no runtime reproduction if none.
- E3: reproduced in the recorded environment with command/actions and actual output.

A high-impact E1 can deserve urgent investigation. Severity and certainty are separate.
A structural/test gap or product proposal need not pretend to be an E3 runtime defect.
Confidence is justified in prose; avoid fake decimal precision.

## Finding

Use a stable descriptive ID, kind, component, title, priority and evidence level.
Record snapshot (commit and dirty state), exact source locations and symbols, expected
contract/source, trigger/preconditions, actual evidence, user/business impact,
alternative explanations checked, remaining uncertainties, suggested minimal fix,
acceptance criteria, effort/risk assumptions, verification details and dedup status.

Suggested fixes are not automatically validated solutions. Tests or benchmarks
written in a plan must say NOT RUN. A number is an estimate unless measured; record
how measurements were obtained. Never invent file paths, line numbers, test counts,
benchmark results, issue IDs, tool versions or subagent outputs.

## Report sections

1. Scope, snapshot, mode, budget and environmental limits.
2. Observed project/module/contract map.
3. Ranked findings (possibly empty) with evidence and next action.
4. Verification ledger: not run / passed / failed / blocked; exact target and result.
5. Coverage matrix by module + platform + lane + verification level. Mark inspected,
   partial, blocked, deferred or not applicable and why.
6. Duplicated/rejected leads, unresolved assumptions and publication/fix boundary.

Do not label the entire repository safe or fully verified based on sampled review.
Do not silently discard omitted generated/shared code when it affects a boundary.
An issue tracker outage makes dedup incomplete, not clean.

## Issue draft layout

Title: [component] observable failure or concrete improvement outcome

Snapshot and scope → expected/actual → evidence → impact and prerequisites →
counter-checks → proposed fix with alternatives → acceptance criteria → tests/commands
(run status explicit) → migration/rollback if needed → dependencies/duplicates → gaps.

For recurring runs keep state per repo identity + branch/commit + scope + finding root
cause. Do not deduplicate solely by line number; code movement changes it. Distinguish
unchanged findings, regressions, resolved findings and unavailable data. This starter
specifies that policy; it does NOT implement persistent storage or an issue publisher.