Verification Before Completion

intent

this skill enforces a hard gate: no completion claim gets made without fresh verification evidence run immediately before the claim. "should pass", "probably works", and "looks correct" don't count. only command output with exit code 0 or explicit pass/fail metrics counts as evidence. use this before claiming tests pass, bugs fixed, builds succeed, features complete, or readiness to merge. also use this at task start when a request has vague scope (like "refactor everywhere") to confirm what actually gets touched before you write a line.

inputs

• git working tree state: git status --porcelain output to detect uncommitted changes
• vcs history access: ability to run git log, git diff to review what changed and check review staleness
• build/test/lint toolchain: whatever the repo uses (pytest, npm test, cargo test, etc.) must be runnable in the current session
• access to run verification commands: permission to execute the full chain (build > typecheck > lint > test > security scan > diff review) without blockers
• cursor/code-execution context: ability to run shell commands in the current session and capture full output including exit codes
• optional external tools for scope detection: ripgrep (rg) or similar for mapping blast radius on ambiguous requests
• optional user-input mechanism: AskUserQuestion (Claude Code) or request_user_input (Codex) for scope confirmation gates

procedure

gate function (five-step verification chain)

1. identify the verification command

   • input: completion claim you want to make (e.g. "tests pass", "bug fixed", "feature complete")
   • action: determine what command output proves this claim; for compound claims (ship-level: commit/push/PR ready), run the full chain and stop on first failure; for single claims, use the proof command from the Common Claims table (see decision points below)
   • output: specific command string (e.g. pytest tests/, npm test, npm run build && npm run lint && npm test)

2. run verification now, in this session

   • input: the command from step 1
   • action: execute it immediately; output from any earlier turn is stale and does not count; do not skip, defer, or reference prior results
   • output: full command output including exit code (0 for success, nonzero for failure)

3. read the complete output

   • input: full command output from step 2
   • action: read all of it; check exit code explicitly; don't scan for the word "passed" or cherry-pick lines; note failure counts, warnings, error messages
   • output: structured summary of what the output shows (e.g. "42 passed, 0 failed, exit code 0" or "1 test failed, exit code 1")

4. verify the output matches the claim

   • input: the claim + the output summary from step 3
   • action: does the output actually prove the claim? "42 passed, 0 failed" confirms "tests pass"; "41 passed, 1 failed" does not; if verification fails, do not proceed to step 5
   • output: explicit yes/no decision with reasoning

5. make the claim only if step 4 is yes

   • input: passed verification from step 4
   • action: state the claim with the evidence visible; cite the command and result; include in completion report
   • output: claim statement + verification evidence in completion report

pre-verification checks (before running gate)

1. check working tree state

   • input: current directory in repo
   • action: run git status --porcelain; if there are uncommitted changes unrelated to the current task, handle them first (commit, stash, or acknowledge); if dirty tree + shared-module change exists, verification on dirty tree does not count as evidence
   • output: clean working tree or documented justification for changes

2. for delegated work: do not trust implementer subagent report

   • input: completion claim from a subagent
   • action: never relay the subagent's own verification claim; verify both spec compliance and code quality yourself; confirm via vcs diff that changes actually exist, then run the verification command directly
   • output: independent verification evidence

scope confirmation gate (pre-edit, fires at task start)

1. detect ambiguous scope

   • input: task/request text
   • action: scan for vague phrasing ("migrate my project", "refactor the codebase", "update everywhere", "fix this across the app", "my code/repo/project", "should update"); if present and no explicit file list was given, fire this gate
   • output: true (gate blocks editing) or false (proceed directly to edits)

2. run blast-radius breakdown

   • input: the pattern or feature being changed
   • action: execute one of these commands to surface real scope:

     rg -l 'pattern' | cut -d/ -f1 | sort | uniq -c | sort -rn   # files per top-level dir
     rg -l 'pattern' | xargs dirname | sort -u                   # affected directories
     

   • output: breakdown showing number of files per subsystem/directory

3. present scope options to user

   • input: breakdown from step 2
   • action: show result ("This touches N files across M subsystems"); offer options: (a) everything, (b) just , (c) pick specific files; use AskUserQuestion if available, else request_user_input, else numbered options in chat
   • output: user commits to one option before you start editing

verification strategy selection (by change type)

1. identify change type

   • input: description of what was changed
   • action: match to one row in the Verification Strategies table (below)
   • output: required verification strategy for this change type

2. execute verification strategy

   • input: the strategy row
   • action: run the exact commands/checks listed for that change type; include adversarial probe if not exempt
   • output: verification evidence (command output, console logs, diff, etc.)

adversarial probe inclusion (for production logic changes)

1. check if change touches production logic

   • input: list of files changed
   • action: does it touch user-facing behavior, state mutations, security boundaries, or data processing? if no, exempt from adversarial probe (docs, typo fixes, rename refactors only)
   • output: true (require probe) or false (exempt)

