agentleFS
ahmadrishiahmadrishi/agentic-mahoraga/skills/guard/verification-before-advance/SKILL.md

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

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
  1. Distinctive:

    After any source change, before you claim it works.

    line 20
  2. Distinctive:

    Before closing a task, or advancing to the next step of a multi-step plan.

    line 21
  3. Distinctive:

    When asked "did this work?" / "verify my change."

    line 22
  4. Distinctive:

    When you are tempted to write "done," "tested," or "verified."

    line 23
  5. Distinctive:

    verify you chose the *right* check for the change (a clean parse says nothing about behavior).

    line 70
  6. Distinctive:

    verify the code is *correct*, only that this one file parses.

    line 71
  7. Distinctive:

    verify that tests *actually executed* versus were stubbed or skipped.

    line 72
  8. Distinctive:

    verify a cross-service / producer→consumer contract.

    line 73

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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.
  2. Climb the verification ladder and stop at the highest rung you can actually reach; then name that rung in your close:

    RungCheckWhat it provesWhat it does NOT prove
    0dependencies resolve / installyou can build at allnothing about your change
    1typecheck / static analysis (tsc --noEmit, mypy, compiler)types line uptemplates, wiring, behavior
    2build (where one exists)it compiles + links; the minimum barit does the right thing
    3run it / drive the pathbehavior for the case(s) you trieduntried cases; other stacks
    4automated tests execute and passthe asserted cases holdonly what the tests assert
  3. 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.
  4. 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."

  1. Goal: "reproduce a zero-amount charge being accepted, apply the fix, confirm it is now rejected." (verifiable, loopable)
  2. 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).
  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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.