The verification-before-completion skill, reviewed

What it tells the agent to do

1. Identify the command whose output would prove the claim.
2. Run that command fresh and in full, not a partial or earlier run.
3. Read the full output, check the exit code and count failures.
4. If the output confirms the claim, state it with the evidence; if not, state the actual status.
5. For regression tests, revert the fix and confirm the test fails, then restore it and confirm it passes.
6. For delegated agents, check the VCS diff instead of trusting their success report.
7. For requirements, re-read the plan, make a checklist, and verify each item.

Lines worth reading

Straight from the file, with why each one matters.

1. line 3Use when about to claim work is complete, fixed, or passing

   A trigger tied to a moment rather than a topic. It fires on the agent's own urge to declare victory, which is when it matters.

2. line 35Skip any step = lying, not verifying

   Blunt framing. It works because it removes the comfortable middle ground of "mostly checked.

3. line 84Revert fix → Run (MUST FAIL) → Restore → Run (pass)

   The useful trick here: a regression test only counts once you've watched it fail without the fix.

4. line 47VCS diff shows changes

   Telling: subagent success reports aren't trusted either. Check the diff, not the claim.

5. line 70Exhaustion ≠ excuse

   Rationalizations written as if the model gets tired at 5pm. Funny, and it pre-empts excuses before they appear.

Watch out for

• Low

  The red-green step tells the agent to revert a fix. Done carelessly on uncommitted work (e.g. a checkout), the fix could be lost.

  line 84Revert fix → Run (MUST FAIL) → Restore → Run (pass)

The scorecard

• TriggerSays when to use it
  9/10

  Names the moment and the words: complete, fixed, passing, committing, PRs.

• FocusOne clear job
  9/10

  One job: no success claim without fresh evidence.

• LeanLight to load
  8/10

  About 120 lines, but red flags, excuses and "when to apply" repeat each other.

• ConcreteSteps you can follow
  7/10

  Clear gate and claim-to-evidence table, but no help finding the right command.

• SafeSafe to run
  9/10

  No network, secrets or destructive commands. Only the revert step needs care.

How it could be better

1. Say how to find the verification command

   The gate begins with "what command proves this claim?" but gives the agent no place to look.

   Add

   To find the command, check in order: <project README test section>, package.json scripts / Makefile / pyproject, then the CI config (<e.g. .github/workflows/*.yml>). Use the same command CI runs.

   Copy

2. Make the revert step non-destructive

   Reverting a fix to watch the test fail can throw away uncommitted work if done with checkout or reset.

   Add

   To revert the fix temporarily, use `git stash push <changed files>` and later `git stash pop`, or commit first. Never use `git checkout --` or `git reset --hard` on uncommitted changes.

   Copy

3. Show the shape of an evidence-backed report

   Saying "state claim WITH evidence" is less useful than a template the agent can copy into its reply.

   Add

   Report like this:
   Ran: `<command>`
   Result: <exit code>, <N passed / M failed>
   Status: <claim, or the actual state and what remains>

   Copy

4. Merge the overlapping lists

   Red Flags, Rationalization Prevention and When To Apply say much of the same thing, and every line stays in context.

   Add

   ## Red flags (stop and verify)
   - Words like "should", "probably", "Done!" before running anything
   - About to commit, push, open a PR, or move to the next task
   - Trusting a subagent's report or a partial check

   Copy