verification-before-advance
Skill1 starsChanged 16 days agoMITView on GitHub
Use before claiming a task done or moving to the next step of a multi-step plan — turn the task into a verifiable goal, climb the highest verification rung you can actually reach (deps → typecheck → build → run → tests), and report UNVERIFIED with a reason when a rung is unreachable rather than guessing. Honest about hooks — the shipped PostToolUse check (hooks/verify-after-edit.sh) runs a fast per-file syntax check and SURFACES the result, but a PostToolUse hook CANNOT block (Claude Code ignores its exit code) and cannot certify that the behavior is correct, that the right check ran, or that tests really executed. Do NOT use for the exact words you close with once verified (that is honesty-vocabulary) or for whether the output reaches its reader (that is trace-to-consumer).
In this repository15 other files it gives its agents.
- codebase-mapping-forgeSkill
- conformance-lintSkill
- skill-editorSkill
- spec-style-forgeSkill
- honesty-vocabularySkill
- karpathy-guidelinesSkill
- reuse-before-createSkill
- simplicity-firstSkill
- small-diff-surgical-changeSkill
- surface-assumptionsSkill
- trace-to-consumerSkill
- adversarial-review-loopSkill
- blind-evalSkill
- sandbox-isolationSkill
- skill-improvement-loopSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
After any source change, before you claim it works.
- Distinctive: line 21
Before closing a task, or advancing to the next step of a multi-step plan.
- Distinctive: line 22
When asked "did this work?" / "verify my change."
- Distinctive: line 23
When you are tempted to write "done," "tested," or "verified."
- Distinctive: line 70
verify you chose the *right* check for the change (a clean parse says nothing about behavior).
- Distinctive: line 71
verify the code is *correct*, only that this one file parses.
- Distinctive: line 72
verify that tests *actually executed* versus were stubbed or skipped.
- Distinctive: line 73
verify a cross-service / producer→consumer contract.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Verification Before Advance
"It should work" is not "it works." The failure this prevents is advancing — closing a task, or moving to the next step — on the strength of a mental model instead of an executed check. The rule: before you claim done or advance, run the highest verification you can actually reach, and name exactly what it proved. And be honest that a hook can nudge this but cannot certify it.
When it triggers
- After any source change, before you claim it works.
- Before closing a task, or advancing to the next step of a multi-step plan.
- When asked "did this work?" / "verify my change."
- When you are tempted to write "done," "tested," or "verified."
The rule — turn the task into a goal, then climb the ladder
- State a verifiable goal up front. "Add validation" → "write a check for invalid input, then make it pass." "Fix the bug" → "write a check that reproduces it, then make it pass." Weak criteria ("make it work") cannot be looped on and hide failure.
Climb the verification ladder and stop at the highest rung you can actually reach; then name that rung in your close:
Rung Check What it proves What it does NOT prove 0 dependencies resolve / install you can build at all nothing about your change 1 typecheck / static analysis ( tsc --noEmit,mypy, compiler)types line up templates, wiring, behavior 2 build (where one exists) it compiles + links; the minimum bar it does the right thing 3 run it / drive the path behavior for the case(s) you tried untried cases; other stacks 4 automated tests execute and pass the asserted cases hold only what the tests assert - If a rung is unreachable (no network, no fixtures, no test harness, private registry), that is a legitimate UNVERIFIED — say so with the reason. Do not guess a green or fabricate a result.
- Close with the honesty vocabulary (→
honesty-vocabulary): name the rung you reached; never write "tested" unless real tests actually ran.
Producer↔consumer contract — the rung the build cannot climb
A build proves each side compiles in isolation; it can never prove that a downstream reader
consumes the value an upstream writer emits, because there is often no compile-time link across the
boundary. On any change spanning two sides of a contract (a shared attribute key, a value's
units/semantics, a detection condition), run the design-time contract check in
trace-to-consumer before you close — two green builds do not
prove the two sides agree.
Key points — honest about what the hook can and cannot do
This is the theme that keeps GUARD honest, so state it exactly. The pack ships
hooks/verify-after-edit.sh (auto-discovered via
hooks/hooks.json) as a PostToolUse hook on Write|Edit.
It runs a fast per-file syntax check keyed on the file's extension — .py → python3 -m
py_compile, .sh → bash -n, .json → json.load, .js/.mjs → node --check (only when node
is present), anything else → prints UNVERIFIED (no fast offline check for <ext>) — and surfaces
that verdict on stderr. Then it always exits 0.
Why exit 0 always: a PostToolUse hook CANNOT block. Claude Code runs it after the tool has already applied the edit and ignores its exit code (exit 2 is not honored, unlike PreToolUse). So this hook is a surfacing / reminder mechanism, not a gate — it cannot stop you advancing, and it does not run a full build. Even setting that aside, a syntax check cannot:
- verify you chose the right check for the change (a clean parse says nothing about behavior);
- verify the code is correct, only that this one file parses;
- verify that tests actually executed versus were stubbed or skipped;
- verify a cross-service / producer→consumer contract.
Those are model-judgment rungs. So verification-before-advance is skill-prose plus a PostToolUse
surfacing check — the discipline does the gating, the hook only reminds. Never treat a green hook as
proof the behavior is right; treat it as "this file parses," and climb the ladder above yourself.
(The one row of GUARD that IS a hard block lives elsewhere — see
small-diff-surgical-change's PreToolUse gate.)
Worked example
Task: "Fix the bug where a zero-amount charge is accepted."
- Goal: "reproduce a zero-amount charge being accepted, apply the fix, confirm it is now rejected." (verifiable, loopable)
- Climb: typecheck ✓ (rung 1) → build ✓ (rung 2) → run the repro: a zero-amount charge now returns a validation error, a positive charge still succeeds ✓ (rung 3).
- Close: "SMOKE-VERIFIED — reproduced the zero-amount input, applied the guard, the path now rejects it and a valid charge still succeeds. Not exhaustively tested; no automated test added."
Counter-example (overclaim): applying the guard, seeing the build pass, and closing "done, the validation works and is tested" — no run, no test. The honest close is BUILD-VERIFIED, behavior UNVERIFIED.
Anti-patterns
- "It should work" / "this looks correct" as a close.
- Writing "tested" when no test ran, or adding a do-nothing stub and calling it verification.
- Skipping the build because "it's a one-line change."
- Treating a green PostToolUse hook (the file parsed) as proof the behavior is right — worse, treating it as a gate at all; it surfaces after the edit and cannot block.
- Guessing a result when a rung is unreachable instead of reporting UNVERIFIED with the reason.
- Advancing to step N+1 of a plan without checking step N met its criterion.
Related skills
honesty-vocabulary— the exact words you may close with once you know which rung you reached.trace-to-consumer— the contract rung a build cannot climb.small-diff-surgical-change— a small diff is faster and safer to verify.karpathy-guidelines— bias 4 (goal-driven execution), in context.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

