Verifying Development Work

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, 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

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

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 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)
• 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.