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.

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 confidence is high
• Agent reports success or tests "should" pass

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Without running the verification command in this message, claiming success is not allowed.

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

STOP when:

• 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: "Lying leads to replacement"

Navigation

For detailed information:

• [Gate Function](references/gate-function.md): Complete five-step verification process with decision trees
• [Verification Patterns](references/verification-patterns.md): Correct verification patterns for tests, builds, deployments, and more
• [Red Flags and Failures](references/red-flags-and-failures.md): Common failure modes, red flags, and real-world examples with time/cost data
• [Integration and Workflows](references/integration-and-workflows.md): Integration with other skills, CI/CD patterns, and agent delegation workflows

The Bottom Line

No shortcuts for verification.

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

This is non-negotiable.

The Gate Function

The gate function is the mandatory checkpoint before ANY completion claim.

The Complete 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

Step-by-Step Breakdown

Step 1: IDENTIFY

What to identify:

• The exact command that proves your claim
• Not a related command
• Not a partial command
• The FULL verification command

Examples:

Common Mistakes:

• ❌ Identifying related but insufficient command
• ❌ Identifying partial verification
• ❌ Identifying old verification results
• ❌ Can't identify verification → Claim invalid

Step 2: RUN

How to run:

• Execute the COMPLETE command
• Fresh execution (not cached results)
• Full scope (not subset)
• Right here, right now (not "I ran it earlier")

Requirements:

• Use exact command identified in Step 1
• Run in correct environment
• Include all parameters/flags
• Wait for complete execution

Common Mistakes:

• ❌ Running partial command
• ❌ Using cached/previous results
• ❌ Running related but different command
• ❌ Assuming results without running

Examples:

✅ Correct:

# Full test suite, right now
pytest tests/

❌ Incorrect:

# Only one test file
pytest tests/test_auth.py

# Previous run (stale)
"I ran tests 10 minutes ago"

# Related but not sufficient
ruff check .  # This is linter, not tests

Step 3: READ

What to read:

• COMPLETE output, not just summary
• Exit code (0 = success, non-zero = failure)
• Count of passes/failures
• Error messages if any
• Warnings if any

How to read:

• Scroll through entire output
• Don't skip "boring" parts
• Check final status line
• Verify exit code
• Count specific numbers

Common Mistakes:

• ❌ Reading only summary
• ❌ Skipping error details
• ❌ Ignoring warnings
• ❌ Not checking exit code
• ❌ Assuming from first few lines

Examples:

✅ Correct Reading:

pytest tests/
...
[complete output]
...
====== 34 passed in 2.45s ======
Exit code: 0

Conclusion: 34 tests, ALL passed, 0 failed

❌ Incorrect Reading:

pytest tests/
[output appears...]
"Looks like tests are passing"  ← Didn't read to end

Step 4: VERIFY

Verification questions: 1. Does output match claim exactly? 2. Are there any failures/errors? 3. Is exit code 0 (success)? 4. Are counts what expected? 5. Are there warnings to address?

Decision tree:

Output confirms claim?
├─ YES → Proceed to Step 5 (claim with evidence)
└─ NO  → Report actual status with evidence
    - Don't claim success
    - Report what actually happened
    - Include evidence of actual state

Examples:

✅ Output Confirms Claim:

Claim: "All tests pass"
Output: "34 passed, 0 failed"
Exit Code: 0
Verification: YES → Safe to claim

❌ Output Contradicts Claim:

Claim: "All tests pass"
Output: "31 passed, 3 failed"
Exit Code: 1
Verification: NO → Cannot claim
Correct response: "31/34 tests pass, 3 failing: test_auth, test_db, test_api"

Step 5: CLAIM

Only reach this step if:

• ✅ Identified correct verification
• ✅ Ran complete command
• ✅ Read full output
• ✅ Output confirms claim

How to claim:

[Evidence] + [Claim]

Example: "All 34 tests pass (pytest output: 34/34 passed, exit 0)"

Structure: 1. State the evidence first 2. Then make the claim 3. Include specific numbers 4. Reference verification command

Examples:

✅ Correct Claims:

"pytest output: 34/34 passed → All tests pass"
"make build: exit 0, dist/ created → Build succeeds"
"ruff check: 0 errors, 0 warnings → Linter clean"
"curl https://api.example.com: 200 OK → Endpoint accessible"

❌ Incorrect Claims:

"Should pass now" ← No evidence
"Tests pass" ← No evidence shown
"Looks good" ← Subjective, no evidence
"Fixed!" ← No verification

Common Gate Function Violations

Violation 1: Skipping IDENTIFY

Symptom: Can't name verification command Fix: If you can't identify verification, claim is invalid

Violation 2: Skipping RUN

Symptom: Using old results, assuming outcomes Fix: Fresh execution required, every time

Violation 3: Skipping READ

Symptom: Making claims without reading output Fix: Read COMPLETE output before claiming

Violation 4: Skipping VERIFY

Symptom: Claiming success despite failures in output Fix: Match output to claim, report reality

Violation 5: Claiming Despite Failure

Symptom: Tests fail but claim "mostly works" Fix: Report actual state: "31/34 pass, 3 failing"

Gate Function for Different Contexts

Before Committing

GATE CHECK:
1. IDENTIFY: git diff, test suite, linter
2. RUN: git diff && pytest && ruff check .
3. READ: Full output of all three
4. VERIFY: No uncommitted junk, all tests pass, linter clean
5. CLAIM: "Ready to commit" OR report issues found

Before Creating PR

GATE CHECK:
1. IDENTIFY: Full test suite, requirements checklist, diff review
2. RUN: pytest && git diff main...HEAD
3. READ: Test results + all changes made
4. VERIFY: Tests pass, changes match requirements
5. CLAIM: "Ready for PR" OR report gaps

