skills/usable-knowledge-workflow/references/evidence-and-verification.md

# Evidence and verification

## The distinction that matters

There are three states, and collapsing them is the most common failure:

| State | Meaning |
|---|---|
| Verified | You observed the result. A command ran and you read its output; a test passed; you re-read the file after editing. |
| Reported | A source claims it. Someone wrote it down, possibly correctly, possibly a year ago. |
| Assumed | You inferred it from convention, naming, or prior experience. |

Verified and reported are both legitimate inputs. Assumed is legitimate too — as long as it
is labelled. What is never acceptable is presenting reported or assumed material as
verified.

## What does not count as verification

- "The change should work." — a prediction, not an observation.
- "I ran the tests." — with no output read. Exit codes exist for a reason.
- "The file now contains X." — without re-reading it. Edits fail.
- "The API returns Y." — based on a doc, not a call.
- A tool call that returned an error you did not read.
- A green result from a test that does not exercise the changed path.

## Reporting partial verification

Partial verification is normal and worth stating precisely. Vague hedging ("should mostly
work") is worse than a clear split:

> Verified: unit tests pass (48/48), and the new endpoint returns 200 with the expected
> body against the local server.
> Not verified: behavior under concurrent writes, and the production migration path. The
> staging environment was unreachable.

The user can act on that. They cannot act on "I think it's fine".

## Verifying against stored knowledge

When stored knowledge and observed reality disagree, reality wins — and the disagreement is
itself worth reporting, because it usually means the stored item is stale and someone
should fix it.

> The stored solution says the retry limit is 3, but `config/retry.ts:14` sets it to 5.
> I used 5, which is what the code actually does. The stored item looks out of date.

## Cost of a false success claim

A wrong answer that is labelled uncertain costs the user a few minutes of checking. A wrong
answer labelled as done costs them a production incident and their trust in every future
answer. The asymmetry is large enough that when in doubt, you should under-claim.