verification-before-completion

name	verification-before-completion
description	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
user-invocable	true

Verification Before Completion

Overview

Claiming success without evidence is guessing. "It should work" is not verification.

Core principle: ALWAYS run verification commands and confirm output before claiming work is complete. Evidence before assertions.

Violating the letter of these checks is violating the spirit of quality.

The Iron Law

NO SUCCESS CLAIMS WITHOUT RUNNING VERIFICATION COMMANDS

If you haven't seen passing output with your own eyes, you cannot claim it works.

No exceptions:

• Don't say "tests should pass" — run them
• Don't say "build looks fine" — build it
• Don't say "no lint errors" — lint it
• Don't say "changes look good" — diff them

When to Use

Always, before:

• Claiming work is "done" or "complete"
• Committing code
• Creating pull requests
• Closing issues
• Reporting success to teammates
• Moving to the next task

Use this ESPECIALLY when:

• Under time pressure (rushing guarantees missed issues)
• Changes seem trivial ("just a typo" can break builds)
• You've made multiple changes across files
• Refactoring existing code
• Fixing bugs (verify the fix AND no regressions)

Don't skip when:

• Change seems too small to break anything (small changes break things)
• You're confident it works (confidence ≠ evidence)
• You "already tested manually" (manual ≠ systematic)
• CI will catch it (catch it NOW, not after push)

The Four Phases

You MUST complete all four phases before claiming completion. Order matters.

Phase 1: Test Execution

Run ALL relevant tests, not just the ones you think matter.

# Run tests for affected area
npm test -- --coverage path/to/affected/
# OR
yarn test path/to/affected/

# Run full test suite if changes are cross-cutting
npm test

Verify:

• All tests pass (zero failures)
• No test warnings or errors in output
• Coverage hasn't decreased
• New code has corresponding tests
• No skipped tests you forgot to unskip

Test fails? Fix it. Do NOT proceed to Phase 2.

No tests exist? Write them first. Untested code is unverified code.

Phase 2: Build Verification

Confirm the project compiles and builds without errors.

# TypeScript projects
npx tsc --noEmit

# Build the project
npm run build
# OR
yarn build

Verify:

• Zero TypeScript errors
• Zero build errors
• Zero build warnings (or only pre-existing ones)
• Output artifacts are generated correctly

Build fails? Fix it. Do NOT proceed to Phase 3.

"It builds on my machine" is not verification. Run the actual build command.

Phase 3: Lint and Quality Check

Run linters and formatters to catch style and quality issues.

# Lint
npm run lint
# OR
npx eslint src/

# Format check
npm run format:check
# OR
npx prettier --check .

Verify:

• Zero lint errors
• Zero formatting issues
• No new warnings introduced
• Pre-commit hooks will pass

Lint fails? Fix it. Do NOT proceed to Phase 4.

Don't disable rules to make lint pass. Fix the code.

Phase 4: Diff Review

Review your own changes before anyone else sees them.

# Review all changes
git diff

# Review staged changes
git diff --cached

# Check for untracked files
git status

Verify:

• No debug code (console.log, debugger, TODO hacks)
• No commented-out code
• No unintended file changes
• No secrets, credentials, or API keys
• No large binary files accidentally staged
• Commit scope matches intent (no unrelated changes)

Found issues? Fix them. Do NOT commit.

"I'll clean it up later" — No. Clean it up now.

The Verification Report

After completing all four phases, summarize evidence:

## Verification Complete

- Tests: ✅ X passed, 0 failed (Y% coverage)
- Build: ✅ Clean compilation, zero errors
- Lint:  ✅ No errors, no new warnings
- Diff:  ✅ Reviewed, no debug code or secrets

Only after this report can you claim work is complete.

Red Flags — STOP and Verify

If you catch yourself thinking:

Thought	Reality
"Tests should pass"	Run them. "Should" isn't evidence.
"I only changed one line"	One line can break everything. Verify.
"CI will catch it"	Catch it now. Don't waste CI time.
"I already tested manually"	Manual testing is incomplete. Run automated checks.
"Build was fine last time"	Your changes may have broken it. Build again.
"Lint is too strict"	Fix code, don't disable rules.
"I'll review the diff later"	Review now. Later never comes.
"It's just a docs change"	Docs can have broken links, bad formatting. Verify.
"Tests take too long"	Run them anyway. Slow tests > shipped bugs.
"I'm confident it works"	Confidence without evidence is arrogance.

ALL of these mean: STOP. Run the verification.

Common Rationalizations

Excuse	Reality
"Too simple to break"	Simple changes break builds. 30-second check prevents hours of debugging.
"I'll verify after commit"	Post-commit fixes require amend/revert. Verify before.
"Only changed tests"	Test changes can mask real failures. Run the suite.
"CI runs everything"	CI feedback is slow. Local verification is fast. Catch issues immediately.
"Time pressure, ship it"	Shipping broken code creates MORE time pressure. Verify now.
"Other tests are flaky"	Distinguish your failures from flaky ones. Don't hide behind noise.
"Reviewer will catch it"	Reviewers miss things. Self-review catches 80% of issues.
"It worked in dev"	Dev ≠ prod. Build and test in the actual target environment.

Quick Reference

Phase	Command	Success Criteria
1. Tests	npm test	All pass, no warnings
2. Build	npm run build / tsc --noEmit	Zero errors
3. Lint	npm run lint	Zero errors, no new warnings
4. Diff	git diff + git status	Clean, no debug code

Integration with Other Skills

• After TDD: Verification is the final gate after Red-Green-Refactor completes
• After debugging: Verify the fix AND verify no regressions were introduced
• Before shipping: This skill is the prerequisite to any commit or PR workflow

Related skills:

• superpowers:test-driven-development — For writing tests (Phase 1 input)
• superpowers:systematic-debugging — For investigating failures found during verification

Final Rule

Evidence before assertions.
Verification before completion.
Output before claims.

No exceptions without your human partner's permission.