Run and read
Explain a result
Why a number is — or isn’t — trustworthy.
/evalglass explain narrates a result strictly from the typed authority and
diagnostics already in the Scorecard. It reads back why a metric did or did not gate, and
why a value is or isn’t a claim — it never recomputes, infers, or adds authority the records don’t
carry. A missing field is reported as missing, never guessed.
view tells you what was measured; explain tells you why you
can or can’t trust it. Both read the same typed artifact — so an explanation can only ever
restate what the authority records and
diagnostics already say.
What explain reads
For each metric it surfaces two typed sources, never prose:
| Source | What it answers |
|---|---|
authority[m] | May this metric gate? can_gate / level + typed reasons (e.g. threshold_proposed, dataset_proposed, metric_status=informational). |
diagnostics | Why is a state non-perfect? Each is a structured record — code, severity, message, location, cause, evidence refs — not a sentence to parse. |
A worked explanation
Running /evalglass explain exact_match on the quickstart reads back:
output
exact_match — informational (cannot gate)
authority.reasons:
- metric_status=informational (the metric is not set to gating)
- threshold_proposed (no approved threshold)
- dataset_proposed (sample gold is proposed, not validated)
measurement:
- included=3 non_evaluable=2 (2 trace rows have no reference)
→ value 1.0 is "measured well", not "allowed to gate".
Every line above is lifted from the Scorecard’s typed fields. The two
non_evaluable rows are reported as excluded — never folded into
the value as 0.0 — and the explanation says why the perfect value still
gates nothing.
A missing field is reported as missing
If a Score lacks a subject identity, a baseline was never requested, or a diagnostic has no cause,
explain says so plainly. It will not infer a reason that the records don’t support —
inventing one would be exactly the false confidence the project forbids.