Verify Before Done

Verify Before Done

Self-reported success is the most expensive lie in agentic coding: an agent that grades its own homework will, on a long enough timeline, tell you something works when it doesn't. This skill replaces "I believe this is done" with "here is the evidence this is done."

When to use this

• You're about to write "fixed", "done", "working", "tests pass", "should work now", or similar, at the end of a turn.
• You implemented something and are tempted to report success based on reading the code rather than running it.
• A user asks you to verify, double-check, or confirm that something works.

Instructions

1. Name the claim. Before finishing, state precisely what you're claiming is true ("the login form now rejects invalid emails", "the flaky test no longer flakes"). A vague claim ("I fixed it") can't be verified — a specific one can.

2. Get evidence, not confidence. Climb this ladder as far as the task allows — don't stop at a lower rung when a higher one is available. See references/evidence-ladder.md for the full breakdown with examples.

   • Rung 0 — Unverified assumption: "this should work." Never report this as done.
   • Rung 1 — Static read: re-read the diff and reasoned it's correct. Weak on its own.
   • Rung 2 — Automated check: ran the test suite / linter / type-checker and it's green.
   • Rung 3 — Reproduced the scenario: reproduced the original failure, applied the fix, reproduced again, and it's now gone — captured real output, not paraphrased.
   • Rung 4 — Independent review: a fresh reviewer (different context, ideally a separate agent) checked the result against the original ask and didn't just rubber-stamp the implementer's own summary.

3. When you can spawn an independent reviewer, do it for anything non-trivial. If your environment supports launching a separate agent/subagent with its own context (e.g. Claude Code's Agent tool, a forked session, a second CLI session), hand it the original request and the diff — not your summary of what you did — and ask it to check independently, read-only. See references/independent-review.md for a ready-to-use prompt template and for what to do when no such capability exists (a "cold read": step away, re-read the diff as a skeptical stranger, actively try to break it).

4. Report the evidence, not the verdict. Don't just say "done" — say what you ran and what it showed. Compare:

   • Weak: "Fixed the bug."
   • Strong: "Reproduced the crash with pytest tests/test_login.py::test_bad_email (failed before), applied the fix, re-ran it — now passes. Full suite: 142/142."

5. If you can't verify, say so explicitly. "I made this change but couldn't run the test suite (no test runner in this environment) — here's what I'd check" is honest and useful. "Done" when you didn't actually check is the failure mode this skill exists to prevent.

6. Match verification weight to the change. A one-line typo fix doesn't need an independent reviewer; a multi-file refactor or anything touching auth, payments, or data migrations should reach Rung 3 or 4 before you call it done. See references/evidence-ladder.md for calibration guidance.

Examples

Weak report (what this skill prevents):

I updated the validation regex. The email field should now reject invalid addresses. Done!

Strong report (what this skill produces):

Reproduced the original bug: test@ was accepted (test failed as expected). Updated the regex in validators.py:42. Re-ran the test — now fails on test@ as expected and still accepts user@example.com. Full validation suite: 18/18 passing.

Edge cases

• No test infrastructure exists. Don't invent confidence you don't have. Manually exercise the code path if possible (run the script, hit the endpoint, render the component) and report exactly what you observed.
• The task is genuinely trivial (fixing a typo, renaming a variable with no callers). A quick static read is proportionate — don't manufacture ceremony. State plainly that verification was lightweight and why.
• Verification itself is flaky or slow. Say so and report what you did verify, rather than silently skipping the step or claiming a false pass.
• You're the one who wrote the code. You're the worst-positioned person to judge it objectively — this is exactly why Rung 4 (independent review) exists. Prefer it whenever the capability is available.

Reference files

• references/evidence-ladder.md — the five verification tiers in depth, with worked examples and guidance on how much evidence a given change warrants.
• references/independent-review.md — how to get a genuinely independent check: a prompt template for spawning a fresh reviewer agent, and a "cold read" protocol for when no sub-agent capability exists.