verification-before-completion

Run verification commands and confirm output before claiming success

⭐36stars🔀6forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

The 'Verification Before Completion' skill implements a rigorous 'evidence-first' protocol designed to eliminate false success claims in software development and agentic workflows. By enforcing a mandatory five-step gate function—Identify, Run, Read, Verify, and Claim—it ensures that no task is marked as complete without fresh, documented output from verification commands. This skill is essential for maintaining high code quality, reducing rework costs, and building trust in automated or AI-assisted programming environments.

Use Cases

  • 1. Pre-Commit & PR Validation: Ensuring that all unit tests, linters, and build scripts pass with documented evidence before code is pushed or merged into a repository.
  • 2. Reliable Bug Fixing: Confirming that a specific patch actually resolves the root cause by running reproduction scripts and verifying the exact output rather than assuming success.
  • 3. Agentic Workflow Guardrails: Setting a high bar for AI agents to provide raw logs and execution results as proof of work, preventing 'hallucinated' success reports.
  • 4. Deployment Readiness Checks: Executing comprehensive smoke tests and environment health checks immediately before a production release to avoid costly rollbacks.
  • 5. Quality Assurance Auditing: Providing a clear audit trail of verification steps taken during the development process to ensure compliance with engineering standards.
nameverification-before-completion
descriptionRun verification commands and confirm output before claiming success
version2.0.0
categorydebugging
authorJesse Vincent
licenseMIT
sourcehttps://github.com/obra/superpowers-skills/tree/main/skills/debugging/verification-before-completion
summary"Evidence before claims: mandatory verification before ANY completion claim"
when_to_use"When about to claim work is complete, fixed, passing, or ready. ESPECIALLY before commits, PRs, or task completion."
quick_start"1. Identify verification command 2. Run FULL command 3. Read complete output 4. Verify results 5. THEN claim with evidence"
context_limit800
requires_tools[]

Verification Before Completion

Overview

Claiming work is complete without verification is dishonesty, not efficiency.

Core principle: Evidence before claims, always.

Violating the letter of this rule is violating the spirit of this rule.

This skill enforces mandatory verification before ANY completion claim, preventing false positives, broken builds, and trust violations.

When to Use This Skill

Activate ALWAYS before claiming:

  • Success, completion, or satisfaction ("Done!", "Fixed!", "Great!")
  • Tests pass, linter clean, build succeeds
  • Committing, pushing, creating PRs
  • Marking tasks complete or delegating to agents

Use this ESPECIALLY when:

  • Under time pressure or tired
  • "Quick fix" seems obvious or you're confident
  • Agent reports success or tests "should" pass

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

Core Principles

  1. Evidence Required: Every claim needs supporting evidence
  2. Fresh Verification: Must verify now, not rely on previous runs
  3. Complete Verification: Full command, not partial checks
  4. Honest Reporting: Report actual state, not hoped-for state

Quick Start

The five-step gate function:

  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.

Key Patterns

Correct Pattern:

✅ [Run pytest] [Output: 34/34 passed] "All tests pass"

Incorrect Patterns:

❌ "Should pass now"
❌ "Looks correct"
❌ "Tests were passing"
❌ "I'm confident it works"

Red Flags - STOP Immediately

If you catch yourself:

  • Using "should", "probably", "seems to"
  • Expressing satisfaction before verification
  • About to commit/push/PR without verification
  • Trusting agent success reports
  • Relying on partial verification

ALL of these mean: STOP. Run verification first.

Why This Matters

Statistics from real-world failures:

  • Verification cost: 2 minutes
  • Recovery cost: 120+ minutes (60x more expensive)
  • 40% of unverified "complete" claims required rework

Core violation: "If you lie, you'll be replaced"

For detailed information:

The Bottom Line

No shortcuts for verification.

Run the command. Read the output. THEN claim the result.

This is non-negotiable.