Verification Before Completion

When to Activate

• At every task checkpoint during plan execution
• Before marking a Linear issue as done
• After fixing a bug (verify the fix, not just that the code compiles)
• Before shipping — final pre-review verification

Preconditions

executing-plans

Activation

_shared/observability.md

---
**Verification Before Completion** activated
Trigger: Task checkpoint reached
Produces: 4-level verification report
---

Verification Protocol

Level 1: Build Verification

Level 1/4: Build verification...

1. Build succeeds: Run the build command, check for zero errors
2. No type errors: Run typecheck (

   tsc --noEmit

   or equivalent)
3. Lint passes: Run the linter with zero errors (warnings OK)

Level 1/4: Build verification... [PASS/FAIL]

Level 2: Test Verification

Level 2/4: Test verification...

1. All tests pass: Run the full test suite, not just the new tests
2. New tests exist: The task's changes should have corresponding tests
3. Tests are meaningful: The tests actually verify the behavior, not just that the code runs
4. No skipped tests:

   describe.skip

   or

   test.todo

   for the current task's tests = not done

• Does the test fail if you revert the implementation change?
• Does the test cover the acceptance criteria from the issue?
• Does the test cover edge cases mentioned in the plan?

Level 2/4: Test verification... [PASS/FAIL]

Level 3: Acceptance Criteria

Level 3/4: Acceptance criteria...

1. Read the acceptance criteria from the Linear issue
2. Check each criterion individually:

   Acceptance Criteria:
   - [x] Users can log in with email/password — VERIFIED (test: auth.test.ts:24)
   - [x] Invalid credentials show error message — VERIFIED (test: auth.test.ts:38)
   - [ ] Rate limiting after 5 failed attempts — NOT VERIFIED (no test, no implementation found)

3. If any criterion is unmet: The task is NOT complete

Level 3/4: Acceptance criteria... [PASS/FAIL]

Level 4: Integration Verification

Level 4/4: Integration verification...

1. No regression: Pre-existing tests still pass
2. No side effects: Changes don't break unrelated features
3. API contracts: If you changed an interface, all consumers are updated
4. Data consistency: If you changed a schema, migrations exist and work

Verification Strategies

For Bug Fixes

1. Confirm the original reproduction steps no longer trigger the bug
2. Confirm the regression test fails on the old code and passes on the new
3. Check for related bugs that might have the same root cause

For New Features

1. Walk through the user flow end-to-end (mentally or via tests)
2. Check empty states, error states, edge cases
3. Verify the feature is discoverable and documented

For Refactors

1. Behavior is identical before and after (tests prove this)
2. Performance is not degraded (if relevant)
3. The refactored code is actually cleaner (not just different)

Level 4/4: Integration verification... [PASS/FAIL]

Failure Handling

1. Document what failed:

   VERIFICATION FAILED
   Level: [1/2/3/4]
   Criterion: [what was being checked]
   Expected: [what should happen]
   Actual: [what happened instead]

2. Don't retry blindly — Analyze why it failed first. Log the decision:

   Decision: [Retry approach] Reason: [root cause analysis] Alternatives: [other fix strategies considered]

3. Fix the root cause, then re-verify from Level 1
4. Max 3 retries — After 3 failures, use error recovery (see

   _shared/observability.md

   ). AskUserQuestion with options: "Retry from Level 1 with different approach / Skip this verification level / Stop and report for manual review."

Completion Report

## Verification: PASS

**Build**: Clean
**Tests**: [N] passing, 0 failing, [N] new
**Acceptance Criteria**: [N/N] met
**Integration**: No regressions

Task is genuinely complete.

## Verification: BLOCKED

**Passing**: Levels 1-2
**Failing**: Level 3 — acceptance criterion [X] unmet
**Details**: [what's missing and why]
**Recommendation**: [what needs to happen next]

Task is NOT complete.

Rules

• Never mark a task as done without running verification
• Never trust "it should work" — run the actual commands and check the actual output
• Tests passing is necessary but not sufficient — check acceptance criteria too
• If there's no test suite, flag it as a risk but don't block on it
• Verification should be fast — if it takes more than 2 minutes, the project's test/build setup needs improvement (flag this)
• Be honest about failures — a clearly reported failure is more valuable than a false success