# verification-before-completion

> A Claude Code skill that blocks the agent from claiming work is done until it has run a verification command, read the output, and confirmed the result — replacing 'should work' and 'looks good' with evidence.

**Use case**: Stop claiming things work without running them first

**Canonical URL**: https://agentcookbooks.com/skills/verification-before-completion/

**Topics**: claude-code, skills, code-quality, code-review

**Trigger phrases**: "is this done", "did the tests pass", "ready to commit"

**Source**: [Jesse Vincent](https://github.com/obra/superpowers/tree/main/skills/verification-before-completion)

**License**: MIT

---

## What it does

`verification-before-completion` enforces a single rule: never claim a task is complete without fresh evidence from running the verification. The skill's protocol is four steps — identify what proves the claim, run it, read the *full* output, then confirm or fail. It explicitly rejects language like "should work", "looks good", "this ought to pass" as dishonest substitutes for actual verification.

The skill targets the most common silent failure in Claude Code sessions: agent reports "done", user merges, CI breaks, or worse — production breaks. The fix isn't trust; it's making verification a hard gate before any completion claim.

## When to use it

- Before announcing any task is complete
- Before committing code
- Before opening a PR or marking a TODO as done
- When pattern-matching makes a fix "look right" — verify it actually runs
- After applying a fix the agent feels confident about (overconfidence is the failure mode)

When *not* to reach for it:

- During exploratory phases where you're investigating, not finalizing
- For pure refactors where tests already passed and behavior didn't change (still verify, but the gate is lighter)

## Install

From the [obra/superpowers](https://github.com/obra/superpowers) repo at `skills/verification-before-completion/`. Pairs naturally with `systematic-debugging` (which catches symptom-patching) and the code-review skills.

## What a session looks like

1. **Identify the verification.** What command, test, or output would prove the claim? "The function works" → `npm test src/foo.test.ts`. "The build is clean" → `npm run build`. "The bug is fixed" → reproduce the original failure and observe it doesn't fail.
2. **Run it completely.** Not part of it. Not until the first failure. The full run.
3. **Read the full output.** Errors hide in the middle of long stack traces. Warnings matter. The skill resists the urge to grep for "PASS" and call it done.
4. **Confirm or fail honestly.** If it passed, say so with the evidence. If it didn't, say so with the evidence. Never paper over a partial pass.

The discipline that makes it work: the agent says nothing about completion until step 4 produces verifiable evidence. "Should work" is treated as a failure of the protocol.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been triggered against a "looks good" claim, this section will capture: what the agent was about to claim, what the verification actually showed, and whether the gate caught a real bug or just added friction._

## Source and attribution

From [Jesse Vincent's superpowers repository](https://github.com/obra/superpowers/tree/main/skills/verification-before-completion).

License: MIT.

The skill's framing is explicit: claiming completion without verification *is dishonesty*, especially before commits, PRs, or task closure. That framing is what gives the skill teeth — it's not "be careful", it's "you are lying if you skip this".