Verification Before Completion: Evidence Before Claims

Introduction: The Most Expensive Word in Engineering

“Done” is the most expensive word in software. Not because saying it is hard, but because saying it cheaply is so tempting. The tests were green twenty minutes ago. The linter is quiet. The subagent reported success. The fix should work now. Every one of those sentences ends with a completion claim that no fresh command has backed — and most incident postmortem timelines contain one of them.

The Superpowers verification-before-completion skill exists to make that class of lie impossible to tell casually. It is the shortest discipline in the series and arguably the most load-bearing: no completion claim without fresh verification evidence, run and read in this same turn. This article is a deep dive into how the skill enforces that — the Iron Law, the five-step gate function, the failure modes it is designed to catch — and how a single grep -c at the end of a container audit turned “we believe the server is healthy” into a defensible claim.

What the Verification-Before-Completion Skill Actually Does

The skill lives at software-development/superpowers-verification-before-completion, and its SKILL.md opens with a sentence that leaves no room for interpretation: claiming work is complete without verification is dishonesty, not efficiency. That framing is deliberate. The skill refuses to treat verification as a quality nicety you do when there is time; it treats an unverified “it works” as a false statement, full stop.

The core principle is two words long: evidence before claims, always. And the skill closes the escape hatch immediately after opening it — “violating the letter of this rule is violating the spirit of this rule.” There is no version of this discipline where you skip the command because you are confident, because the change was small, or because you already checked something adjacent. Confidence is a feeling; verification is an output. Only one of them can be pasted into a report.

Where the executing-plans skill governs the middle of a job — work the list, check the boxes — this skill governs the two most dangerous moments: every per-task “checked off” along the way, and the final “done” at the end. It is the companion discipline that makes every other Superpowers skill honest.

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Two words in that law do all the work. Verification evidence means the actual output of the actual command: exit code, failure count, the lines the tool printed. Not a mental model of what the command would print. Not last week’s run. Fresh means the clock is reset by every claim — the skill is explicit: if you haven’t run the verification command in this turn, you cannot claim it passes.

The freshness requirement is what separates this from generic “test your code” advice. Stale evidence is how experienced engineers get caught: you ran the suite before lunch, and since then you merged a branch, rebased, and hand-edited a config. That green run is evidence about a codebase that no longer exists. The Iron Law makes that distinction mechanical: no fresh run, no claim, no matter how recently the old run passed.

The Gate Function: Identify, Run, Read, Verify, Claim

The skill operationalizes the Iron Law as a gate every status claim must pass through:

BEFORE claiming any status:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying

Identify sounds trivial and is secretly the hardest step, because it forces you to admit what your claim actually asserts. “The bug is fixed” is proven by re-running the exact reproduction that originally failed — not by the unit test you wrote around the suspected cause. If you cannot name the command that would prove the claim, you do not yet understand the claim.

Run means the full command, freshly: the whole suite, not the three tests you think are relevant. Read is the step everyone shortcuts — the output must be read completely, the exit code checked, the failures counted, because a tool that prints 47 passing tests and then 2 errors before exiting 1 is a tool telling you the claim is false. Verify compares the evidence against the claim honestly in both directions: when the output contradicts you, the report states the real status with the real evidence — “the test failed, here is the failure” — not the status you expected; when it confirms, the claim ships with its evidence attached. A flake you re-ran and watched disappear is evidence; a flake you asserted is a cover story.

Only after all five steps does step 5 unlock the claim itself. The closing line is the whole skill in six words: skip any step = lying, not verifying.

Common Failures: The Claims That Get Away

The skill catalogs the specific claims agents and engineers most often let through the gate — each row pairs a claim with what would actually prove it and what people substitute instead:

Claim	Requires	Not Sufficient
Tests pass	Test output showing 0 failures	Previous run, “should pass”
Build succeeds	Build command exiting 0	Linter passing
Bug fixed	The original symptom test passing	“Code changed, assumed fixed”
Requirements met	Line-by-line checklist against the plan	Tests passing alone
Agent completed	VCS diff showing the actual changes	Agent reports “success”

Read the right column as a taxonomy of the three failure modes the skill is built to kill. Trusting stale or secondhand reports — the previous run, the agent’s self-assessment. Partial verification — the linter is not a build, tests are not requirements, a diff of one file is not the whole task. And prediction dressed as result — “should pass now” is a forecast about the future, stated in the present tense. None of these feel lazy in the moment; they feel like reasonable confidence right up until they are wrong.

