Verification & Quality: Evidence Before Assertions

Introduction: Four Skills, One Argument

Most incident postmortems end with the same quiet word: assumed. We assumed the change was small, that the reviewer actually looked, that the container restarted cleanly, that the test we wrote after the code even tests anything. The Superpowers verification quality theme exists to remove that word from the vocabulary of “done.” It groups four skills — test-driven development, requesting-code-review, receiving-code-review, and verification-before-completion — around a single argument: evidence before assertions, always.

The four skills are not four flavors of the same test. Each fires at a different moment in the life of a change, which means each catches a different class of defect. TDD prevents bugs at creation time. Code review catches design problems that no test can see, because the tests were written inside the same design. Verification catches the gap between the artifact and the claim about the artifact. Together they cover the timeline of the work; drop one and you open a window where a defect class travels undetected.

The Stack at a Glance

Each layer is defined by the moment it fires, the bugs it catches, and the evidence it produces:

Notice that the layers do not overlap much. A reviewer reading a pinned commit range cannot observe a production incident. A test suite cannot tell you that the interface it verifies is the wrong interface. A verification command cannot catch a bug you never thought to check for. Defense in depth only works when each layer guards a different door.

Layer One: TDD Prevents Bugs at Creation

The test-driven-development skill carries its own iron law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. You write one minimal test for one behavior, you watch it fail, and only then do you write the smallest code that makes it pass. Then you refactor under the safety of green. The cycle is RED → GREEN → REFACTOR, and every transition is verified, not assumed.

The non-negotiable step is watching the failure. The skill’s core principle: if you didn’t watch the test fail, you don’t know if it tests the right thing. A test written after the code passes immediately — which proves nothing. It might assert on a mock instead of behavior, exercise the implementation instead of the requirement, or miss the edge case you forgot. You cannot forget a case you never tried to discover; a failing test is evidence that the test can catch the bug before the code claims it can’t happen.

TDD also leaks usefully into the other layers, because it is a design instrument as much as a testing one. The skill is blunt about it: hard to test = hard to use. If a test needs to mock the entire world, the design is too coupled — which is exactly the kind of finding code review should hear about. And the discipline is not limited to code: the same failing-check-first loop applies to infrastructure, where validating a compose file or running nginx -t before reload is TDD for configs.

Layer Two: Code Review Catches Design Problems

Tests prove the code does what the author thought to check. Review answers the question tests structurally cannot: is this the right thing to have built? The requesting-code-review skill operationalizes that question. A review request is not “PTAL” — it is a structured brief: the change pinned to a BASE_SHA..HEAD_SHA range, the requirements to grade against, and evidence of what was tested and which edge cases were considered. The reviewer gets precisely crafted context, never the author’s session history, so it evaluates the work product instead of inheriting the author’s blind spots. Findings come back by severity: Critical fixed immediately, Important before continuing, Minor noted.

The handshake has a second half. The receiving-code-review skill treats feedback as a claim, not a command. The prescribed response is READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT: check every suggestion against codebase reality before touching anything. Performative agreement is literally forbidden — “You’re absolutely right!” is listed as a failure response, because it is a social performance standing in for a technical check. A suggestion that breaks existing functionality, violates YAGNI, or conflicts with an architectural decision gets pushed back on with reasoning and, ideally, a test that proves the point.

Why does this matter to a quality theme? Because a review implemented blind is a new bug with a nicer commit message. The receiver is the verification layer for the reviewer’s own assertions.

Layer Three: Verification Catches the Claim Gap

The verification-before-completion skill has the strictest rule in the whole Superpowers library:

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you have not run the verification command in this turn, you cannot claim it passes. Its gate function is mechanical: identify the command that would prove the claim, run it in full, read the entire output and the exit code, confirm the output actually supports the claim, and only then speak. Skipping any step is not abbreviated verification — it is the absence of it.

The skill’s table of common failures reads like a confession booth: “tests pass” requires fresh output showing zero failures, not last hour’s green run. “Bug fixed” requires the original symptom test passing, not “the code changed, assumed fixed.” And most relevant to agent-driven work: “agent completed” requires a version-control diff you actually inspected — a subagent reporting “success” is, by definition, not evidence. The red flags are linguistic: should, probably, seems to, and the telltale satisfaction of “Great! Done!” emitted before anything was run.

The Shared Axiom: Evidence Before Assertions

Step back and the four iron laws turn out to be one sentence wearing four uniforms:

Even the rationalization tables rhyme. TDD’s “I’ll test after” and verification’s “should work now” and review’s “I’ll just check the diff myself” share one grammar: a feeling proposed as a substitute for an artifact. Each skill’s rebuttal is the same — confidence is not evidence; run the check. That uniformity is the actual theme: the Superpowers verification quality theme is not four procedures, it is one epistemology applied at four moments.

Real Example: 32 Containers, One Command

The audit that grounds this whole series ended on a verification gate. The target: SYNAS, a home OpenMediaVault server running 32 Docker containers across 26 networks — game servers, a tactical RMM stack, checkmk monitoring, Portainer, n8n, vaultwarden. The claim on the table: “the system is stable.” The cost of asserting that claim falsely is a very bad afternoon, so it was not allowed to be asserted — only evidenced.

