verification-before-completion

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,318 words, so you can see where the weight sits before reading.

1. 1The rule74 words
2. 2The gate88 words
3. 3What proves what220 words
4. 4Making a regression test earn its name85 words
5. 5Reading a result honestly86 words
6. 6When earlier evidence can be reused89 words
7. 7Small changes are not exempt96 words
8. 8When you cannot run the check91 words
9. 9After a failure36 words
10. 10Verification must not change the world74 words
11. 11Words that should stop you109 words
12. 12Reporting144 words

The skill itself

Read it before you install it

---
name: verification-before-completion
description: Gate every claim that work is done, fixed, passing or ready on fresh evidence - run the check that proves the claim, read its output and exit code, and report only what it shows. Use before saying work is complete, before committing, pushing or opening a pull request, before marking a task done or starting the next, and whenever a worker or subagent reports success. Triggers include "is it done", "does it pass", "ready to merge", "did that work", and the urge to write "should work now". Covers tests, builds, linters, file edits, migrations, bug fixes, requirement checks and delegated work. Not for choosing what to test (see test-driven-development) or finding a cause (see systematic-debugging).
license: MIT
---

# Verification before completion

A claim that work is done, fixed or passing is a statement about the state of things right now. Only a check run against that state can support it. Confidence, a plausible diff and an earlier green run are not checks. An unchecked claim is a guess stated as a fact, and the person who trusts it pays for it.

## The rule

```
NO COMPLETION CLAIM WITHOUT EVIDENCE FROM A CHECK RUN AGAINST THE CURRENT STATE
```

"Current state" means the code, configuration, dependencies and environment as they are after your last change. The rule covers paraphrases and implications: "all set", "that's sorted", a commit message, a pull request description, a hand-off, or moving on to the next task. Saying "I made the change and have not run the tests yet" is honest, and always allowed.

## The gate

1. **Identify** the check that would prove this claim, and would fail if the claim were false.
2. **Run** the complete command, not a subset. A claim about the suite needs the suite.
3. **Read** the whole result: the exit code, the counts, the failures, the warnings. The last line is not the result.
4. **Compare** it with the claim. Does it say exactly this, or something narrower?
5. **Report** the claim together with the evidence. If the evidence does not support it, report the actual status instead.

## What proves what

| Claim | Evidence | Not enough |
|---|---|---|
| Tests pass | The full suite, run after the last edit: counts and exit code | An earlier run, only the new test file, "should pass" |
| Build succeeds | The build command exits 0 | A clean linter, logs that look fine |
| Linter or type check is clean | That tool's own output | Inferring it from a related tool |
| Bug is fixed | The original symptom no longer reproduces, and a regression test failed before the fix and passes after | The code changed |
| Edit applied | Re-read or search the file for the new text where it should be, then syntax-check or compile it | The editing tool said success |
| Migration or data change worked | A query showing the new state: row counts, new columns, permissions | The command returned success |
| Requirements are met | Each acceptance condition checked one by one | The tests pass |
| A worker finished | The actual diff, including new untracked files, plus checks you ran or its real log | Its report |
| Nothing else broke | The full suite, and a diff that touches only what you expected | The file you changed passes |

## Making a regression test earn its name

A test that was never red proves nothing. Write it, see it pass, remove the fix, see it fail, restore the fix, see it pass. Do the removal in a way you can restore exactly: a copy of the tree, or a change you can reverse. Never reset, check out over, or stash away the user's uncommitted work to stage the experiment. If you cannot do it safely, say "not shown to fail without the fix" and do not call the test a regression guard.

## Reading a result honestly

A green result can be empty. Look for: zero tests collected, tests skipped, a command run in the wrong directory or environment, an exit code of 0 after error output, and a check that never touched the changed lines. For a bug fix or new behavior, name the test that exercises the lines you changed.

Report every failure the run shows, by name, including ones you did not cause. A red result you watched scroll past and did not mention makes your report false by omission.

## When earlier evidence can be reused

Re-running everything after each message is waste, but reusing a result needs all of these:

- the same code state, including staged, unstaged and untracked files (a commit hash does not cover uncommitted changes);
- the same command and the same scope;
- the same dependencies, configuration, runtime and external state, or a known equivalent;
- the actual log and exit code in hand, not a summary of them.

If any is missing, run the check again. A worker's "PASS" is a lead, not evidence, until these are confirmed.

## Small changes are not exempt

Small changes are where unverified work slips through. Scale the check to the change, never to zero. A one-line edit gets a one-line check: re-read it, syntax-check it, or run the test that covers it. A comment or documentation edit can use a lighter check, such as reading the diff, rendering the page or following the link. Say which check you used. Do not classify a change as trivial to avoid a check you would otherwise owe, and do not defer a check to a reviewer: review reads the change, it does not run your code.

