Verification Before Completion

← Back to Enforcement Layer vf-verification-before-completion.md

Verification Before Completion

No completion claims without fresh verification evidence.

The Rule

NO CLAIM WITHOUT EVIDENCE. NO EVIDENCE WITHOUT EXECUTION.

Before stating that anything works, is complete, is fixed, or is ready — you must have run a verification command in this session and read its output. Memory, intuition, and code reading are not verification.

Gate Function

Every time you are about to claim a status (works, done, fixed, ready, deployed, passing), execute this gate:

BEFORE claiming status:
  1. IDENTIFY — What specific command proves this claim?
     (build command, test run, API call, curl, git status, etc.)
  2. RUN — Execute the command. Full command, no shortcuts.
  3. READ — Read the complete output. Not a summary. The output.
  4. VERIFY — Does the output confirm the claim? Specifically?
  5. CLAIM — Now you may state the status, citing the evidence.

If you skip any step, you are making an unverified claim.
Unverified claims are lies with good intentions. Don't make them.

Red Flag Phrases

If you catch yourself about to write any of these, STOP and run the gate function:

Phrase What It Really Means
"Should work now" I haven't verified it works
"That looks correct" I read code instead of running it
"This should fix it" I haven't confirmed the fix
"The build should pass" I haven't run the build
"I believe this is complete" I haven't checked completion criteria
"Everything is in place" I haven't verified each piece
"This matches the spec" I haven't run the validation gates
"No issues expected" I haven't tested for issues

Applies To

This verification rule applies to ALL claims, including:

Build Claims

  • "Portal builds successfully" → Run cd apps/portal && npx pnpm build, show output
  • "Website builds cleanly" → Run cd apps/website && npx pnpm build, show output
  • "No TypeScript errors" → Run the build, show zero-error output

HubSpot Claims

  • "Record created" → Show the API response with the record ID
  • "Property exists" → Show the sample record or property check result
  • "Association created" → Show the association response

Git Claims

  • "Changes committed" → Run git status and git log -1, show output
  • "Branch is clean" → Run git status, show "nothing to commit"
  • "Pushed to remote" → Show the push output with remote confirmation

File Claims

  • "File updated" → Read the file, show the relevant section
  • "Config is correct" → Read and display the actual config

Fix Claims

  • "Bug is fixed" → Run the scenario that reproduced the bug, show it passing
  • "Error resolved" → Run the command that errored, show clean output

Commit Messages Are Intentions, Not Production State

A commit message describes what the author INTENDED to fix at the time of the commit. It does not describe current production state.

The trap: When debugging a routing or behavior issue, reading commit history often produces a message like "fix /VFT/* routes" or "remove broken directory route." This creates the impression that the route's status is known. It is not — the commit describes an intent at a point in time. The current state of production requires direct verification.

The rule: Never make a routing, behavior, or integration decision based on commit message narrative alone. Verify current production state via curl, direct inspection of the live URL, or fresh file read — then decide.

Example that cost 90 minutes (2026-05-24): Commit 58d2597 said it fixed /VFT/* routes. Re-reading the commit during debugging first produced distrust (the described fix seemed wrong), then re-trust (when Chris reversed), then the realization that the commit was both correct AND irrelevant — the literal /VFT/* IS broken AND the working URL was always /vft/* (different route mechanism). The commit narrative created a false frame. A single curl of the actual URL would have resolved the investigation in under 60 seconds.

How to apply:

  1. When a route or feature "should work" based on a commit message, run curl -si {URL} and read the response before any other debugging step.
  2. When a commit says it "removed" or "fixed" something, verify the current file state with a direct file read.
  3. Treat commit messages as archaeological artifacts — they tell you what someone thought was true at a point in time, not what is true now.

The Discipline

This is not bureaucracy. This is the difference between "I think it works" and "I verified it works." The cost of running a verification command is seconds. The cost of an unverified claim is broken production, wasted debugging time, and eroded trust.

Verify, then claim. Every time.