Verification Before Completion

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.

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.

The Gate Function

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

Common Failures

Red Flags - STOP

• 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 Prevention

Key Patterns

Tests:

✅ [Run test command] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Looks correct"

Regression tests (TDD Red-Green):

✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
❌ "I've written a regression test" (without red-green verification)

Build:

✅ [Run build] [See: exit 0] "Build passes"
❌ "Linter passed" (linter doesn't check compilation)

Requirements:

✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
❌ "Tests pass, phase complete"

Agent delegation:

✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
❌ Trust agent report

Why This Matters

From 24 failure memories:

• your human partner said "I don't believe you" - trust broken
• Undefined functions shipped - would crash
• Missing requirements shipped - incomplete features
• Time wasted on false completion → redirect → rework
• Violates: "Honesty is a core value. If you lie, you'll be replaced."

When To Apply

ALWAYS before:

• ANY variation of success/completion claims
• ANY expression of satisfaction
• ANY positive statement about work state
• Committing, PR creation, task completion
• Moving to next task
• Delegating to agents

Rule applies to:

• Exact phrases
• Paraphrases and synonyms
• Implications of success
• ANY communication suggesting completion/correctness

When to Use This Skill

Trigger Conditions:

• Before claiming any work is complete or successful
• Before committing code changes to version control
• Before creating pull requests or submitting for review
• Before expressing satisfaction with implementation
• Before moving to the next task or phase
• When delegating work to agents and verifying completion
• When about to make any positive statement about work status
• Before shipping features or marking tasks as done
• When tired or under time pressure (prevents false claims)
• After any implementation work requiring validation

Mandatory Application:

• Always apply before any completion claims
• No exceptions for "obvious" or "simple" changes
• Required even when delegating to agents
• Must be applied before any communication of success

Step-by-Step Procedure

Step 1: Identify Verification Command

Determine what command proves the claim:

// Identify the appropriate verification method
const verificationMethods = {
  tests: {
    claim: 'tests pass',
    command: 'npm test',
    success: 'All tests pass with 0 failures'
  },
  build: {
    claim: 'build succeeds',
    command: 'npm run build',
    success: 'Exit code 0, no compilation errors'
  },
  lint: {
    claim: 'code is clean',
    command: 'npm run lint',
    success: '0 linting errors or warnings'
  },
  requirements: {
    claim: 'requirements met',
    command: 'manual checklist verification',
    success: 'All requirements checked and confirmed'
  }
};

Verification Command Identification:

• Tests: Full test suite execution
• Build: Complete build process
• Linting: Code quality checks
• Requirements: Manual checklist verification
• Agent work: VCS diff and functionality verification

Step 2: Execute Fresh Verification

Run the complete verification command from scratch:

# Execute verification with full output capture
VERIFICATION_OUTPUT=$(mktemp)
VERIFICATION_EXIT_CODE=0

# Run the verification command
case $CLAIM_TYPE in
  "tests")
    npm test 2>&1 | tee "$VERIFICATION_OUTPUT"
    VERIFICATION_EXIT_CODE=${PIPESTATUS[0]}
    ;;
  "build")
    npm run build 2>&1 | tee "$VERIFICATION_OUTPUT"
    VERIFICATION_EXIT_CODE=${PIPESTATUS[0]}
    ;;
  "lint")
    npm run lint 2>&1 | tee "$VERIFICATION_OUTPUT"
    VERIFICATION_EXIT_CODE=${PIPESTATUS[0]}
    ;;
esac

Fresh Execution Requirements:

• Complete command execution (not partial)
• Full output capture for analysis
• Exit code verification
• No reliance on previous runs

Step 3: Analyze Complete Output

Read and analyze the full verification output:

// Analyze verification results
function analyzeVerificationOutput(output, exitCode) {
  const results = {
    success: exitCode === 0,
    failureCount: countFailures(output),
    errorMessages: extractErrors(output),
    warnings: extractWarnings(output),
    summary: generateSummary(output)
  };

  return results;
}

// Count different types of failures
function countFailures(output) {
  return {
    testFailures: (output.match(/FAILED|✗/g) || []).length,
    buildErrors: (output.match(/ERROR|error/g) || []).length,
    lintErrors: (output.match(/error|Error/g) || []).length,
    compilationErrors: (output.match(/Compilation failed/g) || []).length
  };
}