The skill adds a red-flag list to catch the failure in your own prose in real time: using “should,” “probably,” or “seems to”; expressing satisfaction before verification (“Great!” “Done!”); about to commit or push without verifying; relying on a partial check; and the universal precursor to every bad deploy, “just this once.” Each one is a trigger for the same action: run the verification.

Real Example: The Final Count That Made 32/32 a Fact

The audit of SYNAS — the home server detailed in the executing-plans article — is a clean case study, because its headline claim looked unfalsifiably boring: all 32 Docker containers healthy.

The audit had produced that number task by task: an early health sweep showed 32 of 32 up, and five downstream tasks built their findings on top of it. By every normal measure, the claim was supported. By the Iron Law, it was a claim about the present resting on evidence from the recent past — during a multi-task audit, containers restart and crash.

So before the report was finalized, the gate ran one more time, end to end. Identify: what single command proves “32 of 32 running right now”? docker ps -a | grep -ci 'up'. Run: execute it fresh against the live host. Read: the output was a single line — 32. Verify: 32 matches the report’s headline count of 32/32. Claim: the report states 32 of 32 containers up — with the command and its output recorded in the completion artifact committed alongside the plan.

That one command is the difference between “I believe everything is running” and “here is the count, measured seconds ago.” It also shows why the gate demands a fresh check at the end, not confidence earned along the way: no amount of diligent intermediate checking substitutes for one independent measurement of the exact claim being made.

Trusting Agents Is the New Trusting Yourself

Delegation multiplies the failure mode this skill targets. A subagent returning “task complete, all tests passing” is seductive fake evidence precisely because it arrives pre-polished — and an orchestrator that forwards it upstream without checking has laundered an unverified claim into a verified-sounding one.

The skill’s rule is blunt: agent reports “success” is not sufficient; a VCS diff showing the changes is. The Hermes Agent integration spells out the loop after every delegate_task:

Read the subagent’s summary — as a lead, not a verdict.
Check what files were actually modified, via git diff or git status.
Run the verification commands yourself, in your own session, now.
Claim only the state those commands actually show — including gaps.

The skill also closes the loop over time: record verification outcomes in memory, and when a verification method turns out to have been insufficient — it passed, yet a bug survived — record that, so the next session verifies against a stronger check. Verification discipline improves the same way tests do: every escaped bug is information about a hole in the gate.

Related Deep Dives in the Series

executing-plans runs the verification step inside every task of a plan; this skill is what makes those verifications mandatory rather than ceremonial, and its final 32/32 container count is this article’s case study.
finishing-a-development-branch is where this discipline is most concentrated: no merge, PR, or “shipped” before the finish-line checks have fresh output behind them.
systematic-debugging supplies the other half of an honest “no”: when verification fails, you investigate root causes instead of bargaining with the evidence.
Superpowers Test-Driven Development — no production code without a failing test first.
Superpowers Using Superpowers — the meta-skill: skill discovery and priority at the start of every session.

Frequently Asked Questions

Q: Isn’t re-running a command that passed five minutes ago wasteful?
The command takes seconds; a wrong “done” costs a rollback, a hotfix, or a trust deficit that never fully repays. And five minutes is exactly the window in which the next edit landed. Freshness is cheap.

Q: What counts as “fresh”?
Run after the last change you are claiming anything about, and read in the same turn as the claim. The skill’s operational line: if you did not run the verification command in this turn, you cannot claim it passes.

Key Takeaways

The Superpowers verification-before-completion skill enforces one rule: no completion claims without fresh verification evidence — and treating the letter of the rule as the spirit of it.
The gate function is five steps — identify the proving command, run it fully, read all of it, verify it confirms, then claim with evidence attached. Skipping a step is lying, not verifying.
The classic leaks are trusting prior runs, trusting agent reports, partial checks, and “should pass now” — each has a named substitute that actually proves the claim.
One fresh docker ps -a | grep -ci 'up' returning 32 turned a 32-container health claim from belief into measurement; that is the entire skill in one command.
Delegation raises the stakes: verify subagent output with diffs and your own runs before anything gets forwarded upstream.

Next in this series: finishing a development branch — where every discipline in the series meets the merge button. Browse the full Skills We Use series index for all nineteen articles.