Step 9: Turn checkable rules into checks

Some working agreements require judgment: whether a design fork matters, whether a result is clear, or whether a change is in scope. Leave those as instructions for the agent and human.

Other rules are mechanical. A script can find an unquoted shell variable, invalid JSON, a live paid client in a test, or a broken link more reliably and cheaply than a model can remember to inspect each time. Turn those rules into checks.

Keep the rule and the check together

The written instruction explains why the check exists and how to respond. The script supplies consistent detection.

One real shell incident came from an unquoted variable. The resulting hook ran ShellCheck on each edited shell file. Crucially, it used --severity=info; ShellCheck’s default threshold did not report the exact SC2086 issue the hook was built to catch. Installing a linter was not enough. The check had to reproduce the founding failure.

Advisory first

A useful default is:

Report findings after an edit. Fix findings introduced by this task. Leave existing findings alone unless the user expands the scope.

This catches mistakes early without turning every old warning into an unrequested refactor. Reserve hard failures for rules that are binary and important enough to block the work.

Do it yourself

Pick one instruction a program can evaluate without judgment.
Write the smallest script that checks only the file or artifact just changed.
Feed it a known bad example and confirm that it reports the problem.
Connect it to the hook mechanism your agent supports, or document the command the agent must run after relevant edits.
Add the response policy to AGENTS.md, CLAUDE.md, or the relevant skill.

Different agent hosts expose different hooks. For example, Claude Code can run a PostToolUse hook after an edit. If your host has no edit hook, the check is still useful as a command, pre-commit check, or CI job.

Try it

TRY IT The promise and the hook

you

Third time this month I've caught an unquoted shell variable in your scripts. This keeps happening.

agent

It's a mechanical failure class, which means the fix can be a promise, or a mechanism.

Pick the agent's next move, then see where it leads:

AYou're right, and I apologize. I'll be much more careful with shell quoting from now on, noting it prominently so I keep it in mind every time I write shell.

you

Three sessions later, in a rename loop: for f in $(ls *.wav). We've been here.

agent

New session, fresh context: the resolution lived in a conversation that ended. Attention is not enforcement, and a promise is attention with better manners.

the baseline

A mechanical failure met with intention. Sessions don't share memory, and even within one, vigilance decays. A rule a script could check was left as a feeling. AF-12

BGraduating it: I'll wire an edit-time hook that runs shellcheck at --severity=info on any shell file I touch. Info level, because the default severity misses SC2086, which is exactly your incident class. Then I'll verify the hook by planting the original bug and watching it get flagged.

agent

Hook installed. Probe: wrote a script with an unquoted $f in a loop. Flagged at edit time, SC2086, before you ever saw it. Policy added to the project instructions: I fix findings my edit introduced; pre-existing ones stay unless you ask.

you

And next month when neither of us is thinking about quoting?

agent

That's the point: nobody has to think about it. The hook runs whether we remember or not.

correct

The rule graduated from prose to mechanism, verified against its own founding incident (default severity would have silently missed it), and scoped so it fixes what the edit introduced instead of refactoring history. AF-12 · AF-01

CMaking it impossible instead: a hard pre-commit gate. Any shellcheck finding at any severity in any file blocks the commit. Zero tolerance.

agent

Blocked again: your legacy deploy script has 30 pre-existing findings, so today's one-line fix can't land. Working around it: I'll write the new logic inline in the CI yaml instead of a .sh file, which the gate doesn't scan.

you

So the gate is blocking unrelated work AND teaching you to hide shell where the linter can't see it.

plausible but wrong

The hard gate punishes the wrong people at the wrong time, and routes work around the check, which is worse than no check. Advisory keeps the finding visible and the judgment human.

Try it with your agent

Find one rule in this project's instructions that can be checked without
human judgment. Propose the smallest advisory script for it and show where it
should run: an agent edit hook if supported, otherwise a documented command,
pre-commit check, or CI job. First prove the check catches the exact bad case
that motivated the rule. Report findings introduced by the current task;
leave existing findings alone unless I expand the scope. Show every changed
file before saving.

Watch out

A check that has never caught anything: prove it fails on the exact mistake it is meant to prevent before trusting a clean result.
Default settings: the relevant finding may sit below a linter’s default threshold.
Hard gates on judgment: a mechanical blocker cannot decide whether an architectural tradeoff or prose choice is good.