Verification Before Completion

tl;dr: the evidence-before-claims skill from the Debugging cluster. Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. If you haven’t run the verification command in this message, you can’t claim it passes. Violating the letter is violating the spirit.

What it actually does

SKILL.md (obra/superpowers, fetched 2026-09-10) is short and rigid. Two pieces structure it: the Iron Law and the Gate Function.

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

“Fresh” is operative — a previous run, a remembered test pass, a linter-clean output that doesn’t include the compiler step is not fresh evidence for a “build succeeds” claim.

The Gate Function (five steps, in order)

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN:     Execute the FULL command (fresh, complete)
3. READ:    Full output, check exit code, count failures
4. VERIFY:  Does output confirm the claim?
           - If NO:  State actual status with evidence
           - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

Skip any step = lying, not verifying.

Claims vs. evidence — the named pairs

The skill enumerates the common failure modes as a two-column table:

Each row is a real failure pattern. The linter-vs-compiler row alone catches more confident-on-no-evidence failures than anything else in the skill.

Regression tests — the TDD red-green carve-out

The skill is explicit about regression tests:

Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)

A regression test that has only ever passed once has not been verified as a regression test. The revert-fail-restore dance is the only way to prove the test actually exercises the bug it claims to. Same evidence rule, applied to the test itself.

Agent delegation — the agent-reported-success carve-out

When a subagent reports success, the same gate applies to the report:

• Agent reports success → Check VCS diff → Verify changes → Report actual state
• Trusting agent success reports = “Not sufficient” column for the Agent completed row

Requesting Code Review pairs with this: the reviewer subagent produces an evidence-backed triage, and verification-before-completion enforces that the dispatching agent only claims review complete after reading the actual returned findings, not the agent’s “all green” summary line.

The red-flag lists (verbatim from SKILL.md)

Two tables at the end of the file are worth quoting in full because they predict the exact phrasing a tired agent will reach for.

STOP wording — phrases that mean “you are about to lie”:

• Using “should”, “probably”, “seems to”
• Expressing satisfaction before verification (“Great!”, “Perfect!”, “Done!”, etc.)
• About to commit/push/PR without verification
• Trusting agent success reports
• Relying on partial verification
• Thinking “just this once”
• Tired and wanting work over
• ANY wording implying success without having run verification

Rationalization table — excuses vs. reality:

The final rule: this skill applies to exact phrases, paraphrases, synonyms, implications of success, and ANY communication suggesting completion or correctness — the wording-level reading is the failure mode.

Where it sits in the Superpowers flow

It is one of two non-negotiable skills, paired with using-superpowers. The README puts it inside the Debugging cluster, between systematic-debugging (find the root cause) and the actual fix. The chain:

1. systematic-debugging proves a root cause with evidence
2. write a failing test against that cause (TDD)
3. fix it
4. verification-before-completion runs the gate to claim it fixed

It also runs after requesting-code-review: claims that “the review found nothing” need to show the reviewer’s actual output, not the dispatcher’s paraphrase of it.

Install

Per the upstream README, there is no npx skills add obra/superpowers command. Install the whole plugin per-harness:

# Claude Code — Anthropic official marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code — Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Codex CLI — official marketplace
/plugins    # search "superpowers" → Install Plugin

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# OpenCode — host fetches its own install doc
# Say: "Fetch and follow instructions from
#       https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md"

# Antigravity
agy plugin install https://github.com/obra/superpowers

Installing just this SKILL.md on its own will load the rules but not the rest of the methodology that feeds it (e.g. systematic-debugging, test-driven-development). For the gate to be meaningful, the surrounding skills need to be loaded too.

Gotchas

• Fresh evidence, not just evidence. “Linter passed earlier in this session” is not verification evidence for “build succeeds” now. Run the actual build command in the message that contains the claim.
• The agent-reported-success carve-out is the failure mode. verification-before-completion is what stops “I dispatched a subagent, it said ‘done’, I said ‘done’” claim chains. Treat agent “all green” output the same as a placeholder until the VCS diff is checked.
• Linter ≠ compiler. The named gotcha in both tables. tsc --noEmit and eslint are different programs; passing the second does not justify claiming the first.
• Regression tests must show they failed once. A test that never failed doesn’t prove it’s a regression test. Revert the fix, run the test, restore. If you didn’t do that dance, the test claim is unverified.
• Same wording trick. “Looks correct”, “should be fine”, “I’m 90% sure” are all in the banned phrase list. The skill closes with “spirit over letter” — if your sentence is one synonym away from a banned phrase, the rule still applies.
• Tired is a real reason. The “I’m tired” rationalization is in the table because exhaustion is the most common source of unverified completion claims in long sessions.
• Pairs with systematic-debugging, not replaces it. verification-before-completion only validates that something passes — the claim that the right thing passes comes from the earlier systematic-debugging step proving the root cause was the bug you fixed.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not run a five-step gate in the sandbox.

Related: Using Superpowers (obra/superpowers) — the other non-negotiable, same “violating the letter is violating the spirit” wording; Requesting Code Review (obra/superpowers) — the supply side this skill gates on the demand side; Executing Plans (obra/superpowers) — the workflow whose task-complete checkpoints this skill enforces.