Before Marking Task Complete

GATE CHECK:
1. IDENTIFY: Requirements list, verification commands
2. RUN: Check each requirement individually
3. READ: Results of each verification
4. VERIFY: All requirements met
5. CLAIM: "Task complete: 5/5 requirements met" OR "4/5 met, missing X"

Before Delegating to Agent

GATE CHECK:
1. IDENTIFY: What agent should accomplish
2. RUN: Agent execution
3. READ: Agent report AND git diff
4. VERIFY: Changes match task, no surprises
5. CLAIM: "Agent completed X, verified by diff" OR "Agent attempted but Y issue found"

Before Deployment

GATE CHECK:
1. IDENTIFY: Build, tests, smoke tests, health checks
2. RUN: Full build + test suite
3. READ: All outputs
4. VERIFY: All pass, ready to deploy
5. CLAIM: "Ready for deployment" OR report blockers

The Iron Law Explained

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

"No completion claims" = ANY variation:

• "Done", "Complete", "Finished", "Success"
• "Fixed", "Working", "Passing", "Clean"
• "Ready", "Good to go", "All set"
• ANY paraphrase or synonym

"Without fresh verification" = Must have:

• Run command in this session
• Read complete output
• Verified results match claim
• Evidence is current (not stale)

"Evidence" = Must include:

• Specific command run
• Specific output received
• Specific numbers/counts
• Exit codes where applicable

Why Every Step Matters

Skip IDENTIFY: Don't know what to verify → Can't verify → Can't claim Skip RUN: No current evidence → Claiming based on hope → Lying Skip READ: Don't know actual results → Assuming → Lying Skip VERIFY: Results might contradict claim → Claiming anyway → Lying Skip any step: Broke verification process → Cannot be trusted

The Bottom Line

The gate function is non-negotiable. Every completion claim must pass through it.

No shortcuts. No exceptions. No assumptions.

Run the command. Read the output. Verify the result. Then claim.

Integration and Workflows

How verification-before-completion integrates with other skills and common workflows.

Integration with Other Skills

Systematic Debugging

When debugging, verification prevents false confidence in fixes:

1. Reproduce bug (systematic-debugging Phase 1)
2. Investigate root cause (systematic-debugging Phase 1)
3. Form hypothesis (systematic-debugging Phase 3)
4. Implement fix (systematic-debugging Phase 4)
5. ⚠️ GATE FUNCTION: Verify fix works (verification-before-completion)
   - Run reproduction case → Must pass
   - Run full test suite → Must pass
   - THEN claim "Bug fixed"

Integration points:

• After Phase 1 (Investigation): Verify you can reproduce consistently
• After Phase 4 (Implementation): Verify fix actually works
• Never claim fix without verification

Common mistakes:

• ❌ "Logic looks correct" → Verify it works
• ❌ "Should fix the bug" → Run reproduction test
• ❌ "Code changed" → Verify behavior changed

Test-Driven Development (TDD)

TDD red-green cycle requires verification at each step:

1. Write test (TDD)
2. ⚠️ VERIFY: Test fails (RED) - proves it catches bug
3. Implement code (TDD)
4. ⚠️ VERIFY: Test passes (GREEN) - proves fix works
5. Revert code temporarily
6. ⚠️ VERIFY: Test fails again (RED) - proves test isn't false positive
7. Restore code
8. ⚠️ VERIFY: Test passes (GREEN) - final confirmation

Integration points:

• Every transition in red-green cycle needs verification
• Never assume test state, always verify
• Document verification evidence for each step

Why critical:

• Test passing immediately = test doesn't catch bug
• Skip verification = false confidence in test coverage

Condition-Based Waiting

When waiting for conditions, verify they're actually met:

1. Identify condition to wait for (condition-based-waiting)
2. Implement wait logic
3. ⚠️ GATE FUNCTION: Verify condition actually met
   - Check condition state
   - Don't assume timeout = success
   - THEN proceed

Integration points:

• After wait completes: Verify condition met, not just timeout elapsed
• Replace "waited long enough" with "verified condition met"

Common mistakes:

• ❌ "Waited 5 seconds" → Verify condition met
• ❌ "Should be ready now" → Check actual state

Root-Cause Tracing

When tracing root causes, verify your understanding:

1. Trace back through call stack (root-cause-tracing)
2. Identify suspected root cause
3. ⚠️ GATE FUNCTION: Verify root cause identified
   - Test hypothesis
   - Can you reproduce by triggering suspected cause?
   - THEN claim root cause found

Integration points:

• After identifying root cause: Verify it's truly the cause
• Test by removing suspected cause: Problem should disappear
• Never claim root cause without verification

Workflow Examples

Feature Development Workflow

1. Read requirements
2. Write tests (TDD)
3. ⚠️ VERIFY: Tests fail (red)
4. Implement feature
5. ⚠️ VERIFY: Tests pass (green)
6. ⚠️ VERIFY: All requirements met (checklist)
7. ⚠️ VERIFY: Full test suite passes
8. ⚠️ VERIFY: Linter clean
9. ⚠️ VERIFY: Build succeeds
10. THEN commit

Verification points: 5 gates before commit

Bug Fix Workflow

1. Reproduce bug
2. ⚠️ VERIFY: Can reproduce consistently
3. Investigate root cause (systematic-debugging)
4. ⚠️ VERIFY: Root cause identified
5. Write regression test
6. ⚠️ VERIFY: Test fails (catches bug)
7. Implement fix
8. ⚠️ VERIFY: Regression test passes
9. ⚠️ VERIFY: Full test suite passes (no regressions)
10. THEN claim bug fixed

