Verification Before Completion

intent

never claim completion, handoff, or readiness without fresh verification evidence. run the proof command immediately before the claim, in the current session, and read the full output. "should pass", "looks correct", and "pretty sure it works" do not count. only command output with exit code 0 or explicit pass confirmation counts as evidence. use this skill whenever you are about to say "tests pass", "bug fixed", "done", "ready to merge", handing off to another agent, or before editing a request with ambiguous scope.

inputs

• working tree state: current git diff and uncommitted changes (input: git status --porcelain)
• base branch or last known good commit: for retroactive verification fallback (input: git log hash or branch name)
• scope of the claim: what exactly are you verifying (e.g. "single test file", "entire build", "endpoint behavior")
• change type: the category of work (frontend, backend, infra, refactor, etc.) to select the right verification strategy
• test runner or validation tool: whatever command proves the claim (pytest, npm test, terraform plan, etc.)
• for delegated work: the subagent's implementation diff and their claimed result (input: git diff output + their report)
• for sweep tasks: a session-scratch ledger tracking each item and its disposition (input: external scratch file, never version-controlled)

procedure

1. pre-verification tree check

inputs: current working tree state steps: a. run git status --porcelain. check for uncommitted changes unrelated to the current task. b. if dirty tree found: commit, stash, or explicitly acknowledge the unrelated changes before proceeding. c. if the change touches a shared module or has broad blast radius (dependency bump, framework upgrade, codegen, migration), capture the baseline first: run the repo's full validation suite against the existing state before any write. record the exact command set and its output. d. for delegated work: never trust the subagent's report. confirm via git diff that changes were actually made, then run the verification command directly yourself.

outputs: clean or documented working tree; baseline command set and output (if broad-radius change)

2. scope confirmation gate (pre-edit only)

inputs: the original request phrasing, current file inventory applies when: the request uses spatial scope like "migrate my project", "refactor the codebase", "fix this across the app", "update everywhere" AND the user has not enumerated specific files. steps: a. run a breakdown command to surface the blast radius:

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

b. present the result: "This touches N files across M subsystems". c. ask the user (via AskUserQuestion in Claude Code or request_user_input in Codex) for scope confirmation: (a) everything, (b) just , (c) pick specific files. d. do not start editing until the user commits to one option.

skip this gate if: the request already lists specific file paths.

outputs: confirmed scope from user, or explicit scope bounds

3. enumerate coverage for sweep tasks

inputs: the full set of items to cover (all files matching a pattern, all findings, all renames, etc.) applies when: the task scope is "every item in a set" (repo-wide rename, "migrate everywhere", audit all files, resolve all findings). steps: a. create a ledger in session-scratch (git-ignored local directory, never tracked) with one row per item: pending, done, excluded (reason), or blocked (evidence). b. after any path move, rename, or new item creation during the sweep, re-enumerate the set so new items enter coverage. c. keep removed items in the ledger until explicitly accounted for: if an item silently vanishes, it looks the same as "finished" unless you mark it removed. d. completion requires zero pending and zero blocked entries. "i covered a lot of them" is not a disposition.

outputs: ledger file with all items enumerated and zero pending/blocked entries

4. run the gate function

inputs: the claim you are about to make, the proof command from the Common Claims table below (or the command that proves it) steps:

step	action	example
1. identify	what command proves this claim. for ship-level claims (commit/push/PR-ready), run the full chain: build -> typecheck -> lint -> test -> security scan -> diff review, stopping on first failure. for a single claim, use the proof command from the Common Claims table.	pytest tests/, npm test, curl -s localhost:3000/health
2. run	run it now, in this same message. output from an earlier turn is stale.	"i ran it earlier" fails this step
3. read	read the complete output. check the exit code. do not scan for "passed" - read failure counts, warnings, errors.	scan all output, not just the summary line
4. verify	does the output actually confirm the claim.	"42 passed, 0 failed" confirms tests pass. "41 passed, 1 failed" does not.
5. claim	only now make the statement, with evidence visible.	"all 42 tests pass" with output visible above

outputs: verification command output; explicit pass/fail determination

5. choose verification strategy by change type

inputs: the type of change made match the strategy to the change type:

change type	required verification
frontend (component, page, form)	start the dev server, exercise the feature in a browser, check the console. test happy path and one failure path. screenshot or describe the result.
backend handler / endpoint	curl the endpoint, check response shape and status code. hit at least one error path (invalid input, missing auth).
cli tool	run the binary with real inputs. check stdout, stderr, exit code. run from /tmp to catch "only works from source" bugs.
infra / iac (terraform, dockerfile, k8s)	terraform plan / docker build / kubectl apply --dry-run=server. review the diff before applying.
database migration	run migration up, down, then up again against production-shape data.
refactoring (no behavior change)	full test suite passes unchanged. public api surface diff shows no breakage. run grep on exported identifiers before and after.
library / package update	run the consumer's test suite against the new version. check for deprecation warnings.
schema change	old consumers parse the new shape (forward compat). new consumers handle old data still present (backward compat). test both directions.
documentation / prose	read the rendered output. confirm links, formatting, and content match intent.
config with no validator	validate syntax where possible (jq ., yamllint). otherwise read the file and confirm it matches the intended change.
non-runnable changes	git diff, confirm the diff matches intent. state explicitly: "no automated verification available , verified by reading the diff."

