Verification Before Completion

Prove work is done instead of asserting it. Every completion claim must be backed by captured output from verification commands run in the current session. The most expensive bugs are the ones that ship behind a confident "it works," not the ones that fail loudly.

Iron law

No "done" without evidence. Assertions are not evidence.

If you have not run a verification command and read its output in this session, you cannot claim the work passes. "Should work" is not a status. "I believe it's correct" is not a test result. The only proof is captured output from an executed command.

Why this matters

False completion costs more than incomplete work. Incomplete work is visible, so someone will finish it. False completion is invisible: it passes review, merges, deploys, and fails in production. Every minute spent on verification saves hours of debugging, rollback, incident response, and trust repair. The cost of catching a defect grows by orders of magnitude at each stage: local development, code review, staging, production. Verify early and often, with evidence.

Core Principles

Tiered definition of done

Work passes through several tiers before it is done. Each tier has its own evidence requirements. See done-definitions for the full breakdown.

The verification cycle

Run this cycle before every completion claim.

Phase 1: Identify the verification surface

Determine what needs to be verified based on what changed.

• List every file modified, added, or deleted
• Map each change to its verification category (code, config, schema, docs, infra)
• Identify the minimum set of commands that covers all changed surfaces
• If unsure what to verify, verify everything. Over-verification costs minutes, under-verification costs hours

Phase 2: Run verification commands

Run every required command. Do not skip any.

• Run commands in the project root unless they require a specific directory
• Use the project's own scripts and configuration. Do not invent custom verification
• Run the full suite, not a subset, unless the full suite takes more than 5 minutes (then run targeted tests and note that the full suite is deferred)
• Capture both stdout and stderr

Phase 3: Capture output

Record the raw output from every command.

• Include the exact command that was run
• Include the full output (or the summary section for large outputs)
• Include the exit code
• Do not fabricate timestamps; the current session is the implicit timestamp

Phase 4: Compare to expected

Check the output against the success criteria.

• All tests pass (zero failures, zero errors, zero skipped unless pre-existing)
• Zero lint errors (zero warnings for strict projects)
• Type checker reports zero errors
• Build exits with code 0 and produces expected artifacts
• If any check fails, the work is NOT done. Fix the issue and restart from Phase 2

Phase 5: Cite evidence in the claim

Reference the captured output when claiming completion.

• State which commands were run
• State the result of each (pass count, exit code, key output lines)
• If any caveats exist (pre-existing failures, skipped checks, known issues), state them explicitly
• Never use language that hides uncertainty (see Language to avoid)

What counts as evidence

See evidence-patterns for the full reference.

Verification by task type

Different changes need different verification. See verification-checklist for full checklists per task type.

Common fake-completion patterns

See failure-modes for the full catalog.

Language to avoid

Quality checklist

Before claiming any work is complete:

• All modified files are identified
• Verification commands are identified for each change type
• Every verification command has been run (not recalled from memory; run fresh)
• Output from every command is captured and visible
• All tests pass with zero failures
• Linter reports zero errors
• Type checker reports zero errors (if applicable)
• Build succeeds with exit code 0 (if applicable)
• No untracked or uncommitted files that should be included
• No language from the "Language to Avoid" table appears in the completion claim
• Any caveats, known issues, or deferred checks are explicitly stated
• Evidence is cited, not asserted

Critical rules

1. Run before you claim. Every verification command must be executed in the current session. Output from a previous session, a previous branch, or a previous version of the code is not evidence.
2. Capture everything. Paste output, do not paraphrase it. "Tests pass" is a claim. "Ran cargo test, 89 passed, 0 failed" is evidence.
3. Check exit codes. A command that prints friendly output but exits non-zero has failed. Always verify the exit code, not just the log output.
4. Full suite, not cherry-picked. Run the complete test suite, not just the tests for the file you changed. Your change may break something elsewhere.
5. No self-certification. "I verified it" without captured output is worth zero. The evidence must be visible to anyone reading the completion claim.
6. Caveats are mandatory. If any check was skipped, any test was ignored, or any known issue remains, state it explicitly. Hidden caveats are lies by omission.
7. Failures mean not done. If any verification command fails, the work is not complete. Fix the failure and re-run. There is no "done except for that one failing test."
8. Fresh over stale. If you made any change after the last verification run, even a one-character fix, re-run all verification. The last change is the one that breaks things.
9. Verification is part of the work. Code without verification is a draft, not a delivery.
10. When in doubt, verify more. Over-verification wastes minutes. Under-verification wastes days.

Reference Files

Integration with Other Skills