Evidence lists
Require list items to be falsifiable claims or carry a resolvable source, with items.all=@evidence/specific, items.all=@evidence/cited, and items.words.min.
DATA: "I have completed the diagnostic." PICARD: "And the result, Commander?" A status with no observable result is not evidence. It's a feeling.
An evidence list holds items a reader can check: a test that ran, a number that moved, a source that resolves.
The contract
<!-- mdv: section required -->
## Manual Verification
<!-- mdv: list required items.min=2 items.all=@evidence/specific error=vague-evidence -->
- Ran `npm test`; 412 nav checks pass, 0 fail.
- Checked the CI orbit; p95 latency dropped to 30ms.## Manual Verification
- Looks good.
- Tested it.verification.md
State: what the document claims; clear it by doing the work or saying it is not done
3 warning "Looks good." can't be checked vague-evidence
help: Say what you ran or saw, e.g. "npm test: 312 passed"
4 warning "Tested it." can't be checked vague-evidence
help: Say what you ran or saw, e.g. "npm test: 312 passed"
✖ 2 problems (0 errors, 2 warnings)
mdv explain <rule-id> for detailsThe predicates
| Rule | Default | Passes when |
|---|---|---|
items. | warn | 4+ words and a verification verb, number, code or URL |
items. | error | a link, reference or footnote resolves |
Both can combine; specific is a heuristic, so it stays advisory (mdv check --fail-on warning to fail on it).
<!-- mdv: section required -->
## Findings
<!-- mdv: list items.all=@evidence/specific items.all=@evidence/cited error=vague-evidence -->
- Throughput rose 18% after the cache landed [1].Per-item word floor
items. catches stubs: an item too short to say what was found.
When to reach for it
When bullets are proof: verification steps, incident timelines, findings. @evidence/ is English-biased; drop it for other languages and keep @evidence/.
Frontmatter
Validate YAML metadata keys with front directives, including presence, allow-lists, dates, placeholders, patterns, and closure.
Grounded templates
Bind logical source names to real data — files, commands, loaders, or in-memory values — so a contract checks claims against current truth, not just shape.