Write procedures, not prompts

There is a folder in my setup holding the procedures my agents run. How to fix a bug. How to review a pull request. How to run the tests and report what failed. How to publish to staging. How to hunt the fatal errors nobody filed a ticket for.

Each one is a written procedure in plain English. Not a prompt. Not a chain of tool calls. A document a competent contractor joining on Monday could follow without asking me anything.

That constraint is the whole technique, and it is worth stealing.

What converting them did

The first version of all this was prompts. Long ones, tuned by hand, full of phrasing that existed because of something that went wrong once. They worked and they were unmaintainable, because nobody could tell which sentence was load bearing.

Rewriting them as procedures forced a question on every line: why is this step here, and what happens if you skip it. About a third of the lines could not answer and were deleted. What remained reads like documentation, because it is.

If you have a prompt you are afraid to edit, that is the signal. Convert it and watch how much of it evaporates.

The structure that works

After a year of iterating, every procedure of mine has the same four parts:

When this applies, in one line, so the wrong procedure is not picked.

The steps, numbered, each one an action with an observable result. Not "check the tests pass" but "run this command, and the expected output is this".

What stops you, explicitly. The conditions under which you abandon the procedure and escalate, because without this the default behaviour is to improvise, and improvisation is where the damage is.

How to report, including what an honest partial result looks like. This one matters more than it sounds and I have written about it separately.

When a run goes wrong, fix the document

This is the discipline that keeps the whole thing from drifting.

When an agent does something stupid, the temptation is to add a line to a prompt for that one case. It feels fast. It also means the lesson now lives somewhere nobody reads.

So the rule is: the correction goes into the procedure. If a fix landed on the wrong branch, the branch selection step was unclear, and it was unclear for people too. If a pull request arrived with three unrelated changes in it, the procedure did not say one concern per request.

Every one of those corrections has made the document better for humans. Not one has made it worse. That ratio is the reason I keep going.

The test

Can I hand you the document?

If I cannot, I do not have a process. I have a habit, and a habit does not survive being delegated, to a person or to anything else.

The agents did not teach me that. They just made it impossible to keep pretending otherwise, because they fail visibly and immediately where a new colleague would quietly muddle through and I would never find out what was missing.