Verification points: 5 gates before claiming fixed

Refactoring Workflow

1. Identify code to refactor
2. ⚠️ VERIFY: All tests pass (baseline)
3. Make refactoring changes
4. ⚠️ VERIFY: All tests still pass
5. ⚠️ VERIFY: Behavior unchanged
6. ⚠️ VERIFY: Performance not degraded
7. THEN claim refactoring complete

Verification points: 4 gates ensuring safe refactoring

Code Review Workflow

As reviewer:

1. Read PR description and requirements
2. Review code changes (git diff)
3. ⚠️ VERIFY: Can't trust PR author verification
4. Checkout branch locally
5. ⚠️ VERIFY: Tests pass
6. ⚠️ VERIFY: Build succeeds
7. ⚠️ VERIFY: Requirements met
8. THEN approve PR

As author:

1. Complete feature/fix
2. ⚠️ VERIFY: All local checks pass
3. Push to branch
4. ⚠️ VERIFY: CI pipeline passes
5. Create PR with evidence
6. THEN request review

Agent Delegation Workflows

Delegating to AI Agent

Before delegation:

1. Define task clearly
2. Specify verification criteria
3. Delegate to agent

After agent reports completion:

4. ⚠️ NEVER trust agent report
5. Check git diff: What actually changed?
6. ⚠️ VERIFY: Run tests
7. ⚠️ VERIFY: Run build
8. ⚠️ VERIFY: Check requirements met
9. ⚠️ VERIFY: No unexpected changes
10. ⚠️ VERIFY: No secrets added
11. THEN accept or reject

Critical rule: Agent success reports are NOT verification

Agent Verification Checklist

For every agent task completion:

[ ] Reviewed complete git diff
[ ] Ran full test suite
[ ] Checked build succeeds
[ ] Verified requirements met
[ ] No TODO/placeholder code
[ ] No commented-out code
[ ] No secrets in code
[ ] No unrelated changes
[ ] Dependencies appropriate
[ ] Code quality acceptable

Only after ALL checks pass: Accept agent work

Multi-Agent Workflows

When coordinating multiple agents:

1. Agent A completes task
2. ⚠️ VERIFY: Agent A work correct
3. Agent B completes dependent task
4. ⚠️ VERIFY: Agent B work correct
5. ⚠️ VERIFY: Integration works (A + B together)
6. THEN proceed

Each agent verified independently, then verify integration

CI/CD Pipeline Integration

Pre-Commit Hook Verification

#!/bin/bash
# .git/hooks/pre-commit

# GATE FUNCTION: Verify before allowing commit

echo "Running pre-commit verification..."

# Test verification
pytest tests/ || exit 1
echo "✅ Tests pass"

# Linter verification
ruff check . || exit 1
echo "✅ Linter clean"

# Build verification
make build || exit 1
echo "✅ Build succeeds"

echo "✅ All verifications pass - commit allowed"

Enforces gate function at commit time

CI Pipeline Stages

# .github/workflows/ci.yml

name: CI Pipeline with Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      # Stage 1: Build
      - name: Build
        run: make build
      - name: Verify build artifacts
        run: ls dist/ && test -f dist/app

      # Stage 2: Test
      - name: Run tests
        run: pytest tests/
      - name: Verify test results
        run: |
          # Parse test output
          # Verify 0 failures

      # Stage 3: Lint
      - name: Run linter
        run: ruff check .
      - name: Verify linter output
        run: |
          # Verify 0 violations

      # Stage 4: Security
      - name: Security scan
        run: bandit -r .
      - name: Verify no critical issues
        run: |
          # Parse security output
          # Verify 0 high/critical

Each stage has verification step

Deployment Pipeline Verification

