Evidence-Before-Claims

Overview

Core principle: You may not claim something works until you have run the proving command in this message and read its output. Evidence first, claim second — always. "Should work" is not a status; it's a hope.

The Iron Law

NO COMPLETION CLAIM WITHOUT FRESH VERIFICATION EVIDENCE

Fresh means now, in this turn — not "I ran it earlier," not "it passed last time." Code changed since then, or you wouldn't be claiming anything. A prior green run does not certify the current tree.

The Gate

Before any success claim, run this gate:

1. IDENTIFY the command that would prove the claim (the build, the test, the actual run that exercises the change — not a proxy).
2. SCOPE it to the change's blast radius — the set of behavior this edit could plausibly break. Not "the one test I wrote"; not "everything, always." See below.
3. RUN it fresh, at that scope, in full. No --fast, no bailing after the first green line.
4. READ the whole output and the exit code. Errors hide in the middle; exit code is the verdict.
5. VERIFY it actually shows what you're about to claim — the right thing passed, not just something.
6. THEN claim — and say what you ran and what you didn't.

If you can't run the proving command, you don't claim success; you say what you verified and what you didn't.

Scope by Blast Radius

Verification breadth is a judgment, not a reflex. Running everything for a typo-fix trains everyone (including you) to stop reading the output; running one test for a signature change ships the break. Ask: what could this edit plausibly falsify? Test that, plus one ring out.

Escalate when the signal is ambiguous. A failure you can't immediately explain, a flaky result, a suite you haven't run in a while, a diff that grew past what you predicted — widen to full. Cheap suites bias toward full; if the whole thing takes 30 seconds, scoping is a waste of thought.

Scope-down never applies to the final landing gate. The narrow scope proves a slice. finishing still runs the repository's prescribed gate on the tree that actually lands.

Say the Scope Out Loud

A claim inherits the scope of its evidence, so state both together:

"auth unit tests + the 3 call sites pass (17 tests). I did not run the integration suite — nothing here crosses a process boundary."

That sentence is falsifiable: the user can immediately tell you if your blast-radius call was wrong. "Tests pass ✅" hides the judgment and makes it unauditable.

This Applies to Paraphrases Too

The law covers the meaning, not just the exact word "done." "That should fix it," "all green," "ready to merge," "the tests are passing," "🎉 Perfect!" — every one is a completion claim and needs fresh evidence behind it.

Don't Trust Reports — Verify Them

When a subagent or tool reports success, that is a claim, not evidence. Verify it against reality — the VCS diff, the actual output, the running artifact. Agents can be confidently wrong; "the implementer said it's done" is not the same as "it's done."

Red Flags — STOP, You're About to Claim Without Evidence

Common Mistakes

• Verifying only the new test. The new test passing proves the feature exists, not that it left everything else standing. One ring out is the minimum.
• Reflexive full-suite as a substitute for thinking. It looks rigorous and costs nothing to type, but a 10-minute suite you don't read is weaker evidence than 30 focused seconds you do.
• Scoping by what's convenient instead of by risk. "That suite is slow/flaky/needs a DB" is a reason to fix it or flag it, not a reason to declare it out of the blast radius.
• Silent scoping. Narrowing is legitimate; hiding that you narrowed is not. Say what you skipped.
• Reading the exit code but not the output (or vice versa). You need both: green exit and the right thing in the log.
• Stale evidence. Output from before your last edit certifies nothing about the current tree.
• Claiming for the human what you'd never claim for yourself. The bar is the same whether it's a status update or a merge.