Output Analysis:

• Check exit code (0 = success)
• Count failures and errors
• Extract error messages
• Identify warning conditions
• Generate summary assessment

Step 4: Verify Claim Against Evidence

Compare claim against actual verification results:

// Verify claim matches evidence
function verifyClaim(claim, verificationResults) {
  const claimVerification = {
    'tests pass': verificationResults.success && verificationResults.failureCount.testFailures === 0,
    'build succeeds': verificationResults.success && verificationResults.failureCount.buildErrors === 0,
    'code is clean': verificationResults.success && verificationResults.failureCount.lintErrors === 0,
    'requirements met': verificationResults.manualChecklistComplete,
    'bug fixed': verificationResults.regressionTestPasses,
    'feature complete': verificationResults.allAcceptanceCriteriaMet
  };

  return {
    claimValid: claimVerification[claim] || false,
    evidence: verificationResults,
    discrepancies: identifyDiscrepancies(claim, verificationResults)
  };
}

Claim Verification:

• Tests pass: 0 test failures, exit code 0
• Build succeeds: No compilation errors, exit code 0
• Code clean: 0 linting errors, exit code 0
• Requirements met: All checklist items verified
• Bug fixed: Regression test passes

Step 5: Report Actual Status with Evidence

State the verified status with supporting evidence:

// Report verified status
function reportVerifiedStatus(claim, verificationResults) {
  if (verificationResults.success) {
    return `[Verification: ${verificationResults.command}] [Result: ${verificationResults.summary}] "${claim}"`;
  } else {
    return `[Verification: ${verificationResults.command}] [Result: ${verificationResults.summary}] "Claim invalid - ${verificationResults.errorMessages.join(', ')}"`;
  }
}

// Example outputs:
// ✅ [npm test] [34/34 tests pass] "All tests pass"
// ❌ [npm run build] [3 compilation errors] "Build fails - missing imports in Component.tsx"

Evidence-Based Reporting:

• Include verification command executed
• Show actual results (pass/fail counts)
• Provide specific error messages if failed
• Never make claims without fresh evidence

Step 6: Handle Agent-Delegated Work

Verify agent completion independently:

// Verify agent work completion
function verifyAgentWork(agentReport, taskRequirements) {
  const independentVerification = {
    vcsChanges: checkGitDiff(agentReport.expectedFiles),
    functionality: testActualBehavior(taskRequirements),
    requirements: verifyAcceptanceCriteria(taskRequirements),
    quality: runQualityChecks()
  };

  return {
    agentReportValid: compareWithIndependentVerification(agentReport, independentVerification),
    evidence: independentVerification,
    discrepancies: findDiscrepancies(agentReport, independentVerification)
  };
}

Agent Verification:

• Check actual VCS changes (not just agent reports)
• Test actual functionality implemented
• Verify requirements are truly met
• Run independent quality checks

Step 7: Implement Red-Green Verification for Tests

Verify regression tests with proper red-green cycle:

// Red-Green verification for regression tests
async function verifyRegressionTest(testCode, originalFailingCode) {
  // 1. Write the test
  writeTestFile(testCode);
  
  // 2. Run with original code (should FAIL)
  const redResult = await runTest();
  if (redResult.success) {
    throw new Error('Test should fail with original code');
  }
  
  // 3. Implement fix
  implementFix(originalFailingCode);
  
  // 4. Run test again (should PASS)
  const greenResult = await runTest();
  if (!greenResult.success) {
    throw new Error('Test should pass with fix implemented');
  }
  
  return {
    verified: true,
    redConfirmed: !redResult.success,
    greenConfirmed: greenResult.success
  };
}

Red-Green Verification:

• Confirm test fails with original broken code
• Implement minimal fix
• Confirm test passes with fixed code
• Ensures test actually catches the bug

Step 8: Create Requirements Verification Checklist

Systematically verify requirements completion:

// Requirements verification checklist
function createRequirementsChecklist(planDocument, implementation) {
  const checklist = planDocument.tasks.map(task => ({
    taskId: task.id,
    description: task.description,
    verificationMethod: determineVerificationMethod(task),
    status: 'pending',
    evidence: null
  }));

  return checklist;
}

