Evidence lists
Require list items to be falsifiable claims or carry a resolvable source, with each.falsifiable, each.sourced, and each.minWords.
DATA: "I have completed the diagnostic." PICARD: "And the result, Commander?" A status with no observable result is not evidence. It's a feeling.
Most lists just need items. An evidence list needs items a reader can check — a test that ran, a number that moved, a source that resolves. The evidenceList tag plus the each.* rule family turns "trust me" bullets into claims that either hold up or fail the build.
The contract
<!-- mdv: evidenceList required minItems=2 each.falsifiable error=each.falsifiable -->
## Manual Verification
- Ran `npm test`; 412 nav checks pass, 0 fail.
- Checked the CI orbit; p95 latency dropped to 30ms.
<!-- mdv: endevidenceList -->each.falsifiable checks that every item names something verifiable. A bullet passes when it has at least four words and either a verification verb (ran, checked, verified, measured, failed, …, in past or present tense) or a concrete signal — a number, an inline code span, or a URL.
## Manual Verification
- Looks good.
- Tested it.verification.md:3 error [vague-evidence] In "Manual Verification", the item "Looks good." is too vague to verify.
verification.md:4 error [vague-evidence] In "Manual Verification", the item "Tested it." is too vague to verify."Tested it." even contains a verb, but at two words it's below the four-word floor — the heuristic rejects one- and two-word gestures on purpose.
The predicates
The two predicate rules are independent flags — add one or both to a directive:
| Rule | Default severity | Passes when |
|---|---|---|
each.falsifiable | warn | the item has ≥4 words and either a verification verb or a number / code / URL |
each.sourced | error | the item carries a citation that resolves (a link, reference, or footnote) |
each.falsifiable is a heuristic, so it warns by default — an occasional false positive nudges rather than blocks. each.sourced is deterministic (a citation either resolves or it doesn't), so it stays a hard error. Retune either per directive with the standard severity overrides — error=<rule> promotes, warn=<rule> demotes:
<!-- mdv: evidenceList each.falsifiable each.sourced error=each.falsifiable -->
## Findings
- Throughput rose 18% after the cache landed [1].
<!-- mdv: endevidenceList -->That requires every finding to be both concrete and cited, and promotes the falsifiable check to a build-failing error.
Per-item word counts
Two more each.* rules bound the size of each item independently of the predicates:
each.minWords=4— every item needs at least four words (catches terse stubs).each.maxWords=40— every item stays under forty words (catches an essay smuggled into a bullet).
When to reach for it
Use evidenceList over a plain list whenever the bullets are proof — a PR's manual-verification steps, an incident timeline, a research finding, a security review's checks. For an ordinary list (commands, links, options) a plain list with minItems is enough; save the evidence predicates for claims that have to survive scrutiny. And because each.falsifiable is English-biased, a team writing evidence in another language can drop it (or keep only each.sourced) without losing the rest of the contract.