Verification Before Completion
When to use
- Never skip, even before a plan's next task. Step 1.3 decides which checks run, not the size of the change: a one-line fix still runs the smallest check that could fail.
- A change visible in a running GUI or TUI adds
visual-ui-verificationto the checks Step 1.3 picks.
Available scripts
scripts/state-identity.sh— captures and re-checks the state identity (a hash of the working-tree content; with--committed, the commit) in Steps 1.4 and 2.4.
Step 1: Pin down the claim
List every item the request asked for, including anything added later, with one row for each variant an item names or the code keeps in parallel (sync and async, each platform, each caller). Record a decision for each row: delivered, pending, blocked, or declined with a reason.
Keep an evidence record (the ledger): add to it, never rewrite it, and keep it outside the state under check. One task with one required check: one row in your reply holds the claim, the check, the state identity, and the raw result; ignore steps that name a full-record field. An integration, a release, or more than one check: open the full record,
assets/evidence-ledger.md, before the first check runs and fill every field.Add one
Resultsrow per check that the task, the plan, or the project's standing schedule of checks requires here. A required check that is missing, only planned, blocked, or unexplained makes the claim pending before anything runs. If the requirement names a person who must accept the work, readreferences/manual-acceptance.mdbefore its row.A check counts for a changed file only if its configuration includes that file. Add a row for every project check whose configured scope includes a changed path, even one nothing listed. If that check already reports errors on the base, run it on the base in a separate worktree, never by switching the state under check, and compare the two error lists instead of expecting zero: an error the base lacks fails the row; an inherited one that matches an approved pre-existing exclusion in the workspace record stays listed and limits the claim to "no new errors"; one with no exclusion is an unexplained red: list it and keep the claim pending.
Capture and record the state the checks will run on; add
--committedwhen it is a commit:bash scripts/state-identity.sh --quietFill
Statewith what the script cannot see.
Step 2: Run the checks
Reuse an earlier result only while the record's
Invalidationlist still allows it here, and record why. Run the rest fresh.If a check times out, fails partway, runs in the background, or changes something it should not, read
references/unsettled-runs.mdbefore recording its row. If it fails again with nothing changed, diagnose or return pending; never rerun until one passes.Read the raw output, not the exit code, and record the run in its row; redact only the copy you show your human partner. If an assertion could not have failed for this code, or the runner replayed a cached result or skipped the test, say so and do not count its green; repairing the task's own test belongs to
test-driven-development, and repairing a project or battery gate toverification-strategy.If a reading is zero, empty, or "no errors", count it only after the same probe, run the same way, returned a hit on a known-positive input. A surface the run never exercised is unverified, not clean: name it in the row. If the tool that acted reports a value (rows written, a file saved, a setting applied), count it only once you read it back through an independent path.
Re-check the state with the flags used at capture:
bash scripts/state-identity.sh --compare {{recorded value}}Any nonzero exit leaves the claim pending; follow
references/unsettled-runs.mdfor that exit code before anything else. Never commit to make the identities match. On 0, compare the otherStateinputs yourself.
Step 3: Claim and return
A required check that failed, did not run, or ran on another state makes the result red: not complete. Fill
Inventory reconciliation.Write the claim the rows support and nothing wider: what passed, on which state identity, what is pending.
An off-by-one fix to
due_date:pytest tests/test_due.py::test_last_dayon commit4f2a9c1prints1 passed. That supports "the test passes on4f2a9c1", not "fixed": nothing shows that test failing before the fix, and the rest of the suite has not run.A checkpoint commit reuses rows whose check reads only file content, and only when
--compare {{recorded value}} --committedexits 0; once it does, record each reused row again under the committed revision. Commit, CI, and review checks bind to their own revision.REQUIRED — return the record; this skill routes nowhere. Every unmet check goes back with it, failed and inconclusive rows intact, to the pending step of whatever asked; never invoke that caller.
using-sdlc-skillsroutes what follows; onlyrelease-readinessdecides release.Run no commit, push, PR, or merge from this skill.
Gotchas
- A partial commit leaves reviewed files uncommitted while the hash still
matches; only
--committedproves a commit holds a row's state.
Hard stops
- Never report done while any requested item has no recorded decision.
- Never claim a test passes without seeing it pass on the recorded state.
- Never claim a bug fixed without a reproduction that failed before and passes after, plus exact evidence of the control and that the fixed code was restored after the failing run.
- Never turn a worker's "success" report into evidence; inspect its diff, state, and raw output.
- Never change the state under check with the bookkeeping meant to prove it.
- A check never seen to fail for the defect it guards is suspect. Read
references/hollow-verification.mdbefore citing its green. - An empty or zero result is a claim about the instrument until a positive
control shows it can see the population in the environment the system runs
in. Output you produced by hand shows you can run the command, not that the
system acted. Read
references/hollow-verification.mdbefore citing either. - A check silenced is not a check passed. Suppressing a finding, lowering a strictness setting, or excluding a path changes what ran, not what is true; the claim that check supported is now unproven.
- A flaky green is unexplained nondeterminism; send it through
debugging. - Verified is not reviewed. Off
using-sdlc-skills' short route, a completion or integration boundary needsrequesting-code-review; a task's checks passing is not that boundary unless its plan says so.
When tempted to skip
| Thought | Reality |
|---|---|
| "It should work" | Run the check and make it a fact. |
| "I ran it earlier" | The state may have moved since, the result may be too old, or it may not cover this claim. |