// Verify each requirement
async function verifyRequirements(checklist) {
  for (const item of checklist) {
    item.evidence = await executeVerification(item.verificationMethod);
    item.status = item.evidence.success ? 'verified' : 'failed';
  }

  return {
    allMet: checklist.every(item => item.status === 'verified'),
    summary: generateVerificationSummary(checklist),
    gaps: checklist.filter(item => item.status === 'failed')
  };
}

Requirements Verification:

• Create checklist from plan document
• Verify each requirement systematically
• Provide evidence for each verification
• Report completion status with gaps

Step 9: Prevent Premature Claims

Implement verification gates before any success communication:

// Verification gate function
function verificationGate(claim, context) {
  return new Promise((resolve, reject) => {
    // Prevent premature claims
    if (isSuccessClaim(claim) && !hasFreshVerification(context)) {
      reject(new Error('Cannot make success claims without fresh verification'));
    }

    // Require verification for critical actions
    if (isCriticalAction(context.action)) {
      const verification = runVerification(getVerificationCommand(claim));
      if (!verification.success) {
        reject(new Error(`Verification failed: ${verification.errorMessage}`));
      }
    }

    resolve(true);
  });
}

// Critical actions requiring verification
const criticalActions = [
  'commit', 'push', 'create-pr', 'mark-complete',
  'claim-success', 'express-satisfaction', 'delegate-completion'
];

Verification Gates:

• Block premature success claims
• Require verification for critical actions
• Prevent unverified commits/pushes
• Enforce evidence-based communication

Step 10: Document Verification Results

Record verification evidence for audit trail:

// Document verification for audit trail
function documentVerification(claim, verificationResults, context) {
  const verificationRecord = {
    timestamp: new Date().toISOString(),
    claim: claim,
    command: verificationResults.command,
    exitCode: verificationResults.exitCode,
    output: verificationResults.output,
    success: verificationResults.success,
    context: context,
    verifiedBy: 'verification-before-completion-skill'
  };

  // Store in verification log
  appendToVerificationLog(verificationRecord);

  // Include in commit messages if applicable
  if (context.action === 'commit') {
    return `Verification: ${verificationResults.summary}`;
  }

  return verificationRecord;
}

Verification Documentation:

• Timestamp all verifications
• Record command and results
• Maintain audit trail
• Include in version control history

Success Criteria

• Fresh verification command executed before any claims
• Complete output analyzed (not partial checks)
• Exit codes verified (0 for success)
• Failure counts accurately reported
• Claims match verification evidence exactly
• Agent work verified independently
• Red-green cycle completed for regression tests
• Requirements checklist fully verified
• No premature success expressions
• Verification results documented

Common Pitfalls

1. Trusting Previous Runs - Always run fresh verification
2. Partial Output Reading - Read complete command output
3. Ignoring Exit Codes - Check exit codes, not just output appearance
4. Agent Report Reliance - Verify agent work independently
5. Premature Satisfaction - Never express success before verification
6. Confidence-Based Claims - Evidence required, not confidence
7. Shortcut Temptation - No exceptions for "obvious" cases

Verification Command Reference

Testing Verification

# Unit tests
npm test -- --testPathPattern=component.test.js

# Integration tests  
npm run test:integration

# E2E tests
npm run test:e2e

# Specific test file
npm test path/to/specific.test.js

Build Verification

# Full build
npm run build

# Production build
npm run build:prod

# Type checking
npx tsc --noEmit

Code Quality Verification

# Linting
npm run lint

# Formatting check
npm run format:check

# Security audit
npm audit

Requirements Verification

# Manual checklist verification
# (Review plan document against implementation)

Cross-References

Related Procedures

• Testing Framework Guide - Testing verification methods
• Error Fixes Summary - Common verification failures

Related Skills

• testing-verification - Comprehensive testing strategies
• systematic-debugging - Debugging verification failures
• test-driven-development - Test-first development with verification

Related Agents

• QualityForge_AI_Team - Verification assistance and quality checks
• DevForge_AI_Team - Implementation verification support

Performance Metrics

• Application Frequency: Used in 95% of development tasks
• Success Rate: 96% of verifications completed correctly
• False Claims Prevented: 85% reduction in unverified success claims
• Trust Building: 90% improvement in stakeholder confidence

The Bottom Line

No shortcuts for verification.

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

This is non-negotiable.