| name | reality-check |
| description | Assess where a project actually stands against what its README, plan, or pitch promises, with every claim tested against the artifact itself rather than the docs, reported in chat and as an HTML page per the html-explainer standards. Use when someone asks "where are we", "are we on track", "what's missing", "does this actually work", or before a demo, a handoff, or a decision that assumes the project is further along than it might be. With no argument, check the project in the current directory. |
| argument-hint | [project path, repo, or plan to check against] |
| model | claude-opus-4-6 |
| allowed-tools | Read, Grep, Glob, Bash, Write |
Reality Check
Task: $ARGUMENTS
With no argument, the project is the current working directory; run
from any worktree at any time. With an argument, it is the path, repo,
or plan named.
A project's documents describe the project its authors intended. The
project that exists is whatever survives being run, read, and poked at
today. This skill measures the distance between the two, and it never
takes the documents' word for anything.
The writer and the checker
The page and the chat report are written by Opus 4.6; it writes better.
The frontmatter pins it for direct runs. When an orchestrator or a
session on another model runs this skill, the checking (promise
testing, evidence gathering) stays with the capable model and only the
writing is handed to an Opus 4.6 session (claude -p --model claude-opus-4-6 with this skill and the complete findings).
Opus 4.6 forgets things, and that is the dispatcher's problem, not the
reader's: hand it the findings as a complete numbered list with every
verdict and its evidence line, and after it writes, diff the page
against that list. Every finding present, every verdict unchanged, no
evidence softened. A dropped or drifted finding goes back to the same
session as a correction until the diff is clean.
Establish the promise
Collect every place the project says what it is: README, plan, brief,
pitch, roadmap, open PR descriptions, the landing page if there is one.
Distill them into a numbered list of concrete promises, each one
falsifiable. "Users can install with one command" is a promise.
"Modern, fast architecture" is not; drop vagueness rather than grading
it.
A promise is the document as it stands. When the ground truth moved
after the document was written (a PR body quoting copy that later
commits rewrote, a README describing a renamed command), that drift is
itself a Contradicted finding: the document is asking for sign-off on
something that no longer exists.
Test the promise
For each promise, go find out, in the artifact, not the docs:
- Works: you ran it, read it, or traced it end to end, and it holds.
Name the evidence (the command and its output, the file:line, the
passing test).
- Exists but unproven: the code or page is there, and nothing
demonstrates it works. Say what proof is missing.
- Partial: some of the promise holds; state exactly which part does
not.
- Absent: nothing implements it. Note whether anything even refers
to it.
- Contradicted: the artifact does the opposite of the promise. These
outrank everything else in the report.
- Untestable here: the promise needs something this environment does
not have (owned assets, credentials, hardware). Name what would test
it, and report whatever partial corroboration the artifact does
offer; untestable is a fact about the check, never a soft pass.
Run the cheapest honest test first: the install one-liner in a clean
temp directory, the quickstart verbatim, the demo path as a stranger
would walk it. A promise you could test in two minutes and didn't is a
finding about the check, not the project.
Find the unpromised
Walk the artifact once in the other direction: what exists that no
document mentions? Undocumented features, half-built directions,
abandoned scaffolding. These are either wins nobody is claiming or
weight nobody is admitting, and the report says which.
The report
Open with one paragraph a stakeholder could forward: how far along this
project actually is, in plain words, no percentages invented from
nothing. Then:
- the promise list with verdicts and evidence, contradictions first
- the unpromised findings
- the three gaps most worth closing next, each with why it is the one
blocking the story the docs tell
- what the docs should stop claiming today, if anything
Deliver it twice: in chat, and as a page in the project's ./tmp/
(gitignored location of the caller's choice otherwise), rendered per
the html-explainer skill and opened in the browser. On the page:
- Masthead: project name, checked-at date, and one badge summarizing
the stance (holds, mostly holds, diverges, contradicted).
- Opening diagram: promises as a strip, each colored by verdict, so the
shape of the gap is visible before a word is read.
- One card per promise: the promise verbatim, the verdict badge, the
evidence line. Contradictions first, then absences, then the rest.
- Unpromised findings and the three gaps as panels; stop-claiming items
as a warn callout.
- Raw evidence (command output, file excerpts) inside
details.
Boundaries
- Evidence over inference: every verdict cites something you ran or
read. If you could not test a promise, say so and say why; never
downgrade it to a guess.
- Check the artifact as it is on the branch you were pointed at, not as
in-flight work will make it.
- This skill reports; it does not fix. Turning gaps into work items is a
separate step the user asks for.
- No em dashes.
