What a finding is

A finding is the smallest stable unit in doctor, workspace doctor, and explain.

Use it when you need one issue model that still works for CI, editors, agents, and support workflows.

findings explain the issue, why it matters, and what to do next
findings keep the machine-readable identifier stable even when wording changes
findings let humans and tools read the same issue model without scraping terminal prose
a finding should be specific enough that a user can act on it without guessing

Field descriptions

severity tells you whether the finding blocks readiness: error, warn, or info
code is the stable machine-readable identifier for the condition, such as OTA_TASKS_MISSING
category tells you which area the finding belongs to, such as contract, service, policy, or workspace
owner tells you who should act on it, such as the repo contract, host, service, or workspace
summary is the short headline a human should read first
why explains why the finding exists and why it matters
next gives the safest next action ota can recommend
evidence holds the structured facts behind the finding so CI and support can verify it; probe-aware runtime and tool findings can include command and path when ota resolved an executable and recorded the exact probe it ran
the fields together should answer: what happened, why it matters, and what to do next

How to read findings

Read severity first to know whether the finding blocks readiness
Then read summary to understand the issue in one line
Then read why to understand the consequence
Then read next to see the safest fix
Then inspect evidence if you need the proof
runtime and tool diagnosis can distinguish missing commands from probe failures and unparseable version output without changing the stable finding model
If the wording changes later, the code should still stay stable
The top finding renders as the bold title on the Primary Blocker or Primary Finding block, without a separate Verdict: label

Why it matters

CI can gate on stable identifiers instead of brittle wording
agents can ask for the next action instead of guessing
support teams can classify the issue as contract, service, policy, or host related
workspace roll-ups stay readable without flattening repo-level context
the same finding model works across repo doctor, workspace doctor, and explain

Finding catalog

the shipped code catalog lives in docs/spec/doctor-finding-reference.md in the ota repo
use that reference when you need the published code, category, owner, and provenance_key surfaces without reading Rust source directly
workspace acquisition and repo-contract blocker codes are included there alongside the repo doctor finding families

Example findings

Blocking contract issuetext

ERROR  No tasks definedWhy: The repo contract is not yet runnable because ota cannot discover a safe task entrypoint.Next: add a task such as `setup`, `test`, or `build` so the repo can be executed safely.

Warning-only service issuetext

WARNING  Required service has no healthcheckWhy: ota cannot verify readiness without a healthcheck, so the repo may look ready when it is not.Next: add a healthcheck command to the service contract.

Policy findingtext

ERROR  Repo does not satisfy org policy packWhy: The policy pack requires `AGENTS.md` and this repo does not have it, so the repo does not meet org rules.Next: add the missing file or update the policy pack.

Where it shows up

ota doctor
ota workspace doctor
ota explain
policy-aware findings
CI annotations derived from doctor JSON

What a finding is not

not a raw log line
not a free-form error blob
not a hidden policy engine response
not a replacement for the contract or the execution receipt

How CI should use it

gate on severity: error and stable code values
render summary as the human headline
render why as the explanation
render next as the suggested fix
avoid re-parsing text output when JSON is available

Use cases

fastest fix path for a blocked repo
stable machine identifiers for CI
contract, service, policy, or host classification for agents
workspace findings without reading raw JSON