Verification Before Completion (Spec-Aware)

Overview

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

Core principle: Evidence before claims, always.

Verify implementation is complete by running tests AND validating spec compliance.

Key Additions from Standard Verification:

Step 1: Run tests (existing behavior)
Step 2: Code hygiene review (mechanical defect detection)
Step 3: Validate spec compliance (spec-driven)
Step 4: Check for spec drift (spec-driven)
Blocks completion if tests, code hygiene, OR spec compliance fails

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. CHECK SPEC: Does implementation match spec?
   - If NO: State actual compliance with evidence
   - If YES: State compliance score WITH evidence
6. ONLY THEN: Make the claim

Skip any step = lying, not verifying

When to Use

After implementation and code review
Before claiming work is complete
Before committing/merging/deploying
As final gate in /speckit.implement (via superpowers trait overlay)

Spec Selection

If no spec is specified, discover available specs:

# List all specs in the project
fd -t f "spec.md" specs/ 2>/dev/null | head -20

If specs found: Present list and ask user to select one using AskUserQuestion.

Example:

Found 2 specs in this project:
1. specs/0001-user-auth/spec.md
2. specs/0002-api-gateway/spec.md

Which spec should I verify implementation against?

If no specs found: Inform user:

No specs found in specs/ directory.

Verification requires a spec to validate against.
Use `spex:brainstorm` or `/speckit.specify` to create one first.

The Process

1. Run Tests

Execute all tests:

# Run full test suite
npm test  # or pytest, go test, etc.

Check results:

All tests passing?
No flaky tests?
Coverage adequate?

If tests fail:

STOP: Fix tests before proceeding
Do not skip this step
Do not claim completion

2. Code Hygiene Review

Before checking spec compliance, review every changed file for mechanical defects. These are craft-level issues that no spec describes but that cause real bugs.

For each function you wrote or modified, check:

Dead Code and Logic

Every conditional branch produces a different outcome (no branches that do the same thing)
Every parameter is actually used to change behavior (no unused parameters)
Every exported function has at least one caller outside tests (no orphaned API surface)
No variables assigned but never read

Copy and Mutation Safety

When copying a data structure, verify whether nested references are shared
If the copy is later mutated, confirm the original is not affected
If a function receives a pointer/reference, verify whether it is expected to mutate or read-only

Cleanup and Consistency

When removing/disabling something, verify all references to it are also cleaned up (no orphaned entries, dangling references, stale indices)
When adding to a collection, verify duplicates are handled (deduplicate or reject)
When deriving a value from an identifier, verify the derivation uses the correct source (e.g., a display name vs an internal ID vs a type name are different things)

Unnecessary Operations

No sorting/ordering when the result doesn't depend on order (counting, summing, existence checks)
No intermediate data structures that serve no purpose (building a list just to iterate it once)

If any issue found: Fix before proceeding. These are not style nits; they are latent bugs.

3. Validate Spec Compliance

Load spec:

cat specs/features/[feature-name].md

Check each requirement:

Functional Requirement 1: [From spec]
  IMPLEMENTED / MISSING
  TESTED / UNTESTED
  MATCHES SPEC / DEVIATION

Functional Requirement 2: [From spec]
  ...

Verify:

All requirements implemented
All requirements tested
All behavior matches spec
No missing features
No extra features (or documented)

Calculate compliance:

Spec Compliance: X/X requirements = XX%

If compliance < 100%:

STOP: Use spex:evolve to reconcile
Document all deviations
Do not proceed until resolved

4. Check for Spec Drift

Compare:

What spec says NOW
What code does NOW
Any divergence?

Common drift sources:

Spec updated but code not
Code changed but spec not
Undocumented additions
Forgotten requirements

If drift detected:

Document each instance
Use spex:evolve to reconcile
Do not proceed with drift

5. Verify Success Criteria

From spec, check each criterion:

Success Criteria (from spec):
- [ ] Criterion 1: [Description]
      Status: Met / Not met
      Evidence: [How verified]