Throughout the audit, the layers stacked. Parallel subagents audited storage and network topology and each reported everything nominal — and the coordinator treated those success reports as claims to verify, not findings to publish, checking what was actually examined. Config work followed the test-the-check-first discipline: validate before you declare. The status report itself was graded against explicit review criteria rather than the author’s satisfaction.

Then came the final gate, run fresh, read in full:

$ docker ps -a | grep -ci 'up'
32

$ docker ps -a | grep -c 'unhealthy'
0

$ docker ps -a --format '{{.Status}}' | grep -c 'Restarting\|Exited'
0

Then the report read every container’s status line rather than trusting the counts alone, and recorded the evidence as a table:

Only after that output existed did the report say “All containers are healthy and running.” The sentence looks identical to what you would have typed without the gate. The difference is that now it means something: it inherits a passing check the way a verdict inherits a trial.

Why the Superpowers Verification Quality Theme Holds Together

The four layers form a pipeline ordered by time, not by redundancy. TDD acts while the code is being written; review acts at the boundary between tasks; reception acts when feedback arrives; verification acts at the moment language about completeness is about to leave the building. A defect that slips past creation-time tests (because it is a design problem) meets review. A review suggestion that is wrong meets verification-by-receiver. Anything still alive at the end meets the gate.

The failure modes of skipping a layer are correspondingly specific:

• Skip TDD: you get tests-after, which answer “what does this do?” instead of “what should this do?” — coverage with no proof the tests can fail.
• Skip requesting review: design flaws compound, because tasks three through eight quietly build on task two’s wrong interface.
• Skip receiving discipline: correct intentions produce broken implementations — the fix nobody verified.
• Skip verification: reports become fiction by omission, because an unverified “done” is indistinguishable from a guessed one.

Because the moments are disjoint, the overhead is small: each layer costs seconds at its own trigger point, and each buys evidence no other layer can produce. That is the honest economics of why teams running this stack ship fewer hotfixes — not diligence as a virtue, but checkpoints positioned where each class of bug is cheapest to catch.

Adopting the Stack Without the Framework

You can take the theme without importing the skills. Three habits carry most of it. First, write the check before the thing: a failing test, a dry-run command, a curl that should 404 today — whatever would prove you are testing something real. Second, never accept feedback — from a reviewer, a linter, or an AI — as a command: verify it against your codebase, push back with evidence when it is wrong, and re-test after each applied fix. Third, treat every status word as a promise you have to show output for. If a teammate can adopt those three sentences, the framework is optional; the theme is not.

Related Deep Dives in the Series

• Verification before completion — the gate: identify, run, read, verify, claim. The theme’s last line and its opening argument.
• Test-driven development — the creation-time layer: no production code without a failing test first.
• Requesting code review — the boundary layer: pinned SHAs, explicit requirements, evidence attached, findings by severity.
• Receiving code review — the feedback layer: evaluate technically, verify before implementing, argue with reasoning.
• Adjacent: finishing-a-development-branch applies the same gate to the merge decision itself, and the full Skills We Use series index collects all nineteen articles.

Frequently Asked Questions

Q: Don’t these four skills overlap so much that you’re just checking things four times?
No — overlap is the intuition, and time is the answer. Each skill verifies a different assertion at a different moment: “this behaves correctly” (TDD, at creation), “this is the right design” (review, at the boundary), “this feedback is correctly applied” (reception, at feedback time), “this is actually finished” (verification, at claim time). Four checks, four disjoint questions. Re-running the same check four times would indeed be waste; the stack deliberately never repeats a question.

Q: Doesn’t evidence-before-assertions grind delivery to a halt?
It front-loads seconds to prevent hours. Watching a test fail costs one command; discovering in production that the test never tested anything costs a day. The audit example is typical: the entire verification pass was three commands and one full read of docker ps -a output — the cheapest four minutes in the whole engagement.

Q: Does this survive contact with solo work, with no subagents and no colleagues?
Yes, and solo work is where it matters most, because solo work has no accidental second pair of eyes. The reviewer subagent in requesting-code-review exists precisely to manufacture the fresh perspective a team gives you for free. TDD, re-testing feedback (even your own yesterday-feedback), and the verification gate all need no infrastructure — only a terminal and a refusal to say “should be fine.”

Key Takeaways

• The Superpowers verification quality theme unifies four skills under one rule: no assertion without fresh, read-in-full evidence from the check that would prove it.
• TDD prevents bugs at creation time and proves each test can fail; its iron law is “no production code without a failing test first.”
• Requesting-code-review catches design problems at task boundaries using pinned SHAs, explicit requirements, and severity-banded findings; receiving-code-review stops blind implementation of the feedback.
• Verification-before-completion closes the claim gap: never trust an agent report, never trust last turn’s green run, never say “should pass.”
• Real proof, literally: the SYNAS audit’s final docker ps -a pass turned “system is stable” from a vibe into a table — 32/32 containers up, zero unhealthy, zero restarts in 48 hours.

Next in this series: the Systematic Debugging theme — what to do when the evidence says something is wrong. Read the four skill deep-dives linked above for the full procedure behind each layer.