deploy:
  needs: verify
  steps:
    # Deploy
    - name: Deploy to staging
      run: ./deploy.sh staging

    # Verify deployment
    - name: Verify endpoint accessible
      run: curl -f https://staging.example.com/health

    - name: Verify application responding
      run: |
        response=$(curl -s https://staging.example.com/api/status)
        if [ "$response" != "OK" ]; then
          echo "Deployment verification failed"
          exit 1
        fi

    - name: Run smoke tests
      run: pytest tests/smoke/

    # Only proceed if all verifications pass
    - name: Deploy to production
      if: success()
      run: ./deploy.sh production

Production deployment only after staging verification

Team Workflows

Pull Request Template

## Description
[What changed and why]

## Verification Evidence

### Tests
- [ ] All tests pass
- Command: `pytest tests/`
- Output: [paste output showing pass count]
- Exit code: 0

### Build
- [ ] Build succeeds
- Command: `make build`
- Output: [paste relevant output]
- Artifacts: [list created artifacts]

### Requirements
- [ ] Requirement 1: [evidence]
- [ ] Requirement 2: [evidence]
- [ ] Requirement 3: [evidence]

### Manual Testing
- [ ] Tested scenario 1: [result]
- [ ] Tested scenario 2: [result]

## CI Pipeline
- [ ] All CI checks pass
- Link: [CI run URL]

Forces verification evidence collection

Code Review Checklist

For reviewers:

[ ] Author provided verification evidence
[ ] Checked out branch locally
[ ] Ran tests myself (don't trust author claim)
[ ] Verified build succeeds
[ ] Checked requirements met
[ ] Reviewed all changes in diff
[ ] No secrets added
[ ] Code quality acceptable

Reviewer must independently verify

Emergency Workflows

Production Hotfix Workflow

Even under extreme time pressure:

1. Reproduce production issue
2. ⚠️ VERIFY: Can reproduce locally
3. Implement minimal fix
4. ⚠️ VERIFY: Fix works locally
5. ⚠️ VERIFY: Tests pass
6. Deploy to staging
7. ⚠️ VERIFY: Fix works in staging
8. ⚠️ VERIFY: No new issues introduced
9. Deploy to production
10. ⚠️ VERIFY: Fix works in production
11. ⚠️ VERIFY: Monitor error rates
12. THEN claim hotfix complete

Time pressure = MORE verification needed, not less

Rollback Verification

When rolling back:

1. Trigger rollback
2. ⚠️ VERIFY: Rollback completed
3. ⚠️ VERIFY: Application responding
4. ⚠️ VERIFY: Error rates normal
5. ⚠️ VERIFY: Key user flows work
6. THEN communicate "Rollback successful"

Never assume rollback worked - verify it

Documentation Workflows

Documentation Update Workflow

1. Update documentation
2. Have fresh user read it
3. ⚠️ VERIFY: User can follow steps successfully
4. ⚠️ VERIFY: All code examples work
5. ⚠️ VERIFY: All links valid
6. ⚠️ VERIFY: Screenshots current
7. THEN claim documentation complete

API Documentation Workflow

1. Document API endpoints
2. Include request/response examples
3. ⚠️ VERIFY: Can run examples with curl
4. ⚠️ VERIFY: Response matches documentation
5. ⚠️ VERIFY: All error codes documented
6. ⚠️ VERIFY: All parameters documented
7. THEN publish API docs

Metrics and Monitoring

Tracking Verification Compliance

Metrics to track:

• % of commits with verification evidence
• % of PRs with verification evidence
• % of deployments with post-deployment verification
• False positive rate (unverified claims that failed)
• Time spent on verification vs debugging unverified work

Goals:

• 100% verification compliance
• < 5% false positive rate
• Verification time << debugging time saved

Automation Opportunities

What to automate:

• Pre-commit hooks enforce verification
• CI pipelines enforce verification gates
• PR templates require verification evidence
• Deployment scripts include verification steps

What NOT to automate:

• Reading verification output (human must read)
• Making verification claims (human responsibility)
• Judging if verification is sufficient (requires judgment)

The Bottom Line

Verification-before-completion is:

• Non-negotiable in every workflow
• More critical under time pressure, not less
• Required for agent work, never trust agent reports
• Enforced through automation where possible
• Cultural - team practice, not individual choice

Integration principle: Every workflow completion point needs a verification gate.

No shortcuts. No exceptions. No workflow bypasses verification.

Red Flags and Common Failures

Understanding failure modes helps recognize when verification is being skipped.

When to Use This Skill - Detailed Triggers

Activate verification ALWAYS before:

• ANY variation of success/completion claims: "Done", "Complete", "Finished", "Success", "Fixed", "Working", "Passing", "Clean", "Ready"
• ANY expression of satisfaction: "Great!", "Perfect!", "Excellent!", "Awesome!", "Nice!", "Good!"
• ANY positive statement about work state: "Looking good", "Should work", "Seems fine"
• Version control operations: Committing, pushing, creating PRs, merging branches
• Task transitions: Moving to next task, marking tasks complete, closing tickets
• Delegation: Handing off to agents, other developers, or automation
• Status reporting: Updating stakeholders, writing status updates, daily standups
• Pre-deployment: Before staging deployment, production deployment, releases
• Documentation claims: "Documentation complete", "README updated"
• Performance claims: "Optimization complete", "Performance improved"
• Security claims: "Security issue fixed", "Vulnerability patched"

Use this ESPECIALLY when:

• Time pressure: Deadlines making verification "optional"
• Fatigue: Tired and wanting work to be over
• Confidence: "Quick fix" seems obvious or you're very confident
• Repetition: "Done this before", familiar patterns
• Agent reports: Agent claims success or completion
• Test expectations: Tests "should" pass based on changes
• Simple changes: "Just one line", "trivial fix"
• Review pressure: Waiting reviewers or blocked team members
• Multi-tasking: Juggling multiple tasks simultaneously
• Context switching: Returning to work after interruption

Common Failure Modes Table

Red Flags - STOP Immediately

Language Red Flags

If you catch yourself using:

• "Should" - "Should work now", "Should pass", "Should be fixed"
• "Probably" - "Probably works", "Probably passes"
• "Seems to" - "Seems to work", "Seems correct"
• "Looks like" - "Looks good", "Looks correct"
• "I think" - "I think it's fixed", "I think tests pass"
• "Appears to" - "Appears working", "Appears correct"
• "Likely" - "Likely fixed", "Likely working"
• "Pretty sure" - "Pretty sure it works"
• "Confident" - "Confident it passes"
• "Expect" - "Expect tests to pass"

ALL of these = NO VERIFICATION OCCURRED

Premature Satisfaction

Expressing satisfaction BEFORE verification:

• "Great!" before running tests
• "Perfect!" before checking build
• "Done!" before verifying completion
• "Excellent!" before confirming results
• "Success!" before reading output
• "Fixed!" before testing reproduction
• "Nice!" before validation
• "Awesome!" before confirmation

Satisfaction ONLY AFTER verification evidence

Process Red Flags

• About to commit without running tests
• About to push without verification
• About to create PR without checking
• Moving to next task without confirming current
• Trusting agent reports without checking
• Relying on partial verification ("just linter")
• Thinking "just this once" (no exceptions)
• Tired and wanting work to be over
• Time pressure making verification "optional"
• Confident based on similar past work
• "Quick change" doesn't need verification
• Demo worked, assuming production ready

Rationalization Prevention

Common excuses and their realities:

Why These Excuses Fail

"Should work now"

• Software doesn't work on should
• Should = guess, not fact
• Run the command, get the fact
• Real cost: 120+ minutes debugging when wrong
• Verification cost: 2 minutes

"I'm confident"

• Confidence is feeling, not evidence
• Most confident when most wrong (Dunning-Kruger effect)
• Evidence trumps confidence always
• Real example: "Confident" fix broke 4 tests, 2 hours recovery

"Just this once"

• Once becomes habit
• Standards erode gradually
• No exceptions maintains discipline
• Slippery slope: First skip leads to regular skipping

"Linter passed so build should work"

• Linter checks style, not compilation
• Build checks compilation, not runtime
• Tests check runtime, not requirements
• Each layer separate verification
• Real example: Clean linter, build failed (TypeScript errors), deployment blocked

"Agent said success"

• Agents report what they believe
• Agents can misinterpret results
• Agents don't have full context
• Independent verification required
• Real example: Agent reported "tests passing", introduced syntax error, tests couldn't run

"I'm tired"

• Fatigue increases error rate
• Makes verification MORE important
• Shortcutting when tired = guaranteed bugs
• Better to stop than skip verification
• Statistics: 3x higher error rate when fatigued

"Partial verification enough"

• Partial verification = no verification
• Untested parts always break
• "Just the important parts" misjudges importance
• Full verification or none
• Real example: Verified auth, skipped API routes, 3 endpoints broken

"Time pressure"

• Verification: 2-5 minutes
• Fixing unverified work: 60-180 minutes
• Verification SAVES time under pressure
• Math: 60x more expensive to skip

"Demo worked"

• Demos use happy path only
• Production has edge cases, error paths
• Demo environment ≠ production environment
• Real example: Demo perfect, production crashed on null input

Real-World Failure Examples with Time/Cost Data

Example 1: "Tests should pass"

Context: Backend API development, deadline pressure What happened:

• Claimed tests pass without running
• 4 tests actually failing (validation logic)
• Pushed to main, broke CI
• Blocked 3 other developers

Time cost:

• Would have taken: 2 minutes (run pytest)
• Actually took: 2 hours debugging + 30 minutes team coordination
• Cost multiplier: 75x

Lesson: "Should" ≠ "Do". Always run.

Example 2: "Linter clean, so build works"

Context: TypeScript frontend, production deployment What happened:

• Linter passed (style check)
• Build failed (TypeScript type errors)
• Assumed linter = build verification
• Deployment blocked, hotfix needed

Time cost:

• Would have taken: 3 minutes (npm run build)
• Actually took: 90 minutes (find errors, fix, re-deploy)
• Cost multiplier: 30x

Lesson: Each verification layer separate.

Example 3: Trusted agent report

Context: Agent-assisted refactoring What happened:

• Agent reported "tests passing"
• Didn't check git diff
• Agent introduced syntax error
• Tests couldn't even run
• Reverted all changes, manual redo

Time cost:

• Would have taken: 2 minutes (git diff + pytest)
• Actually took: 3 hours (debug, revert, redo work)
• Cost multiplier: 90x

Lesson: Always verify agent work independently.

Example 4: "I'm confident this fixes it"

Context: Bug fix for customer-reported issue What happened:

• Confident in fix logic
• Didn't test reproduction case
• Bug still present, different symptom
• Customer reported immediately
• Trust damaged with customer

Time cost:

• Would have taken: 5 minutes (test reproduction)
• Actually took: 4 hours (customer support, investigation, actual fix)
• Cost multiplier: 48x
• Additional cost: Customer trust violation

Lesson: Confidence ≠ evidence.

Example 5: "Just one quick fix before verification"

Context: Race condition bug fix What happened:

• Made "quick fix" without testing
• Introduced new bug (null pointer)
• Now debugging 2 bugs instead of 1
• Should have verified first fix first

Time cost:

• Would have taken: 3 minutes (run affected tests)
• Actually took: 2.5 hours (debug compound issue)
• Cost multiplier: 50x

Lesson: Never "one more fix" without verification.

Example 6: "Linter passed, committed"

Context: Python API endpoint development What happened:

• Ran ruff linter: clean
• Committed without running tests
• 6 tests failing (business logic errors)
• CI pipeline red, blocking team

Time cost:

• Would have taken: 2 minutes (pytest)
• Actually took: 90 minutes (find failures, fix, force push)
• Cost multiplier: 45x

Lesson: Linter ≠ tests. Run both.

Example 7: "Demo worked perfectly"

Context: Feature demo to stakeholders What happened:

• Demo used happy path only
• Didn't test error cases
• Deployed to staging
• Crashed on first null input
• Emergency rollback

Time cost:

• Would have taken: 10 minutes (edge case testing)
• Actually took: 3 hours (emergency response, fix, re-deploy)
• Cost multiplier: 18x

Lesson: Demo ≠ complete verification.

Example 8: "Agent refactored successfully"

Context: Code cleanup with AI agent What happened:

• Agent reported "refactoring complete"
• Didn't review changes (200 lines)
• Agent removed critical validation
• Security vulnerability introduced

Time cost:

• Would have taken: 5 minutes (git diff review)
• Actually took: 6 hours (security audit, fix, verification)
• Cost multiplier: 72x
• Additional cost: Security risk

Lesson: Always review agent changes.

Example 9: "Too tired to run tests"

Context: Late night bug fix What happened:

• Fixed bug at 11pm
• "Too tired" to run test suite
• Committed and went to bed
• Broke 3 unrelated features
• Morning crisis meeting

Time cost:

• Would have taken: 3 minutes (test suite)
• Actually took: 4 hours (morning debugging, team impact)
• Cost multiplier: 80x
• Additional cost: Team morale impact

Lesson: Too tired to verify = too tired to commit.

Example 10: "Looks good in local dev"

Context: Database migration What happened:

• Migration worked in local environment
• Deployed to staging without testing
• Production data structure different
• Migration corrupted data
• 2-day recovery process

Time cost:

• Would have taken: 10 minutes (staging test)
• Actually took: 16 hours (data recovery, investigation)
• Cost multiplier: 96x
• Additional cost: Data integrity incident

Lesson: Local ≠ staging ≠ production. Test each.

Example 11: "Build succeeded, ready to deploy"

Context: Microservice deployment What happened:

• Build passed successfully
• Didn't run integration tests
• Deployed to production
• Service couldn't connect to database
• Emergency rollback

Time cost:

• Would have taken: 5 minutes (integration tests)
• Actually took: 2 hours (rollback, debug, fix, re-deploy)
• Cost multiplier: 24x

Lesson: Build ≠ integration ≠ deployment ready.

Example 12: "Performance should be better"

Context: API optimization work What happened:

• Implemented caching layer
• Assumed performance improved
• Didn't benchmark
• Actually 20% slower (cache overhead)
• Reverted optimization

Time cost:

• Would have taken: 5 minutes (benchmark run)
• Actually took: 3 hours (deploy, discover, investigate, revert)
• Cost multiplier: 36x

Lesson: Measure performance, don't assume.

Pattern Recognition

Healthy Pattern:

Implement → Verify → Claim → Next
Implement → Verify → Claim → Next

Unhealthy Pattern:

Implement → Implement → Implement → Assume → Claim

Death Spiral Pattern:

Implement → Fails → "One more fix" → Fails → "Just needs..." → Fails → "Almost there..." → Fails

When you see yourself in "one more fix" mode, STOP: 1. Return to root cause investigation 2. Question your understanding 3. Verify each assumption 4. Consider architectural issues 5. Get second opinion

Cultural Red Flags

Organizational patterns that enable verification skipping:

• "Move fast and break things" (without fixing) - Chaos, not velocity
• "We'll catch it in QA" (QA not a safety net) - QA finds gaps, not basic verification
• "Trust the developer" (trust + verify) - Trust requires verification
• "Time pressure" used as excuse - Verification saves time
• "Good enough for now" acceptance - Technical debt accumulation
• Rewarding speed over correctness - Creates perverse incentives
• "Ship and iterate" (without verification) - Shipping broken code
• "Fail fast" (without learning) - Same failures repeated
• Blaming individuals for systemic failures - Process problem, not people

None of these excuse skipping verification.

Cost-Benefit Analysis

Verification Investment

• Time per verification: 2-5 minutes average
• Frequency: Every completion claim
• Daily investment: 10-20 minutes for typical developer

Skipping Costs

• Debug time when wrong: 60-180 minutes average
• Team impact: 2-5 developer-hours blocked
• Trust damage: Immeasurable
• Production incidents: Critical severity
• Customer impact: Revenue/reputation loss

ROI Calculation

• Average cost multiplier: 60x
• False negative rate: 40% of unverified claims fail
• Expected value: Verification ALWAYS saves time

Mathematical certainty: Always verify.

The Bottom Line

Every excuse is a rationalization for: 1. Not wanting to verify 2. Hoping it works 3. Avoiding accountability 4. Wishful thinking

Solution: Run the command. Read the output. Then claim the result.

No shortcuts. No exceptions. No rationalizations.

Remember: 2 minutes now or 120 minutes later. Your choice.

Verification Patterns

Complete patterns for verifying different types of claims before making them.

Test Verification

Correct Pattern:

1. Run full test suite: pytest tests/
2. Read complete output
3. Count: 34 tests, 34 passed, 0 failed
4. Claim: "All 34 tests pass"

Incorrect Patterns:

• ❌ "Should pass now" (no evidence)
• ❌ "Looks correct" (subjective)
• ❌ "Tests were passing earlier" (stale)
• ❌ "I fixed the issue" (assumes, doesn't verify)

Evidence Required:

• Full test command executed
• Complete output visible
• Exact pass/fail counts
• Exit code confirmed (0 = success)

Edge Cases:

• Flaky tests: Run multiple times, document flakiness
• Timeout tests: Verify timeout values appropriate
• Skipped tests: Count and document why skipped
• Warnings in output: Document and address

Troubleshooting:

• Tests hang: Check for infinite loops, deadlocks
• Random failures: Run 10x, identify flaky tests
• Environment issues: Verify dependencies, config
• Coverage gaps: Check coverage report for holes

Regression Test Verification (TDD Red-Green Cycle)

Correct Pattern:

1. Write regression test
2. Run test → MUST FAIL (RED)
3. Implement fix
4. Run test → MUST PASS (GREEN)
5. Revert fix temporarily
6. Run test → MUST FAIL AGAIN (confirms test works)
7. Restore fix
8. Run test → MUST PASS (final confirmation)

Why Red-Green-Red-Green?

• First RED: Confirms test catches the bug
• GREEN: Confirms fix works
• Second RED: Confirms test isn't passing by accident
• Final GREEN: Confirms fix is stable

Incorrect Patterns:

• ❌ "I've written a regression test" (didn't verify it fails)
• ❌ Test passes on first run (never confirmed it catches bug)
• ❌ Single pass without reverting (could be false positive)

Edge Cases:

• Test passes immediately: Test doesn't catch bug, rewrite
• Test fails differently: Fix changed behavior, investigate
• Can't revert cleanly: Use version control, stash changes

Build Verification

Correct Pattern:

1. Run full build: make build
2. Read complete output
3. Check exit code: echo $? → 0
4. Verify artifacts created: ls dist/
5. Claim: "Build succeeds, artifacts in dist/"

Incorrect Patterns:

• ❌ "Linter passed, so build should work" (linter ≠ compiler)
• ❌ "No errors in logs" (didn't actually build)
• ❌ "Build was working earlier" (stale verification)

Common Gotchas:

• Linter passing ≠ compilation passing
• TypeScript errors ≠ build errors
• Local build ≠ CI build
• Dev build ≠ production build

Build Types to Verify:

• Development build: Fast iteration
• Production build: Minification, optimization
• Test build: Coverage instrumentation
• Distribution build: Platform-specific artifacts

Troubleshooting:

• Build succeeds but artifacts missing: Check output directory
• Incremental build issues: Clean build, verify again
• Platform-specific failures: Test on target platform
• Resource exhaustion: Check memory, disk space

Linter Verification

Correct Pattern:

1. Run linter: ruff check .
2. Read full output
3. Count violations: 0 errors, 0 warnings
4. Check exit code: 0
5. Claim: "Linter clean (0 violations)"

Incorrect Patterns:

• ❌ "Fixed the obvious issues" (partial check)
• ❌ "Linter passed on one file" (not comprehensive)
• ❌ "Should be clean now" (no verification)

Multiple Linters Pattern:

1. Run each linter separately
2. Verify each independently
3. Document results for each
4. Only claim clean if ALL pass

Edge Cases:

• Warnings vs errors: Document acceptable warnings
• Auto-fix available: Run auto-fix, verify results
• Custom rules: Verify custom rules active
• Ignored files: Document why files ignored

Bug Fix Verification

Correct Pattern:

1. Document original symptom
2. Create reproduction steps
3. Run reproduction → FAILS (confirms bug)
4. Implement fix
5. Run reproduction → PASSES
6. Run full test suite → PASSES (no regressions)
7. Claim: "Bug fixed, verified with reproduction and tests"

Incorrect Patterns:

• ❌ "Code changed, bug should be fixed" (assumes)
• ❌ "Logic looks correct" (theory, not evidence)
• ❌ "Can't reproduce anymore" (didn't verify with test)

Bug Types:

• Logic bugs: Unit test verifies correct behavior
• Race conditions: Stress test, run 100x
• Edge cases: Test boundary conditions
• Integration bugs: End-to-end test verifies
• Performance bugs: Benchmark before/after

Troubleshooting:

• Can't reproduce: Document steps, environment
• Intermittent bug: Increase test iterations
• Different in production: Test in production-like environment
• Fix causes regression: Test full suite, not just bug test

Requirements Verification

Correct Pattern:

1. Re-read original requirements
2. Create line-by-line checklist
3. Verify each requirement individually
4. Document evidence for each
5. Report: "5/5 requirements met" OR "4/5 met, missing X"

Incorrect Patterns:

• ❌ "Tests pass, so requirements met" (tests ≠ requirements)
• ❌ "I implemented what was asked" (subjective)
• ❌ "Phase complete" (vague, no checklist)

Requirement Types:

• Functional: Feature works as specified
• Non-functional: Performance, scalability, security
• User experience: UI/UX matches design
• Integration: Works with other systems
• Documentation: Docs complete and accurate

Checklist Format:

[ ] Requirement 1: [Evidence: test_feature_x passes]
[ ] Requirement 2: [Evidence: benchmark shows 50ms response]
[ ] Requirement 3: [Evidence: manual testing confirms behavior]
[X] Requirement 4: MISSING - not yet implemented
[ ] Requirement 5: [Evidence: integration test passes]

Agent Delegation Verification

Correct Pattern:

1. Agent reports: "Task complete"
2. Check version control diff: git diff
3. Read all changes made
4. Verify changes match task requirements
5. Run verification commands (tests, build, etc.)
6. Report actual state: "Agent made changes to X, Y verified"

Incorrect Patterns:

• ❌ Trusting agent success report
• ❌ "Agent said success, moving on"
• ❌ Not checking actual changes made

Agent Verification Checklist:

1. Review git diff: What changed?
2. Run tests: Do tests still pass?
3. Check task requirements: All met?
4. Look for unexpected changes: Any surprises?
5. Verify no secrets added: .env, keys, tokens?
6. Check for commented code: Any TODOs added?
7. Verify imports/dependencies: Any new ones?

Common Agent Failures:

• Agent adds TODO instead of implementing
• Agent introduces syntax errors
• Agent misunderstands requirements
• Agent makes unrelated changes
• Agent adds secrets to version control
• Agent breaks existing functionality

Troubleshooting:

• Agent claims success but tests fail: Review diff, find issue
• Agent made unexpected changes: Revert, clarify task
• Agent added placeholder code: Complete implementation
• Agent broke unrelated code: Partial revert, fix issue

Deployment Verification

Correct Pattern:

1. Deploy to environment
2. Check deployment logs: SUCCESS
3. Verify endpoint accessible: curl https://...
4. Check application logs: No errors
5. Run smoke tests on deployed version
6. Claim: "Deployed successfully, endpoint responding"

Incorrect Patterns:

• ❌ "Deployment command succeeded" (didn't check endpoint)
• ❌ "Should be live now" (no verification)
• ❌ "Deployed to staging" (didn't verify it works)

Environment-Specific Verification:

Staging:

1. Deploy to staging
2. Run full test suite against staging
3. Check all endpoints
4. Verify database migrations
5. Test with production-like data

Production:

1. Deploy to production
2. Verify zero-downtime deployment
3. Check health endpoints
4. Monitor error rates
5. Verify key user flows
6. Keep rollback ready

Deployment Types:

• Blue-green: Verify both environments
• Canary: Monitor canary metrics
• Rolling: Verify each batch
• Feature flags: Verify flag state

Troubleshooting:

• Deployment succeeds but service down: Check logs, restart
• Configuration mismatch: Verify environment variables
• Database migration failed: Rollback, investigate
• Partial deployment: Complete or rollback fully

Performance Verification

Correct Pattern:

1. Run performance benchmark
2. Record baseline: 150ms average
3. Implement optimization
4. Run benchmark again
5. Record new measurement: 45ms average
6. Calculate improvement: 70% faster
7. Run multiple times to confirm consistency
8. Claim: "Performance improved 70% (150ms → 45ms, 10 runs)"

Incorrect Patterns:

• ❌ "Should be faster now" (no measurement)
• ❌ "Looks quicker" (subjective)
• ❌ Single measurement (could be outlier)

Benchmark Requirements:

• Sample size: Minimum 10 runs
• Statistical significance: Calculate standard deviation
• Cold vs warm: Test both scenarios
• Load levels: Test under different loads
• Environment: Same environment for before/after

Metrics to Measure:

• Response time: p50, p95, p99 latency
• Throughput: Requests per second
• Resource usage: CPU, memory, disk I/O
• Database queries: Query count, duration
• Network: Bandwidth, connection count

Edge Cases:

• Performance regression: Identify cause, revert if needed
• Inconsistent results: Check for external factors
• Different under load: Load test before claiming
• Memory leaks: Profile memory over time

Security Verification

Correct Pattern:

1. Run security scanner: bandit -r .
2. Read full report
3. Review each finding
4. Document: "3 high, 2 medium, 5 low"
5. Address critical issues
6. Re-run scanner
7. Claim: "Security scan: 0 high, 0 medium, 5 low (accepted)"

Incorrect Patterns:

• ❌ "Looks secure" (no scan)
• ❌ "No obvious vulnerabilities" (didn't scan)
• ❌ "Should be safe" (assumption)

Security Layers to Verify:

Static Analysis:

1. Code scanning: bandit, semgrep
2. Dependency scanning: safety check
3. Secret scanning: git secrets
4. License compliance: license checker

Dynamic Analysis:

1. Penetration testing: OWASP ZAP
2. Fuzzing: Input validation
3. Load testing: DoS resistance
4. Authentication testing: Auth flows

Security Checklist:

• [ ] Input validation implemented
• [ ] SQL injection prevention
• [ ] XSS prevention
• [ ] CSRF protection
• [ ] Authentication secure
• [ ] Authorization checks
• [ ] Secrets not in code
• [ ] HTTPS enforced
• [ ] Headers configured
• [ ] Dependencies updated

Troubleshooting:

• False positives: Document and suppress with justification
• Critical findings: Fix immediately, don't suppress
• Dependency vulnerabilities: Update or replace
• Configuration issues: Fix in deployment configs

Documentation Verification

Correct Pattern:

1. Write documentation
2. Have someone else read it
3. Ask them to follow steps
4. Observe if they succeed without questions
5. Fix confusing parts
6. Repeat until successful
7. Claim: "Documentation verified with fresh user"

Incorrect Patterns:

• ❌ "Documentation complete" (not tested)
• ❌ "Clear to me" (author bias)
• ❌ "Should be understandable" (no verification)

Documentation Types:

API Documentation:

1. Document all endpoints
2. Include request/response examples
3. Document error codes
4. Test with curl/Postman
5. Verify examples work

User Documentation:

1. Write step-by-step guide
2. Include screenshots
3. Test with fresh user
4. Record where they get stuck
5. Improve those sections

Developer Documentation:

1. Document setup steps
2. Fresh clone, follow steps
3. Verify can build and run
4. Document all prerequisites
5. Test on clean machine

Troubleshooting:

• User gets stuck: Add more detail, screenshots
• Prerequisites missing: Document all dependencies
• Examples don't work: Verify and fix examples
• Outdated documentation: Regular review and updates

CI/CD Pipeline Verification

Correct Pattern:

1. Push to branch
2. Watch CI pipeline run
3. Verify all stages pass: build, test, lint, security
4. Check pipeline logs for warnings
5. Verify artifacts created
6. Claim: "CI pipeline passes, all stages green"

Pipeline Stages to Verify:

• Build: Code compiles, artifacts created
• Test: All tests pass, coverage threshold met
• Lint: Code style compliance
• Security: No vulnerabilities found
• Deploy: Successful deployment to target

Edge Cases:

• Flaky pipeline: Investigate root cause, fix
• Timeout issues: Optimize slow stages
• Cache issues: Clear cache, rebuild
• Secrets missing: Verify environment variables

Database Migration Verification

Correct Pattern:

1. Backup database
2. Run migration on backup
3. Verify data integrity
4. Test rollback
5. Run on staging
6. Verify application works
7. Document any data changes
8. Claim: "Migration tested, rollback verified"

Critical Checks:

• Data loss prevention: Verify no data dropped
• Rollback tested: Must be able to undo
• Application compatibility: App works during migration
• Performance impact: Migration doesn't lock tables long

Edge Cases:

• Large tables: Use online migration tools
• Zero-downtime: Test deployment order
• Data transformation: Verify transformation logic
• Foreign key constraints: Check constraint violations

The Universal Pattern

All verification follows this structure:

1. IDENTIFY: What proves this claim?
2. RUN: Execute the full verification command
3. READ: Complete output, not just summary
4. ANALYZE: Does evidence support claim?
5. DECIDE:
   - If YES: Claim with evidence
   - If NO: Report actual state with evidence

Never skip steps. Never assume. Always verify.