# Verification Before Completion

> Runs the checks and reads their output before any claim that work is done. Use when work is about to be called complete, fixed, passing, done, or satisfactory, before any commit or PR, when evidence may be stale, partial, or bound to another state, or before saying that should do it, it's working now, or all set, even if no formal claim is made.

- Skill: `augments-labs/verification-before-completion` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add augments-labs/verification-before-completion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/augments-labs/verification-before-completion/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: augments-labs (https://skillmd.com/u/augments-labs)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/augments-labs/verification-before-completion

---


# Verification Before Completion

## When to use

- **Never skip**, even before a plan's next task. Step 1.3 decides which
  checks run, not the size of the change: a one-line fix still runs the
  smallest check that could fail.
- A change visible in a running GUI or TUI adds `visual-ui-verification` to
  the checks Step 1.3 picks.

## Available scripts

- **`scripts/state-identity.sh`** — captures and re-checks the state identity
  (a hash of the working-tree content; with `--committed`, the commit) in
  Steps 1.4 and 2.4.

## Step 1: Pin down the claim

1. List every item the request asked for, including anything added later,
   with one row for each variant an item names or the code keeps in parallel
   (sync and async, each platform, each caller). Record a decision for each
   row: delivered, pending, blocked, or declined with a reason.
2. Keep an evidence record (the ledger): add to it, never rewrite it, and
   keep it outside the state under check. One task with one required check:
   one row in your reply holds the claim, the check, the state identity, and
   the raw result; ignore steps that name a full-record field. An
   integration, a release, or more than one check: open the full record,
   `assets/evidence-ledger.md`, before the first check runs and fill every
   field.
3. Add one `Results` row per check that the task, the plan, or the project's
   standing schedule of checks requires here. A required check that is
   missing, only planned, blocked, or unexplained makes the claim pending
   before anything runs. If the requirement names a person who must accept
   the work, read `references/manual-acceptance.md` before its row.

   A check counts for a changed file only if its configuration includes that
   file. Add a row for every project check whose configured scope includes a
   changed path, even one nothing listed. If that check already reports errors
   on the base, run it on the base in a separate worktree, never by switching
   the state under check, and compare the two error lists instead of
   expecting zero: an error the base lacks fails the row; an inherited one
   that matches an approved pre-existing exclusion in the workspace record
   stays listed and limits the claim to "no new errors"; one with no
   exclusion is an unexplained red: list it and keep the claim pending.
4. Capture and record the state the checks will run on; add `--committed`
   when it is a commit:

   ```bash
   bash scripts/state-identity.sh --quiet
   ```

5. Fill `State` with what the script cannot see.

## Step 2: Run the checks

1. Reuse an earlier result only while the record's `Invalidation` list still
   allows it here, and record why. Run the rest fresh.
2. If a check times out, fails partway, runs in the background, or changes
   something it should not, read `references/unsettled-runs.md` before
   recording its row. If it fails again with nothing changed, diagnose or
   return pending; never rerun until one passes.
3. Read the raw output, not the exit code, and record the run in its row;
   redact only the copy you show your human partner. If an assertion could
   not have failed for this code, or the runner replayed a cached result or
   skipped the test, say so and do not count its green;
   repairing the task's own test belongs to `test-driven-development`, and
   repairing a project or battery gate to `verification-strategy`.

   If a reading is zero, empty, or "no errors", count it only after the same
   probe, run the same way, returned a hit on a known-positive input. A
   surface the run never exercised is unverified, not clean: name it in the
   row. If the tool that acted reports a value (rows written, a file saved, a
   setting applied), count it only once you read it back through an
   independent path.
4. Re-check the state with the flags used at capture:

   ```bash
   bash scripts/state-identity.sh --compare {{recorded value}}
   ```

   Any nonzero exit leaves the claim pending; follow
   `references/unsettled-runs.md` for that exit code before anything else.
   Never commit to make the identities match. On 0, compare the other
   `State` inputs yourself.

## Step 3: Claim and return

1. A required check that failed, did not run, or ran on another state makes
   the result red: not complete. Fill `Inventory reconciliation`.
2. Write the claim the rows support and nothing wider: what passed, on which
   state identity, what is pending.

   An off-by-one fix to `due_date`: `pytest tests/test_due.py::test_last_day`
   on commit `4f2a9c1` prints `1 passed`. That supports "the test passes on
   `4f2a9c1`", not "fixed": nothing shows that test failing before the fix,
   and the rest of the suite has not run.

3. A checkpoint commit reuses rows whose check reads only file content, and
   only when `--compare {{recorded value}} --committed` exits 0; once it
   does, record each reused row again under the committed revision. Commit,
   CI, and review checks bind to their own revision.
4. **REQUIRED — return the record; this skill routes nowhere.** Every unmet
   check goes back with it, failed and inconclusive rows intact, to the
   pending step of whatever asked; never invoke that caller.
   `using-sdlc-skills` routes what follows; only `release-readiness` decides
   release.
5. Run no commit, push, PR, or merge from this skill.

## Gotchas

- A partial commit leaves reviewed files uncommitted while the hash still
  matches; only `--committed` proves a commit holds a row's state.

## Hard stops

- Never report done while any requested item has no recorded decision.
- Never claim a test passes without seeing it pass on the recorded state.
- Never claim a bug fixed without a reproduction that failed before and
  passes after, plus exact evidence of the control and that the fixed code
  was restored after the failing run.
- Never turn a worker's "success" report into evidence; inspect its diff,
  state, and raw output.
- Never change the state under check with the bookkeeping meant to prove it.
- A check never seen to fail for the defect it guards is suspect. Read
  `references/hollow-verification.md` before citing its green.
- An empty or zero result is a claim about the instrument until a positive
  control shows it can see the population in the environment the system runs
  in. Output you produced by hand shows you can run the command, not that the
  system acted. Read `references/hollow-verification.md` before citing either.
- A check silenced is not a check passed. Suppressing a finding, lowering a
  strictness setting, or excluding a path changes what ran, not what is true;
  the claim that check supported is now unproven.
- A flaky green is unexplained nondeterminism; send it through `debugging`.
- Verified is not reviewed. Off `using-sdlc-skills`' short route, a
  completion or integration boundary needs `requesting-code-review`; a
  task's checks passing is not that boundary unless its plan says so.

## When tempted to skip

| Thought | Reality |
| --- | --- |
| "It should work" | Run the check and make it a fact. |
| "I ran it earlier" | The state may have moved since, the result may be too old, or it may not cover this claim. |

