Verify Spec
Goal
Show me, for each requirement, the evidence that the change does what the spec says. A
statement of done from the session that wrote the code is not evidence.
Quick start
Do the sections in order. First find the criteria and the change:
ls -t specs 2>/dev/null | head -5
B=$(git merge-base HEAD origin/HEAD 2>/dev/null || echo HEAD)
git status --short && git diff --stat "$B"
- DO use the spec that I name, or the spec in
specs/ that this change was built from; ask
me when two specs fit
- DO write the requirements from my request as a numbered list in a temporary file when
there is no spec, and show that list in the report as criteria that you assumed
- DO check that the diff holds the full change, the commits of the branch and the files
that are not committed; name the base yourself when
origin/HEAD is not set
- DO stop and ask me when the spec and the change are about different work
How to collect the evidence
Run the checks that the project has, and each line under Check in the spec, and save the
literal output in a temporary file. Leave out a check that the project does not have:
build the result line, with each error and each new warning
tests the numbers that passed and failed, and the result of each test for an edge case
lint the result line
app for each action under Check: what you did, and what you saw
- DO follow
CLAUDE.md and the project for how to build, test, lint, and run the app
- DO use the changed behaviour in the running app as a user does, when the project has a
way to run it; a build that succeeds and tests that pass do not show that a screen works
- DO call the changed behaviour from a small program outside the repository, when the
project is a library with no app to run
- DO write
NOT CHECKED with the reason when you cannot run a check here, such as a check
that needs a device; a check that did not run is not a pass
- DO save what you did and the output, and not your summary or the result that you
expected; the reviewer reads this file, and an expected value gives it your reading of the
spec
How to get an independent review
Save the tree that the reviewer sees, start a subagent that did not write the code, and give
it this brief with the paths filled in:
I=$(mktemp) && cp "$(git rev-parse --git-path index)" "$I"
GIT_INDEX_FILE=$I git add -A && GIT_INDEX_FILE=$I git write-tree
You review a change that you did not write. Report only: do not edit a file in the
repository, and put each file that you make outside it.
Repository: <path>. Spec: <path>. Evidence: <path>.
Change: `git diff <base>`, and the untracked files in `git status --short`.
For each numbered requirement, find the code that implements it, and give PASS, FAIL, or
NOT CHECKED with the evidence: the file and line, a command and its output, or what the
evidence file shows for the running app.
For each edge case, name the test that covers it, and give its result. An edge case with no
test is a FAIL.
Give a verdict for each line under Constraints and Out of scope also. A line under
Deviations that ends with `Accepted` is a decision of the owner, and not a gap.
Look for a stub: a fixed return value, an empty handler, or a branch that the spec needs and
the code does not have.
Report only a gap that affects correctness. Skip style.
Keep each real problem at its severity. Do not decide that it is acceptable.
For a review after a fix, give this brief in its place:
You review a fix to a change that you did not write. Report only: do not edit a file in the
repository, and put each file that you make outside it.
Repository: <path>. Spec: <path>. Evidence: <path>.
The report of the review before this one: <path>. The fix: `git diff <tree before> <tree now>`.
Give PASS, FAIL, or NOT CHECKED with the evidence for each earlier FAIL and NOT CHECKED, and
for each requirement, edge case, and constraint that the fix touches. Copy each other
verdict from the earlier report, and do not check it again.
Report only a gap that affects correctness. Skip style.
Keep each real problem at its severity. Do not decide that it is acceptable.
- DO ask me, before you start the review, about each line under Deviations that goes
against a requirement, and show me what the evidence says about it; when I accept it, change
the requirement in the spec to match and write
Accepted at the end of that line under
Deviations, and when I reject it, change the code. A review costs much more than a
question, and my answer decides what it checks
- DO give a reviewer its brief only; a reviewer that reads the main conversation or your
reasoning repeats your assumptions
- DO run the two commands before each review; they print the tree that the reviewer sees
and change nothing, and the two trees give the fix to the next reviewer
- DO save the report of each review in a file as the reviewer wrote it; a review that
builds on the last one costs less and finds more
- DO start the reviewer on a model that is not the model of this session, when one is
available; a model rates its own work too high, and a second model has other blind spots
- DO check that each
PASS from the reviewer names its evidence; agreement between two
models is not proof
- DO do the review yourself when you cannot start a subagent, and say in the report that
the review was not independent
How to fix a failure
- DO fix the code for each
FAIL, and add each test that is missing; do not change a
requirement, or a test that is there, to get a pass
- DO stop and ask me when you think that the spec is wrong, or when a requirement has two
readings and the code satisfies only one; I decide if the spec or the code changes
- DO collect the evidence again after each fix, and get the review again when the fix
changed code, because a fix can break a requirement that passed; a fix that only adds a test
needs the test run and not a review
- DO stop after the third review and report what still fails; a failure that survives
two fixes needs a decision from me
- DO NOT change code for a finding that does not affect correctness; to fix each finding
of a reviewer adds layers, and tests for cases that cannot occur
How to report
# | Requirement | Verdict | Evidence
1 | The session survives a restart | PASS | SessionTests.testRestore passed; home screen after relaunch
2 | An expired token shows sign-in | FAIL | AuthStore.swift:88 has no branch for expiry; no test
3 | Sync works on a mobile network | NOT CHECKED | Needs a device: turn Wi-Fi off, then open the list
- DO give each requirement and each edge case one line, also the ones that pass
- DO quote the output line, or name the file and line, as the evidence; "the tests pass"
alone is not evidence
- DO list each file that the change touches, the small changes also, and each line under
Deviations in the spec; I review the diff from this list, and a summary leaves the small
changes out
- DO give each verdict of the reviewer as it is; when you do not agree with one, say so
below the table, with your reason
- DO end with what I must check myself, and with each finding of the reviewer that you
did not fix and the reason
- DO NOT commit; the
open-pr skill does that when I ask
Reference
| Verdict |
Use it when |
PASS |
The output of a command, or what you saw in the running app, shows the behaviour |
FAIL |
The behaviour is absent, wrong, or a stub, or an edge case has no test |
NOT CHECKED |
You had no way to observe it here; say what I must do to check it |
Copyright © 2026 Lorenzo Mazzarotto
1---2name: verify-spec3description: Verifies a finished change against its spec in a fresh context, and reports each requirement as pass or fail with the evidence. Use when asked to verify, check, or prove that a change does what was asked, or before work that was built from a spec is reported as done. Not for a small change, where the build and the tests are enough.4metadata:5 source: https://skillmd.com/skills/mazzsva/verify-spec6---78# Verify Spec910## Goal1112Show me, for each requirement, the evidence that the change does what the spec says. A13statement of done from the session that wrote the code is not evidence.1415## Quick start1617Do the sections in order. First find the criteria and the change:1819```bash20ls -t specs 2>/dev/null | head -521B=$(git merge-base HEAD origin/HEAD 2>/dev/null || echo HEAD)22git status --short && git diff --stat "$B"23```2425* **DO** use the spec that I name, or the spec in `specs/` that this change was built from; ask26 me when two specs fit27* **DO** write the requirements from my request as a numbered list in a temporary file when28 there is no spec, and show that list in the report as criteria that you assumed29* **DO** check that the diff holds the full change, the commits of the branch and the files30 that are not committed; name the base yourself when `origin/HEAD` is not set31* **DO** stop and ask me when the spec and the change are about different work3233## How to collect the evidence3435Run the checks that the project has, and each line under Check in the spec, and save the36literal output in a temporary file. Leave out a check that the project does not have:3738```text39build the result line, with each error and each new warning40tests the numbers that passed and failed, and the result of each test for an edge case41lint the result line42app for each action under Check: what you did, and what you saw43```4445* **DO** follow `CLAUDE.md` and the project for how to build, test, lint, and run the app46* **DO** use the changed behaviour in the running app as a user does, when the project has a47 way to run it; a build that succeeds and tests that pass do not show that a screen works48* **DO** call the changed behaviour from a small program outside the repository, when the49 project is a library with no app to run50* **DO** write `NOT CHECKED` with the reason when you cannot run a check here, such as a check51 that needs a device; a check that did not run is not a pass52* **DO** save what you did and the output, and not your summary or the result that you53 expected; the reviewer reads this file, and an expected value gives it your reading of the54 spec5556## How to get an independent review5758Save the tree that the reviewer sees, start a subagent that did not write the code, and give59it this brief with the paths filled in:6061```bash62I=$(mktemp) && cp "$(git rev-parse --git-path index)" "$I"63GIT_INDEX_FILE=$I git add -A && GIT_INDEX_FILE=$I git write-tree64```6566```text67You review a change that you did not write. Report only: do not edit a file in the68repository, and put each file that you make outside it.69Repository: <path>. Spec: <path>. Evidence: <path>.70Change: `git diff <base>`, and the untracked files in `git status --short`.71For each numbered requirement, find the code that implements it, and give PASS, FAIL, or72NOT CHECKED with the evidence: the file and line, a command and its output, or what the73evidence file shows for the running app.74For each edge case, name the test that covers it, and give its result. An edge case with no75test is a FAIL.76Give a verdict for each line under Constraints and Out of scope also. A line under77Deviations that ends with `Accepted` is a decision of the owner, and not a gap.78Look for a stub: a fixed return value, an empty handler, or a branch that the spec needs and79the code does not have.80Report only a gap that affects correctness. Skip style.81Keep each real problem at its severity. Do not decide that it is acceptable.82```8384For a review after a fix, give this brief in its place:8586```text87You review a fix to a change that you did not write. Report only: do not edit a file in the88repository, and put each file that you make outside it.89Repository: <path>. Spec: <path>. Evidence: <path>.90The report of the review before this one: <path>. The fix: `git diff <tree before> <tree now>`.91Give PASS, FAIL, or NOT CHECKED with the evidence for each earlier FAIL and NOT CHECKED, and92for each requirement, edge case, and constraint that the fix touches. Copy each other93verdict from the earlier report, and do not check it again.94Report only a gap that affects correctness. Skip style.95Keep each real problem at its severity. Do not decide that it is acceptable.96```9798* **DO** ask me, before you start the review, about each line under Deviations that goes99 against a requirement, and show me what the evidence says about it; when I accept it, change100 the requirement in the spec to match and write `Accepted` at the end of that line under101 Deviations, and when I reject it, change the code. A review costs much more than a102 question, and my answer decides what it checks103* **DO** give a reviewer its brief only; a reviewer that reads the main conversation or your104 reasoning repeats your assumptions105* **DO** run the two commands before each review; they print the tree that the reviewer sees106 and change nothing, and the two trees give the fix to the next reviewer107* **DO** save the report of each review in a file as the reviewer wrote it; a review that108 builds on the last one costs less and finds more109* **DO** start the reviewer on a model that is not the model of this session, when one is110 available; a model rates its own work too high, and a second model has other blind spots111* **DO** check that each `PASS` from the reviewer names its evidence; agreement between two112 models is not proof113* **DO** do the review yourself when you cannot start a subagent, and say in the report that114 the review was not independent115116## How to fix a failure117118* **DO** fix the code for each `FAIL`, and add each test that is missing; do not change a119 requirement, or a test that is there, to get a pass120* **DO** stop and ask me when you think that the spec is wrong, or when a requirement has two121 readings and the code satisfies only one; I decide if the spec or the code changes122* **DO** collect the evidence again after each fix, and get the review again when the fix123 changed code, because a fix can break a requirement that passed; a fix that only adds a test124 needs the test run and not a review125* **DO** stop after the third review and report what still fails; a failure that survives126 two fixes needs a decision from me127* **DO NOT** change code for a finding that does not affect correctness; to fix each finding128 of a reviewer adds layers, and tests for cases that cannot occur129130## How to report131132```text133# | Requirement | Verdict | Evidence1341 | The session survives a restart | PASS | SessionTests.testRestore passed; home screen after relaunch1352 | An expired token shows sign-in | FAIL | AuthStore.swift:88 has no branch for expiry; no test1363 | Sync works on a mobile network | NOT CHECKED | Needs a device: turn Wi-Fi off, then open the list137```138139* **DO** give each requirement and each edge case one line, also the ones that pass140* **DO** quote the output line, or name the file and line, as the evidence; "the tests pass"141 alone is not evidence142* **DO** list each file that the change touches, the small changes also, and each line under143 Deviations in the spec; I review the diff from this list, and a summary leaves the small144 changes out145* **DO** give each verdict of the reviewer as it is; when you do not agree with one, say so146 below the table, with your reason147* **DO** end with what I must check myself, and with each finding of the reviewer that you148 did not fix and the reason149* **DO NOT** commit; the `open-pr` skill does that when I ask150151## Reference152153| Verdict | Use it when |154| --- | --- |155| `PASS` | The output of a command, or what you saw in the running app, shows the behaviour |156| `FAIL` | The behaviour is absent, wrong, or a stub, or an edge case has no test |157| `NOT CHECKED` | You had no way to observe it here; say what I must do to check it |158159Copyright © 2026 Lorenzo Mazzarotto