- [ ] Criterion 2: [Description]
      ...

All criteria must be met.

If any criterion not met:

STOP: Criterion not met
Implement missing piece
Re-verify

6. Generate Verification Report

Report structure:

# Verification Report: [Feature Name]

**Date:** YYYY-MM-DD
**Spec:** specs/features/[feature].md

## Test Results

**Status:** PASS / FAIL

[Test output]


**Summary:**
- Total: X tests
- Passed: X
- Failed: X
- Coverage: XX%

## Spec Compliance

**Status:** COMPLIANT / NON-COMPLIANT

**Compliance Score:** XX%

### Requirements Status
- Functional: X/X (XX%)
- Error Cases: X/X (XX%)
- Edge Cases: X/X (XX%)
- Non-Functional: X/X (XX%)

### Deviations
[List any deviations found]

## Spec Drift Check

**Status:** NO DRIFT / DRIFT DETECTED

[Details if drift found]

## Success Criteria

**Status:** ALL MET / INCOMPLETE

- [x] Criterion 1
- [x] Criterion 2
...

## Overall Status

**VERIFIED - Ready for completion**

OR

**NOT VERIFIED - Issues must be resolved**

**Blocking Issues:**
- [Issue 1]
- [Issue 2]

**Next Steps:**
[What needs to be done]

7. Make Go/No-Go Decision

All conditions must be true:

All tests passing
Code hygiene review clean (no dead code, no mutation bugs, no orphans)
Spec compliance 100%
No spec drift
All success criteria met

If ALL true:

VERIFIED: Proceed to completion
Safe to commit/merge/deploy
Write verification marker so the commit gate hook allows the commit:
```
touch "${TMPDIR:-/tmp}/.claude-spex-verified-${SESSION_ID}"
```
(The SESSION_ID is available from the hook context. If not, use a stable session identifier.)

If ANY false:

NOT VERIFIED: Block completion
Fix issues before proceeding
Re-run verification after fixes

Common Failures

Claim	Requires	Not Sufficient
Tests pass	Test command output: 0 failures	Previous run, "should pass"
Spec compliant	Line-by-line requirement check	"Looks complete"
Linter clean	Linter output: 0 errors	Partial check
Build succeeds	Build command: exit 0	Linter passing
Bug fixed	Test original symptom: passes	Code changed
Requirements met	Line-by-line checklist	Tests passing

Red Flags - STOP

Using "should", "probably", "seems to"
Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
About to commit/push/PR without verification
Relying on partial verification
Thinking "just this once"
Tired and wanting work over
ANY wording implying success without having run verification
Modified CLAUDE.md without explicit user request (CLAUDE.md is user-maintained, never auto-update)

Rationalization Prevention

Excuse	Reality
"Should work now"	RUN the verification
"I'm confident"	Confidence is not evidence
"Just this once"	No exceptions
"Tests pass"	Did you check spec compliance?
"Spec compliant"	Did you run the tests?
"I'm tired"	Exhaustion is not an excuse
"Partial check is enough"	Partial proves nothing

Verification Checklist

Use TodoWrite to track:

Example: Verification PASS

You: Running verification before completion...

Step 1: Running tests...

$ npm test

All tests passing (24/24)
Coverage: 95%

Step 2: Validating spec compliance...

Reading spec: specs/features/user-profile-api.md

Checking requirements:
COMPLIANT: Functional Requirement 1: PUT endpoint - Implemented & tested
COMPLIANT: Functional Requirement 2: Validation - Implemented & tested
COMPLIANT: Functional Requirement 3: Auth - Implemented & tested
COMPLIANT: Functional Requirement 4: Authorization - Implemented & tested
COMPLIANT: Functional Requirement 5: Response format - Implemented & tested
COMPLIANT: Functional Requirement 6: Partial updates - Implemented & tested

COMPLIANT: Error Case 1: Missing JWT - Handled & tested
COMPLIANT: Error Case 2: User not found - Handled & tested
COMPLIANT: Error Case 3: Validation failure - Handled & tested
COMPLIANT: Error Case 4: Authorization failure - Handled & tested