## When you cannot run the check

The check may need a pipeline, hardware, credentials or a service you cannot reach, or the project may have no tests. Do not substitute confidence.

- Say what you could not run and why.
- Do what you can instead: a smoke test, a manual reproduction written down as input, expected result, observed result, and pass or fail.
- Mark the claim unverified, and the work incomplete. An unrun check is not a passed check.
- Known debt is acceptable only when named, assigned and non-blocking. A failed check blocks completion.

## After a failure

Diagnose before you retry (see `systematic-debugging`). Fix the cause, then run the check that covers the fix. If two fixes for the same cause fail, stop looping: change the plan or report that you are blocked.

## Verification must not change the world

A check should not cause the damage it guards against. Do not run deployments, migrations against shared or production data, destructive scripts, or anything that sends messages or spends money as a "check" without the user's say-so. Use a dry run, a test database or a read-only query. Passing verification is the precondition for committing, pushing or opening a pull request, not permission to do them. Do those only when the user has asked.

## Words that should stop you

| You are about to say or think | Do this instead |
|---|---|
| "Should work now", "probably", "seems to" | Run the check |
| "Great!", "Done!" before any run | Run it, then say what it showed |
| "I'm confident" | Confidence is not evidence |
| "The linter passed, so it builds" | Run the build |
| "The worker says it works" | Read the diff and the checks yourself |
| "Just this once" or "I'm tired" | The rule does not bend for either |
| "The reviewer will catch it" | Review comes after verification, not instead of it |

## Reporting

Keep the report short enough to inspect:

```
Ran:      npm test (repository root, after the last edit)
Result:   exit 0, 212 passed, 0 failed, 2 skipped (both skipped before my change)
Not run:  browser tests, which need a display
Claim:    the retry fix works and the unit suite is green. Browser behavior is unchecked.
Status:   incomplete until the browser tests run
```

Bad: "That should fix it. Tests pass."

For a longer run, keep the full log in a file and report the command, the working directory, the state tested (commit plus any uncommitted changes), the result, and the log's path. Status is complete only when every check you meant to run was run. A missing step means incomplete, never a softer sentence.

Before a hand-off, re-read the original request or plan, list every acceptance condition, check each, and report the gaps by name.

The second audit

What we found in the sources

It keeps the evidence-before-claims discipline of the version the others copy (obra/superpowers) and adds what five variants contributed: conditions for reusing earlier evidence, what to do when a check cannot be run, checks for edits and migrations, and a short report format. The safety section was written for this rewrite, and none of the sources has it. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• obra/superpowers ↗ · Primary basis · MIT

  The core rule (no completion claim without fresh evidence), the identify-run-read-verify-report gate, the table of claims against the evidence each one needs, the list of wording that should stop you ("should", "probably", satisfaction before a run, "just this once"), the rationalization table, the red-green-restore check for a regression test, and the rule that a worker's success report is checked against the actual diff. The translation, the identical copy, the two variants and the condensed recast in this bundle all follow it.

• lsy041015/orchestra ↗ · Added ideas · MIT

  The conditions under which an earlier result may be reused (same code state including staged, unstaged and untracked files, same command and scope, same environment, the actual log and exit code in hand), the point that a commit hash does not cover uncommitted changes, the short verification record (command, directory, state tested, result, log), no unbounded retry loop and stopping after two failed fixes for one root cause, and inspecting each acceptance condition before reporting completion.

• j0hanz/squad-agents ↗ · Added ideas · MIT

  The ban on classifying a change as trivial in order to skip a check, naming the test that exercises the changed lines, writing a manual verification down as input, expected, observed and status, what to do when there is no test suite or the check only runs in CI (a smoke test or a written manual reproduction, then mark the work incomplete), and "review does not re-run your code".

• SpikeboyIL/claude-code-discipline-pack ↗ · Added ideas · MIT

  Checking that an edit actually landed by re-reading or searching for the new text where it should be, syntax-checking what you touched, the point that small changes are where unverified work slips through, and following a migration with a query that proves the new state.

• sitien173/superpowers-ccg ↗ · Added ideas · MIT

  An unrun check is not a passed check, known debt is acceptable only when named, assigned and non-blocking, and the final report lists skipped checks and environmental blockers.

• thepragmaticbear/bearpaws ↗ · Added ideas · MIT

  Only the rule that a missing step makes the status incomplete, never a softened sentence.

What changed

