In plain words
A verdict tells you what happened; a reason code tells you why in a form software can act on. "Failed" is a fact, and not_found is the next step: the destination was read and the outcome wasn't there. Reason codes let an operator fix the right thing and let a developer branch on the result without parsing prose.
How QED Proof uses it
Every verdict except Verified should carry a reason_code, and Couldn't check must. The receipt spec defines them:
| Code | With | Meaning |
|---|---|---|
not_found |
Failed | Read, and no matching outcome by the deadline |
content_mismatch |
Mismatch | The fingerprint differs from the claim |
target_mismatch |
Mismatch | It exists, under a different account, branch or recipient |
observed_after_tolerance |
Late | Present, but after the tolerance window |
no_connection |
Couldn't check | No access to the destination for this target |
permission_denied |
Couldn't check | Access exists but doesn't cover this read |
rate_limited |
Couldn't check | Throttled on every read until the deadline |
destination_unavailable |
Couldn't check | The destination errored or timed out |
unsupported_action |
Couldn't check | No verifier profile for this action |
claim_ambiguous |
Couldn't check | The claim lacks fields the profile needs |
verifier_error |
Couldn't check | An internal failure in the verifier |
Example
The console pairs each code with a plain sentence, like "The commit it named isn't on main." It keeps the code in a monospace font beside the sentence, so people read the sentence and scripts read the code.