COMPLIANT: Edge Case 1: Empty update - Handled & tested
COMPLIANT: Edge Case 2: Invalid avatar URL - Handled & tested
COMPLIANT: Edge Case 3: Special characters in name - Handled & tested

Spec Compliance: 13/13 = 100%

Step 3: Checking for spec drift...

Comparing spec to implementation...
No drift detected

Step 4: Verifying success criteria...

From spec:
MET: Authenticated users can update their profile
MET: Validation errors return 422 with clear messages
MET: Users cannot update other users' profiles
MET: All edge cases handled gracefully

All criteria met

=== VERIFICATION REPORT ===

Tests: PASS (24/24)
Spec Compliance: 100%
Spec Drift: None
Success Criteria: All met

**OVERALL: VERIFIED**

Implementation is complete and verified. Ready for commit/merge.

Example: Verification FAIL

You: Running verification before completion...

Step 1: Running tests...

$ npm test

Tests FAILED (22/24 passing, 2 failing)

Failures:
1. "Should handle database connection errors"
   Error: Connection retry not implemented

2. "Should return 503 when database unavailable"
   Error: Returns 500 instead of 503

**BLOCKING: Tests must pass before proceeding**

Step 2: Validating spec compliance...

Reading spec: specs/features/user-profile-api.md

Checking requirements:
[checks requirements...]

DEVIATION: Non-Functional Requirement 1: Database retry logic
   Status: Not implemented
   Spec says: "3 retry attempts with exponential backoff"
   Code does: Single attempt, no retry

Spec Compliance: 12/13 = 92%

Step 3: Checking success criteria...

From spec:
MET: Authenticated users can update their profile
MET: Validation errors return 422
NOT MET: Handles database failures gracefully (missing retry logic)
MET: Users cannot update other users' profiles

=== VERIFICATION REPORT ===

Tests: FAIL (2 failures)
Spec Compliance: 92% (missing retry logic)
Success Criteria: 3/4 met

**OVERALL: NOT VERIFIED**

**Blocking Issues:**
1. Database retry logic not implemented (from spec)
2. Tests failing for error handling
3. Returns wrong HTTP status (500 vs 503)

**Next Steps:**
1. Implement database retry logic per spec
2. Fix HTTP status code
3. Re-run verification

**DO NOT PROCEED until all issues resolved.**

Common Failure Scenarios

Scenario: Tests Pass but Spec Compliance Fails

Tests: 24/24 passing
Spec Compliance: 85%
BLOCKED

Issue: Tests don't cover all spec requirements

Action: Add tests for uncovered requirements, re-verify

Scenario: Spec Compliant but Tests Fail

Tests: 20/24 passing
Spec Compliance: 100%
BLOCKED

Issue: Implementation exists but has bugs

Action: Fix bugs, ensure tests pass, re-verify

Scenario: Both Pass but Drift Detected

Tests: 24/24 passing
Spec Compliance: 100%
Spec Drift: Spec updated after implementation
BLOCKED

Issue: Spec changed, code doesn't reflect changes

Action: Update code or revert spec, re-verify

Quality Gates

This skill enforces quality gates:

All tests must pass (from superpowers)
Code hygiene review clean (mechanical defects)
100% spec compliance required (spex)
No spec drift allowed (spex)
All success criteria must be met (spex)

No exceptions. No shortcuts.

These gates exist to prevent:

Incomplete implementations
Untested code
Spec/code divergence
False claims of completion

Remember

Verification is not optional.

Don't skip verification "just this once"
Don't claim completion without verification
Don't ignore failing gates

Verification failures are information.

Tests failing? Code has bugs
Spec compliance failing? Missing features
Drift detected? Synchronization problem
Criteria not met? Work incomplete

No shortcuts for verification.

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

Fix issues, don't rationalize past them.

Evidence before assertions. Always.

This is non-negotiable.

verification-before-completion