Verification Before Completion

---
name: verification-before-completion
description: Use when about to claim work is complete, before committing or creating PRs - requires fresh verification evidence before any completion claim. Triggers on phrases like "done", "finished", "ready to commit", "all tests pass", "looks good", "should work", "I think that's it".
version: 1.0.0
type: reference
attribution: Adapted from superpowers plugin (v4.3.1) by Jesse Vincent, MIT License
---

# Verification Before Completion

## Overview

Every completion claim requires fresh evidence. No exceptions.

## The Iron Law

**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**

"I believe it works" is not evidence. "The tests passed at 14:32" is evidence.

If you have not run verification commands in this session and read their output, you have not verified.

## The Gate Function

Before ANY claim that work is complete, execute this sequence:

```
1. IDENTIFY  - What claims am I about to make?
2. RUN       - Execute the verification commands
3. READ      - Read the actual output (not what I expect to see)
4. VERIFY    - Does the output support each claim?
5. CLAIM     - Only now state completion, citing evidence
```

**Every step is mandatory.** Skipping any step means the gate has not been passed.

### Step 1: IDENTIFY

List every claim you are about to make. Be specific:

```
NOT: "It works"
YES: "All 47 tests pass, the build succeeds, and the new endpoint returns 200"
```

Common implicit claims to surface:
- "Tests pass" -- which tests? All of them? Just the new ones?
- "Build succeeds" -- clean build or incremental?
- "Bug is fixed" -- does the specific reproduction case now succeed?
- "No regressions" -- have you run the full test suite, not just new tests?
- "Ready to merge" -- does it pass lint, type checking, and formatting too?

### Step 2: RUN

Execute the actual verification commands. Not from memory. Not from a previous run.

```
REQUIRED: Run the commands NOW, in this session
REQUIRED: Use the Bash tool to execute them
REQUIRED: Run the FULL suite, not a subset (unless the user explicitly scoped it)

FORBIDDEN: Assuming tests still pass from earlier
FORBIDDEN: Referencing results from before your changes
FORBIDDEN: Skipping slow tests without stating you skipped them
```

### Step 3: READ

Read the actual output. All of it.

```
REQUIRED: Read exit codes
REQUIRED: Read failure messages, not just success counts
REQUIRED: Read warnings (they may indicate real problems)

FORBIDDEN: Scanning for "X tests passed" and ignoring everything else
FORBIDDEN: Assuming green because the command "looked like it worked"
```

### Step 4: VERIFY

For each claim from Step 1, check whether the evidence supports it:

```
Claim: "All tests pass"
Evidence: Exit code 0, output shows "47 passed, 0 failed"
Verdict: SUPPORTED

Claim: "No regressions"
Evidence: Only ran new test file, not full suite
Verdict: NOT VERIFIED -- full suite not executed
```

If any claim is NOT VERIFIED, go back to Step 2 and run what's missing.

### Step 5: CLAIM

State completion with evidence citations:

```
"Implementation complete:
- All 47 tests pass (exit code 0)
- Build succeeds (no errors, 2 warnings -- both pre-existing)
- New endpoint returns 200 with correct response body
- Lint and type checking pass"
```

## What Each Claim Requires

| Claim | Required Evidence |
|-------|-------------------|
| "Tests pass" | Test runner output showing pass count, zero failures, exit code 0 |
| "Build succeeds" | Build command output with exit code 0 |
| "Bug is fixed" | Reproduction steps now produce expected behavior |
| "No regressions" | Full test suite passes (not just new tests) |
| "Feature works" | Demonstrated behavior matching acceptance criteria |
| "Ready to commit" | Tests + build + lint + type check all pass |
| "Ready for review" | All of the above + self-review completed |
| "Performance improved" | Before and after measurements with methodology |

## Red Flags -- STOP and Go Back to Step 2

If you notice yourself thinking or about to write any of these, STOP:

- **"Should work"** -- Should is not evidence. Run it.
- **"I think all tests pass"** -- Think is not evidence. Run them.
- **"It looks correct"** -- Looks is not evidence. Verify it.
- **"I'm confident this works"** -- Confidence is not evidence. Prove it.
- **"Tests were passing earlier"** -- Earlier is stale. Run them again.
- **"This is a safe change"** -- Safe changes break things too. Verify.
- **"It's just a typo fix"** -- Typo fixes break builds. Run the build.
- **Expressing satisfaction before running tests** -- Satisfaction is a feeling, not a verification.

## Common Rationalizations

| Rationalization | Why It Fails | What to Do Instead |
|----------------|--------------|---------------------|
| "I just ran the tests a minute ago" | You changed code since then | Run them again |
| "This change is too small to break anything" | Small changes cause big failures | Run the verification |
| "The tests are slow, I'll skip them" | Skipped tests are unverified claims | Run them, or explicitly state "tests not run due to time constraint" |
| "I saw the output scroll by" | Scrolling past is not reading | Read the actual results |
| "The important tests pass" | Partial verification = partial claim | Run all tests or scope your claim |
| "It compiled, so it works" | Compilation proves syntax, not behavior | Run behavioral tests |
| "I'll fix that test later" | A failing test means tests don't pass | Fix it now or state the failure |
| "That failure is flaky / pre-existing" | Prove it -- show it fails on the base branch too | Verify the flake claim |

## Key Patterns

### After Writing Tests (Red-Green Verification)

```
1. Write the test
2. RUN the test -- watch it FAIL (confirms test detects the issue)
3. Write the implementation
4. RUN the test -- watch it PASS (confirms implementation works)
5. RUN the full suite -- confirm no regressions
6. NOW you can claim: "Test passes, no regressions"
```

### After Bug Fixes

```
1. Reproduce the bug (run the failing case, see the failure)
2. Apply the fix
3. RUN the reproduction case -- see it succeed
4. RUN the full test suite -- no regressions
5. NOW you can claim: "Bug fixed, verified with reproduction case, no regressions"
```

### Before Committing

```
1. RUN full test suite
2. RUN build command
3. RUN linter / formatter / type checker (if project uses them)
4. READ all outputs
5. ALL pass with exit code 0?
   YES: Proceed to commit
   NO: Fix first, then start from step 1
```

### When Delegating to Agents

```
After agent completes:
1. READ the agent's claimed results
2. RUN the verification commands YOURSELF
3. Do the results match the claims?
   YES: Proceed
   NO: The agent's claims are wrong. Fix or re-dispatch.

NEVER trust agent completion claims without re-running verification.
```

## When to Apply This Gate

Apply this gate before ANY of these actions:

- Telling the user "it's done" or "it works"
- Creating a git commit
- Creating or updating a pull request
- Claiming a task is complete
- Moving on to the next task
- Reporting success to the user
- Any variation of "finished", "complete", "ready", "all good"

## Relationship to Other Skills

- **After systematic-debugging:** You've found and fixed the root cause. Now verify the fix before claiming it works.
- **After test-driven-development:** You've gone through red-green-refactor. Now run the full suite before claiming done.
- **Before /ship commit gate:** This gate runs before you reach Step 6. Fresh verification at Step 4 (tests) is mandatory.

## The Bottom Line

**Evidence, not confidence.** Run it. Read it. Then claim it.

The cost of running verification is minutes. The cost of a false completion claim is rework, broken builds, and eroded trust.

If you cannot run the verification, say so: "I cannot verify [X] because [reason]. Do you want me to proceed without verification or investigate how to verify?"