reality-checker
Certify sprint completion with evidence or refuse to. Use when closing a contract.md, marking contract criteria complete, writing the progress.md evidence column, judging "is this done", or when a rep
SKILL.mdskills/reality-checker/SKILL.md
GitHubReality Checker
Final certification pass for a sprint's contract.md: every criterion is judged on
executed evidence, never on intentions, code reading, or another report's claims.
The verdict defaults to NEEDS WORK; READY requires overwhelming proof.
This skill operationalizes §6 ("Verified" = actually executed or visually inspected) at sprint-closure time.
Workflow
- Read the frozen contract. List every
contract.mdcriterion. For each one, identify what evidence would prove it: a command exit 0, a measured number, a screenshot, a file on disk. A criterion with no definable proof is a contract defect — report it, do not improvise leniency. - Re-run the proof through the real path. Execute the repo's pinned gate commands (tests, lint, checks) yourself and capture exit codes. Re-validate fixes through the full real path, not a harness that bypasses it. A command you did not run is not evidence.
- Measure, do not estimate. Every factual claim (number, color, presence of an
asset, performance figure) needs a measurement or a screenshot kept as evidence
under the repo's declared evidence location (default
progress.mdlinks). Inspect renders and screenshots with your own eyes before citing them. - Cross-examine prior claims. Treat "zero issues found", perfect scores, and "production ready" coming from another agent or an earlier pass as a red flag, not a green light. Re-check one or two of their claims at random against the artifacts; if one fails, re-check all of them.
- Judge each criterion: PASS / FAIL / NOT PROVEN.
NOT PROVEN(evidence missing or unconvincing) is a FAIL for closure purposes. Partial implementations are FAILs, not discounts. - Write the certification into
progress.mdusing the report template below, then give the user the verdict: done · verified (how) · not verified.
Automatic fail triggers
Any one of these forces NEEDS WORK regardless of everything else:
- A criterion with no captured evidence, or evidence produced by a skipped, weakened, or modified test (never accept this — §6).
- Claims that contradict the artifacts (a "fast" feature with no timing, a "responsive" UI with no viewport screenshot).
- The gate commands do not pass right now, on the current tree.
- Scope drift: work in the diff that no contract criterion asked for.
Calibration
- First implementations typically need 2-3 revision cycles; a first pass is automatically suspect.
- Honest C+/B- ratings drive better outcomes than inflated ones. "READY" must mean demonstrated excellence, not hope.
- Surface out-of-scope improvements you notice as follow-up items — never as justification for failing unrelated criteria, never folded silently into the diff.
Report template
# Reality check - <date>
## Per-criterion verdict (contract.md)
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | <criterion text> | PASS | `cmd` exit 0 (<date>); output/log link |
| 2 | <criterion text> | FAIL | what was executed, what it showed |
| 3 | <criterion text> | NOT PROVEN | the missing measurement/screenshot |
## Gate evidence
- tests: <runner> - exit <code>
- lint: <tool@version> - exit <code>
- checks: <commands> - exit <codes>
## Issues still open
- [critical] <issue> - evidence: <artifact>
- [medium] <issue> - evidence: <artifact>
## Verdict
Production readiness: NEEDS WORK (default) / READY
Required before READY: <numbered, specific, evidence-backed fixes>
Revision cycle expected: yes/no
Hard rules
- Never certify a criterion you cannot point to executed evidence for.
- Never accept a skipped, disabled, or weakened test as proof (§6).
- Do not average, round up, or discount: one FAIL or NOT PROVEN criterion = NEEDS WORK.
- Report the state as it is; the user decides whether to close anyway.