Findings

A finding is a specific, located observation from verification — a named file, a concrete issue, and a recommended action. Findings accumulate in the proof chain and are triaged by Learn between pipeline cycles.

Reading time · 6 minLast reviewed · 2026-07-02

Severity levels

SeverityMeaningTypical action
riskCould hurt you. Security flaw, data loss, silent failure.Fix before merging — usually scope.
debtMaking the codebase worse. Duplication, fragile patterns, missing tests.scope for follow-up or promote to a skill rule.
obsWorth knowing. Not wrong, but useful for the next engineer.acknowledge or monitor.

Suggested actions

Every finding carries a suggested_action — the classifier's recommendation for what to do. This is the second word in the terminal notation [debt · scope].

ActionMeaning
promoteEncode as a permanent rule in a skill file. The pattern should never recur.
scopeNeeds engineering work. Create a new pipeline scope to address it.
monitorWatch across future cycles. Not urgent, but track for recurrence.
acknowledgeAcknowledged. Valid observation, no action needed.

Categories

Each finding is categorized: code (implementation issue), test (test quality or coverage), or upstream (spec, scope, or tooling issue). The category tells you what kind of thing is wrong — severity tells you how much it matters.

Lifecycle

Every finding starts as active. From there, two terminal states:

  • closed — resolved or acknowledged. The closed_by field records who: mechanical (the referenced file was removed), human (developer decision), or agent (Learn triage).
  • promoted — the finding describes a recurring pattern. It becomes a rule in a skill file via ana proof promote. The promoted_to field records which skill received the rule.

Between pipeline cycles, run ana run learn to triage active findings. Learn presents them by severity, recommends actions, and executes closes and promotions with your approval.

Note

A finding without a follow-up is wasted. The lifecycle ensures every finding either informs the next cycle or is explicitly acknowledged.

A real finding

From the security-hardening proof:

json
{
  "id": "security-hardening-C2",
  "category": "test",
  "summary": "No dedicated integration tests for command entry point injection rejection",
  "file": null,
  "severity": "debt",
  "suggested_action": "scope",
  "status": "active"
}

Active. Categorized as a test gap. Severity: debt — the codebase is getting worse without these tests. Action: scope — needs engineering work as a follow-up. No single file to point at because it's a structural gap, not a line-level bug.

Build also produces build concerns — lighter-weight observations that enter the proof chain with severity and action but without lifecycle tracking. Findings are Verify's output; concerns are Build's honest admissions.

GuideVerifying changesThe verification process — how Verify works independently and what its report contains.Real examplesecurity-hardening10 findings from a security audit.