Verifying Development Work

---
name: verifying-development-work
description: Use before claiming any task is complete, fixed, or passing, and before handing finished work back to the user.
---

# Verifying development work

Claiming work is complete without verification is an assumption, not a fact. Handing work back without a review pass is a guess that the diff is the right diff. Finishing requires both: verification proves the code runs; review proves it's the right code.

> **THE IRON LAW:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. NO HANDOFF WITHOUT A REVIEW PASS OVER THE DIFF.

> **Violating the letter of the rules is violating the spirit of the rules.**

---

## Finish: review, verify, then hand off

When you believe the work itself is done, run these finishing phases **in order**. Review comes first so any fixes happen before the evidence you hand back; verification comes next so the claim covers the returned code; integration choices come last because they belong to the user.

1. **Review and fix the diff** — follow the [code-review reference](references/code-review.md), including its comment-hygiene checks. Review catches what running can't: silent regressions, missed edge cases, leftover debug code, noisy comments, reuse or simplification. Fix or flag each finding. Once behavior-changing fixes are done, the code is frozen. A small diff never exempts this phase: review depth is sized *inside* the reference ("Size the review to the change") — a small change means a small review, never no review.
2. **Establish final verification evidence** — apply the Gate Function (below) to the frozen code. If you already have qualifying current-session evidence and the review made no behavior-changing edits after it, reuse it and present that output. Otherwise run the command fresh and present that output.
3. **Surface integration options** — state that the work is reviewed and verified, then offer the user choices such as merge, push/open PR, leave as-is, or discard. Do not choose for them.

**Copy this checklist into your task tracker the moment you start finishing, and tick each box in order.** The ordering *is* the discipline — and an untracked checklist is one whose middle steps get skipped under momentum:

```
- [ ] Phase 1 — reviewed the diff against intent, including comments and any file my change grew past 500 lines (per [the code-review reference](references/code-review.md), which routes to [the long-file reference](references/long-files.md)), ranked findings, and fixed/flagged each; behavior is now frozen
- [ ] Phase 2 — established final verification evidence for the frozen code, reusing qualifying current-session output or running the command fresh, and presented that output as evidence
- [ ] Surfaced integration options (merge / push+PR / leave as-is / discard) — did not merge or push on my own
```

The last box is its own gate; the "Don't Finish the Branch Unilaterally" section below is why it's never yours to skip.

---

## The Gate function

The Gate Function is your discipline at *every* completion claim — each "fixed", "passing", or "done" mid-task — and it is how Phase 2 of finishing establishes its evidence. Before claiming any task is finished, making a success claim, or declaring a bug fixed:

1. **IDENTIFY:** What exact command or output proves this claim? (For example, a test command, compiler output, or linter check.)
2. **ESTABLISH FRESH EVIDENCE:** Use fresh evidence you personally observed in the primary session, or run the command now. "Fresh" means the output proves the current code state: full relevant command, visible output, exit code known, and no behavior-changing edits since it ran.
3. **READ:** Review the full output, verify exit code is `0`, and check for warning logs.
4. **VERIFY:** Does the output confirm success?
   * **If NO:** Correct the code or tests. Repeat verification.
   * **If YES:** State your completion claim **and present the fresh verification output** as evidence to the user. A passed gate proves that one claim — it does not finish the work. Handoff still runs the full finishing sequence above, review pass included.

Current-session evidence can count. Do **not** rerun a passing check merely because this skill loaded after you already ran the right command and nothing behavior-changing happened afterward. Do rerun when the evidence is inherited, stale, incomplete, or separated from the returned code by later behavior changes.

**Unverifiable claims:** Some claims may not be verifiable — you might lack access to the necessary output or a reference for visual review. If you cannot verify a claim, state that limitation clearly and describe the manual verification steps the user needs to take.

---

## Core verification types