• The description now says what the skill does, when it applies, which phrases should trigger it, and what it is not for. The upstream description is "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always".
• Rewritten as one self-contained file with no companion files, no other skills in a bundle, no plugin namespace and no harness-specific tool names. The two skills it names (test-driven-development, systematic-debugging) are in this repository.
• Upstream ties freshness to "in this message". The rewrite ties it to the current state after the last change, and says when an earlier result may be reused (taken from lsy041015/orchestra). Whether upstream meant to forbid all reuse is unclear.
• Added a section on checks that cannot be run (no tests, CI-only, missing access): say so, do what can be done instead, mark the work incomplete.
• Added a section saying verification must not change the world: no deployments, production migrations, destructive scripts, messages or spending as a "check" without the user's say-so, and passing a check is not permission to commit, push or open a pull request. None of the sources says this; it was written for this rewrite.
• The regression check (remove the fix, see it fail, restore it) now says to do the removal on a copy or by a reversible change and never over the user's uncommitted work. That caution is the rewrite's own; the sources give the red-green sequence only.
• Added a short list of ways a green result can be empty (zero tests collected, skipped tests, wrong directory or environment, exit 0 after error output). It was written for this rewrite and is not taken from a source.
• Replaced the check and cross glyphs with plain Good and Bad labels, and cut the rhetorical lines ("Skip any step = lying, not verifying", "Violating the letter of this rule is violating the spirit").
• Replaced "your human partner" and similar persona wording with "the user".

Problems found in the sources

• !obra/superpowers: The description gives the trigger and the demand but no phrases a person would type and no "not for" line. The body uses check and cross glyphs and rhetoric ("Skip any step = lying, not verifying"). Freshness is defined as having run the command "in this message", which on a strict reading forbids reusing a result even when nothing has changed; whether that is intended is unclear. The "Agent completed" row relies on the VCS diff alone, and lsy041015/orchestra points out that new untracked files must be included. It gives no guidance for checks that cannot be run.
• !gylove1994/superpowers-deepseek-v4: Adds a "Why This Matters" section that cites "24 failure memories" with no source or basis, and quotes "Honesty is a core value. If you lie, you'll be replaced." as a rule. It also uses "your human partner". A diff against upstream shows these are the only additions (two lines near the top, that section, and a closing section).
• !mzored/superpowers-cc-to-codex: A diff against gylove1994/superpowers-deepseek-v4 shows the same body, with only a "-codex" suffix on the name and a header comment added. The comment says no Codex integration is needed and that the upstream skill should be disabled when this one is active to avoid a name collision. Despite the name, it is not tied to Codex.
• !thepragmaticbear/bearpaws: Recasts upstream in XML tags and shortens it. The description is short and gives only triggers. The risk-receipt example names a reviewer with a plugin prefix (bp:code-reviewer), which a lone copy of the file cannot resolve.
• !lsy041015/orchestra: The prose is dense, there is no example of a good or bad claim, and it assumes a main session supervising workers ("make a main-agent ruling" is not explained in the file). Its ideas on reusing evidence and recording the state tested are the strongest in the bundle.
• !j0hanz/squad-agents: Not self-contained: it links to references/definition-of-done.md and to ../test-driven-development/SKILL.md, lists a question tool and a request-code-review skill in its routing, and sets allowed-tools in its frontmatter. The trivial-change test is fixed at exactly one file and one line, which looks arbitrary; unclear whether it was meant as a heuristic. It uses check-mark emoji.
• !SpikeboyIL/claude-code-discipline-pack: Step 4 asks for the new identifier to appear "exactly N times", but grep -c counts matching lines, not occurrences; the file notes this limit only for the paired-string case in step 2. Its scope is edits and migrations, and it does not mention running tests.
• !sitien173/superpowers-ccg: States that a coordinating skill chooses the revision, diff ranges and review sequence, but names no such skill, so a lone copy leaves that unanswered. The labels FAIL and PASS_WITH_DEBT are used without saying where they come from.

What was dropped

• The "Why This Matters" section found in gylove1994/superpowers-deepseek-v4 and mzored/superpowers-cc-to-codex ("24 failure memories" and a quoted line about being replaced if you lie), for lack of any stated basis.
• The risk receipt in thepragmaticbear/bearpaws (Risk, Pinned, Failing first, Review, Assumptions lines). It names a plugin-namespaced reviewer and makes completion depend on one reply format.
• From j0hanz/squad-agents: the fixed trivial-change threshold of one file and one line, the routing to a review skill, the question-tool template for manual test plans, and the links to a definition-of-done file and another skill.
• From sitien173/superpowers-ccg: the PASS, FAIL and PASS_WITH_DEBT labels and the dependence on an unnamed coordinating skill.
• From the upstream: the list that spells out that the rule applies to exact phrases, paraphrases and implications is condensed into one sentence.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/verification-before-completion ~/.claude/skills/

Pairs with