2. select probe type

   • input: the change
   • action: pick the most relevant probe from: boundary value (0, -1, empty string, null, MAX_INT), concurrency (two parallel mutations with same ID), idempotency (run mutation twice, second must no-op or error cleanly), orphan op (delete/update/get nonexistent ID)
   • output: probe test case

3. run probe and capture result

   • input: probe test case
   • action: execute it; record output/error/state change
   • output: probe evidence

review staleness check (before shipping)

1. check for commits since last review

   • input: commit hash of last review
   • action: run git log --oneline <review-commit>..HEAD; if commits exist, proceed to step 2; if empty, review is current
   • output: list of commits since review or "no new commits"

2. verify new changes don't invalidate review

   • input: list of new commits and the review's conclusions
   • action: confirm previously flagged issues are still fixed and no new code contradicts the review's approval
   • output: "review still valid" or list of invalidations

completion report generation (after verification passes)

1. structure the report

   • input: all verification evidence from the gate and strategy steps
   • action: populate the template below with actual data; mandatory sections: Status, Changes made, Things I didn't touch, Potential concerns, Verification evidence
   • output: structured completion report

2. include negative confirmation at signoff

   • input: the verification steps run
   • action: state what defect classes were checked and not found (e.g. "tests pass, no type errors, no lint warnings, no security flags in changed files"), not just what passed
   • output: defect-class summary in Verification evidence section

decision points

when to run this skill

• before any completion claim: "tests pass", "build succeeds", "bug fixed", "feature complete", "ready to merge", "ready to commit", "ready to push", or any positive statement about the work state
• before claiming "no issues": "zero issues found", "all clear", "nothing to fix", or any conclusion of a first-implementation pass (zero defects on first try is a red flag; re-verify with broader scope)
• before task completion: after each plan step and before starting the next file
• before reporting to user: any summary of what you built or fixed
• before delegated work signup: a subagent reports success (verify independently)
• at task start with ambiguous scope: if the request says "refactor everywhere" or "update my codebase" without explicit files, run scope confirmation gate first

when scope confirmation gate blocks editing

if ambiguous scope is present AND no explicit file list was provided: run breakdown, show results, ask user to pick, wait for answer. Do not edit until user commits to a scope option.

if scope is explicit (user said "update src/auth.ts and src/session.ts"): skip the gate, proceed directly to editing.

if scope is implicit but single-directory (user said "fix the API handler" and context makes clear which handler): skip the gate, proceed directly.

common claims and their proof commands

when verification fails

• do not claim completion: report actual failure output to user
• do not retry hoping for a different result: return to implementation
• fix the root cause: address the failure, then re-run from step 1 of the gate function
• if failure is pre-existing (flaky test, environment issue unrelated to your changes): state this explicitly with evidence (show the failure also occurs on base branch via git log --oneline <base>..HEAD); do not ignore it or ship without flagging it

when pre-commit hook fails

• if the current session's changes caused the failure: fixing the root cause is mandatory; git commit --no-verify is forbidden
• if failure is pre-existing (reproduces on base branch): permitted only if (1) you show the failure on base branch and (2) the user saw the failure first; a --no-verify the user never saw is a defeated check

when to defer rationalization

if you catch yourself using any of these phrases, the gate is not satisfied: "should work", "trivial change", "just a refactor", "new tests pass" (not "all tests pass"), "CI will catch it", "looks good", "seems correct", "that should do it", "pretty sure", "can't imagine it breaking".

any positive statement about completion (or paraphrases/synonyms of completion claims) triggers the gate. rephrasing a claim to avoid the trigger words does not exempt it.

output contract

completion report (mandatory, after gate passes):

## completion report

**status**: DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT

**changes made**
- path/to/file.ts: [one-line description of what changed and why]
- path/to/other.ts: [one-line description]

**things i didn't touch (intentionally)**
- [thing noticed but out of scope, with one-line reason]
- [adjacent issue deferred, with one-line reason]
- (or "nothing noticed")

**potential concerns**
- [any risk, uncertainty, or open question the reviewer should know about]
- (or "none")

**verification evidence**
- [command]: [exit code / result summary]
- [adversarial probe type]: [result]
- [defect-class summary]: "tests pass, no type errors, no lint warnings, no security flags in changed files"

if BLOCKED or NEEDS_CONTEXT: mandatory name-the-blocker or missing-information section.

if DONE_WITH_CONCERNS: mandatory Potential concerns section with at least one item.

verification strategy table (reference, used in procedure step 2.2):

outcome signal

you know the skill worked when:

• you have completed all five steps of the gate function and step 4 returned yes
• you have a completion report with actual command output or evidence, not reasoning
• you did not use any rationalization phrases ("should work", "looks good", etc.)
• if the change touched production logic, you included at least one adversarial probe result
• if scope was ambiguous at start, you confirmed it with the user and cited their choice
• if a pre-commit hook failed, you either fixed the root cause or documented pre-existing failure on base branch
• any defect classes you checked (tests, types, lint, security) are listed as "checked and not found" in the verification evidence section