Verification

Verification

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.

Never assert that something works, passes, or is complete without running the verification commands and reading the actual output. Memory of a previous run is not evidence. Assumptions are not evidence. Only fresh output is evidence.

---

What This Means

Three requirements must be met before any completion claim:

1. Run the actual verification command. Execute it, do not recall or assume.
2. Read the actual output. Parse the output line by line.
3. Confirm the output supports ALL success claims. Every claim must have corresponding evidence in the output.

If any of these three steps is skipped, the completion claim is invalid.

---

Forbidden Phrases

The following phrases indicate an unverified claim. Never use them:

Forbidden Phrase	Why It Is Forbidden
"should work"	Speculation, not evidence
"probably fixed"	Probability is not proof
"seems to pass"	Ambiguity signals incomplete verification
"I think it's done"	Thinking is not running
"looks correct"	Visual inspection is not test execution
"I believe this fixes"	Belief is not evidence
"this ought to work"	Expectation is not output

What to Say Instead

Use language that references actual evidence:

• "All 47 tests pass. Output: [paste relevant output]."
• "Lint reports 0 errors, 0 warnings. Output: [paste relevant output]."
• "Typecheck completed with no errors. Output: [paste relevant output]."
• "Acceptance criteria 1-4 verified by tests X, Y, Z, W."

---

Verification Checklist

Execute each applicable step and paste the actual output.

Step 1: Run Tests

Execute the project's test command. Paste the output.

npm test
# or
pytest
# or the project's configured test command

Confirm:

• Total test count matches expectations.
• All tests pass. Zero failures, zero errors.
• No tests are skipped unexpectedly.

Step 2: Run Linter

Execute the project's lint command. Paste the output.

npm run lint
# or
ruff check .
# or the project's configured lint command

Confirm:

• Zero errors.
• Zero warnings (or only pre-existing, documented warnings).

Step 3: Run Type Checker

Execute the project's typecheck command. Paste the output.

npx tsc --noEmit
# or
mypy .
# or the project's configured typecheck command

Confirm:

• Zero type errors.
• No new type warnings introduced.

Step 4: Run E2E Tests (If Applicable)

Execute end-to-end tests when changes affect user-facing behavior.

npx playwright test
# or the project's configured e2e command

Confirm:

• All e2e scenarios pass.
• No flaky failures.

Step 5: Check Acceptance Criteria

Review every acceptance criterion from the issue:

• Criterion 1: Verified by test(s) [name/file].
• Criterion 2: Verified by test(s) [name/file].
• Criterion N: Verified by test(s) [name/file].

Every acceptance criterion must map to at least one passing test.

---

When to Verify

Before Committing

Run the full verification checklist before every commit. A commit represents a claim that the code works at this point. Back that claim with evidence.

Before Creating a Pull Request

Run all checks one final time after the last commit. Ensure the branch is clean and all checks pass from a fresh state.

Before Claiming "Done"

Run the complete checklist before saying an issue is complete, a task is finished, or a fix is in place. This is the final gate.

Before Marking an Issue as Complete

Ensure the PR is merged, the issue is auto-closed, and a final verification on main confirms nothing broke during merge.

---

Partial Success

Reporting Mixed Results

If some checks pass and others fail, report BOTH outcomes clearly.

Tests: 45/47 passing, 2 failing
  - FAIL: test/auth/login.test.ts - "redirects after login"
  - FAIL: test/auth/login.test.ts - "shows error on invalid credentials"
Lint: 0 errors, 0 warnings
Typecheck: 0 errors

Rules for Partial Success

• Never claim success if any part of the verification fails.
• Never hide failing results behind passing results.
• State the exact failures with file names and test names.
• Determine whether the failures are related to the current change or pre-existing.
• If pre-existing, document them and confirm with the team before proceeding.

---

Verification Evidence Format

When reporting verification results, use this format:

## Verification Results

### Tests
Command: `npm test`
Result: 47/47 passing (0 failures)
Output:
  PASS src/auth/login.test.ts (4 tests)
  PASS src/api/users.test.ts (12 tests)
  ...
  Test Suites: 8 passed, 8 total
  Tests: 47 passed, 47 total

### Lint
Command: `npm run lint`
Result: 0 errors, 0 warnings

### Typecheck
Command: `npx tsc --noEmit`
Result: 0 errors

### Acceptance Criteria
- [x] User can log in with valid credentials (login.test.ts:14)
- [x] Invalid credentials show error message (login.test.ts:28)
- [x] Session persists across page reload (session.test.ts:9)

---

Quick Reference

Rule	Requirement
Before any claim	Run verification commands fresh
Output handling	Paste actual output, never paraphrase
Partial failure	Report both passing and failing results
Forbidden language	No "should work", "probably fixed", "looks correct"
Acceptance criteria	Every criterion mapped to a passing test

---

Dependencies

None -- this is a capstone workflow skill that enforces evidence-based completion claims.

Used By

Component	Reason
Command: develop	Step 6 runs final verification before committing
Command: review-code	Step 6 runs all verification commands
Command: submit-pr	Step 2 pre-flight checks verify clean state