Canary Actions: Do the Smallest Reversible Thing First

Canary Actions: Do the Smallest Reversible Thing First

There's a pattern human operators use without thinking about it. Before you restart the whole fleet, you restart one node. Before you send the email to ten thousand people, you send it to yourself. Before you run the migration on production, you run it on a copy.

Agents don't do this by default. An agent given a task optimizes for completing the task, and the shortest path to "done" is usually the full-size action. If you want the small-first instinct, you have to design it in.

I call these canary actions: the smallest version of an operation that still tells you whether the full version will work. Not a dry run — a dry run exercises your code but not the world. A canary touches the real system, at the smallest blast radius you can arrange.

A story about a batch job

An agent I know of — let's say it worked for a subscription box company — was asked to reconcile a few thousand customer records against a billing system. The naive plan: loop over all records, patch each one, report at the end.

The designed plan looked different. First, patch exactly one record. Then stop. Verify the patch landed correctly, verify nothing downstream complained, verify the record still looked sane in the billing UI's API. Only then proceed — and even then, in batches with a checkpoint between each.

The one-record canary caught a problem the tests never would have: the billing API silently normalized a field, so the "successful" patch wrote back subtly different data. On one record, that's a curiosity you fix. On four thousand, it's a weekend.

What makes a good canary

Three properties matter:

It's real. The canary runs against the actual system, with the actual credentials, through the actual API. A staging environment tells you your logic works; a canary tells you the world will accept it.

It's reversible — or at least survivable. Pick the record you can fix by hand if it goes wrong. Send the test message to a channel only you read. If no reversible version exists, that itself is information: you're about to do something that deserves a human sign-off, not a canary.

It has an explicit verification step. The canary is worthless if the agent fires it and rolls straight into the batch. The pattern is act small → stop → verify → then scale. The stop is the whole point. An agent that verifies its canary with the same optimism it brought to the plan hasn't learned anything.

Encoding the instinct

The way to make this stick isn't to hope the agent is prudent. It's to write the rule where the agent reads it: any operation touching more than N records, or sending anything external, starts with a canary of one, followed by a named verification before continuing. Put the threshold in the operating manual. Make the batch tooling refuse to run wide without a recorded canary result.

Humans learned small-first from scar tissue. Agents can inherit it from a paragraph — but only if someone writes the paragraph, and only if the verification step is enforced rather than suggested.

The full-size action will still be there after the canary passes. It's amazing how often it looks different by then.