if no row applies: fall back to the non-runnable row. reading code is not a strategy.

outputs: verification command output and result for the change type

6. include adversarial probes

inputs: the change (production logic or data-sensitive code) applies to: any change touching production logic exempt: docs, trivial typos, pure rename refactors pick at least one probe:

• boundary value: 0, -1, empty string, empty array, null, undefined, MAX_INT, 1-char unicode combining mark
• concurrency: two parallel requests with the same identifier (state changes, races, double-spend)
• idempotency: run the same mutation twice; second should no-op or error cleanly, not corrupt state
• orphan op: delete/update/get a nonexistent id. does it 404/return-null as expected, or throw an internal error

outputs: probe command, execution, and result

7. check review staleness

inputs: prior review(s) (agent or human), current HEAD applies before shipping: a. run git log --oneline <review-commit>..HEAD to list commits after the last review. b. if new commits exist, verify the new changes do not invalidate prior conclusions: previously flagged issues still fixed, no new code contradicts the review. c. if stale, request a new review or confirm the changes are safe.

outputs: staleness check result; decision to re-review or proceed

8. handle verification failures

inputs: verification command output showing failure steps: a. do not claim completion. report the actual failure output to the user. b. do not retry hoping for a different result. c. return to implementation. fix the issue, then re-run from step 1 of the gate function. d. if failure is unrelated to current changes (pre-existing flaky test, environment issue): state it explicitly with evidence (show the failure also occurs on the base branch, or link to a known issue tracker).

outputs: explicit failure report with root cause or evidence of pre-existing issue

9. pre-commit hook failures

inputs: pre-commit hook rejection decision: is this failure caused by the current session's changes?

• yes: fix the root cause. git commit --no-verify is forbidden. the hook is a verification checkpoint, not an obstacle.
• no, failure is pre-existing: show the failure also reproduces on the base branch. confirm the user saw it first. only then is --no-verify permitted.

outputs: either fixed root cause or documented pre-existing failure with evidence

decision points

• if ambiguous spatial scope is in the request: confirm concrete scope with a breakdown command before any edit (gate: scope confirmation gate).
• if the task is "every item in a set" (repo-wide rename, migrate everywhere, audit all): maintain a ledger with zero pending/blocked entries. "covered a lot" does not satisfy this branch.
• if working tree is dirty with unrelated changes: commit, stash, or acknowledge before running verification. for broad-radius changes (dependency bump, codegen), capture the baseline first on clean state.
• if delegated work arrives with a subagent report: never trust their claim. run the verification command yourself and check the diff.
• if change type has no row in the verification strategy table: fall back to "non-runnable changes" - read the diff, state what was checked, explain why no automated verification applies.
• if production logic or data-sensitive code changed: include at least one adversarial probe (boundary, concurrency, idempotency, orphan op). docs and trivial typos are exempt.
• if prior reviews exist and new commits landed after the last review: re-verify that the new commits do not invalidate prior conclusions.
• if verification output shows failure: do not retry; do not claim completion; return to implementation and fix the root cause.
• if a pre-commit hook fails: check if current session's changes caused it. if yes, fix the root cause. if no and user saw it first, and it reproduces on base branch, then document and proceed.

output contract

a complete verification produces a structured report in this format:

## 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]

**Next**
- [the one command to paste, URL to open, or click-path that exercises this in one step -- or the decision now owed]

**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]
- [command]: [exit code / result summary]

status codes: DONE means verification passed, zero concerns. DONE_WITH_CONCERNS means verification passed but risks exist (mandatory to explain in concerns section). BLOCKED means work cannot proceed (name the blocker). NEEDS_CONTEXT means you need info from the user (name the missing info).

changes made: list files actually touched and one line per file on what changed and why. prove scope was bounded.

next: one line only. the thing the reader does now (usually not the verification command itself; usually the command to exercise the feature, the URL to open, the decision needed, or the next file to edit). when result is not exercisable (docs, config, refactor), name what was read or checked.

things i didn't touch: mandatory section. if nothing was noticed, write "nothing noticed". goal is to prove scope was considered.

potential concerns: mandatory if DONE_WITH_CONCERNS. explain any risk, uncertainty, or open question. if DONE with no concerns, write "none".

verification evidence: list each command run, its exit code, and a one-line result summary. include enough detail that the reader can reproduce the verification.

outcome signal

the skill has worked when:

1. a claim is made only after verification command output is visible and read in the current session (not from an earlier turn or from memory).
2. the output actually confirms the claim (exit code 0 or explicit pass statement, not a partial result or a happy guess).
3. for adversarial probes: at least one probe was run and passed, or the change was exempted with reason.
4. for sweep tasks: the ledger shows zero pending and zero blocked entries.
5. for delegated work: you ran the verification command yourself and checked the diff, not relayed the subagent's report.
6. for ambiguous scope: you asked the user to confirm before editing.
7. for broad-radius changes: you captured the baseline first on a clean tree.
8. the completion report is structured (not open-ended), names the status, lists changes, names the next action, explains concerns, and shows verification evidence.
9. no rationalization or confidence substitutes for evidence: "should work", "trivial change", "just a refactor", "ci will catch it" are all rejected at the gate.
10. pre-commit hook failures are fixed at root, not bypassed with --no-verify without evidence of pre-existence.