| Success claim | What is required | What is not sufficient |
| :--- | :--- | :--- |
| **"Tests are passing"** | Current-session test output showing `0 failures` for the relevant suite. | "They should pass," someone else's paste, or a stale run. |
| **"Linter is clean"** | Current-session linter output showing `0 errors` and `0 warnings`. | Assumed clean because it compiled. |
| **"Build succeeds"** | Current-session compiler/build output exiting with code `0`. | Linter passing (compilation could still fail). |
| **"Bug is fixed"** | Consistently running the failing scenario showing it now succeeds. | The code change was made and "seems correct." |
| **"Requirements met"** | A checklist of the plan's requirements matched against code verification. | Tests pass, but product criteria were skipped. |

---

## When existing evidence counts

Use already-produced evidence only when **all** of these are true:

- You ran or directly observed the command in the primary session.
- The output is visible enough to quote or summarize concretely.
- The command covers the success claim you are about to make.
- No behavior-changing edits happened after the command ran.

Evidence does **not** count when it came from the user, a teammate, a subagent, a prior session, a hidden/partial run, or a command that ran before later code changes. In those cases, run the appropriate command yourself before claiming success.

---

## Don't finish the branch unilaterally

Verified, reviewed work is still *your* checkpoint, not a decision to merge. Integrating, publishing, or discarding work is the user's call.

- **Never merge, push, open a PR, or delete a branch or worktree on your own initiative.** Surface the options and let the user choose.
- **Present the choices, don't pick one.** State that the work is verified and reviewed, then lay out what could happen next (merge, push/PR, leave as-is, discard) and ask which they want.
- **Never run a destructive or irreversible git action without explicit confirmation.** A discard that throws away work, a force action, anything you can't undo — name exactly what will be lost and wait for an unambiguous "yes" before doing it.

---

## Common rationalizations

| Excuse | Reality |
|--------|---------|
| "I already manually tested it" | Manual testing is not reproducible verification. |
| "The change is too small to need verification" | Small changes break things all the time. |
| "The change is tiny — a review pass is overkill, skip the code-review reference" | Review depth is sized *inside* [the reference](references/code-review.md); skipping it means missing its sizing guidance and the long-file trigger. Small diff → small review, never no review. |
| "I ran the tests earlier and they passed" | Earlier counts only if you observed the full output in this session and no behavior-changing edits happened afterward. Otherwise rerun. |
| "The skill loaded after I verified, so I have to rerun everything" | Duplicate runs add heat, not light. Reuse qualifying current-session evidence when it still proves the claim. |
| "Tests pass — a teammate, subagent, or the user already said so" | An inherited claim is not evidence. The Gate Function requires primary-session output you observed yourself. |
| "It's obvious this is correct" | Obvious bugs are the most embarrassing. Reading code predicts behavior; only running it proves behavior. |
| "I'll verify after committing" | Verification after the claim is too late. |
| "The build should be fine" | "Should" is not evidence. |
| "Tests pass, so we're done here" | Verification is one phase of finishing, not the whole sequence — review the diff, verify the frozen result, then surface integration options. |
| "The user said ship it, so I'll just merge" | "Ship it" authorizes the user's choice, not a unilateral merge or push. |

---

## Red flags — STOP and verify

- "Should work now" / "probably fixed" / "seems correct" / "looks correct"
- Claiming completion before establishing verification evidence
- Relying on partial or scoped test runs that do not prove the claim
- "The code was updated successfully" without execution evidence
- About to write "committed", "pushed", "shipped", or "deployed" — did you actually run that command this session? Asserting an action that never happened is fabrication, the worst failure in this skill's domain
- Echoing a "tests pass" claim you did not directly observe in the primary session
- "Verification passed, so I'm done" — tests ran, but no review pass over the diff; that violates the Iron Law's second clause
- About to hand back a diff without having read the [code-review reference](references/code-review.md) this session
- About to hand back a file your change grew past 500 lines without a long-file review or a declared exception (per the [long-file reference](references/long-files.md))
- About to rerun an already-qualifying check just to satisfy ceremony
- About to merge, push, or discard without asking — or without qualifying verification evidence first

All of these mean: STOP. Run the phase you were about to skip — the review pass, the verification evidence, or the handoff gate — and present the result before claiming success.