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-05-25

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.accept 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.
acceptAcknowledged. Valid observation, no action needed. Can be closed.

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 claude --agent ana-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.