AI Agent Instructions: Write a Spec It Must Read First

Issue 08 · The specialist

A product on my store came one step away from being invisible. Live, priced, purchasable, and missing from both pages where anyone would go looking for it. Not broken. Just not there.

The step was missing from instructions I wrote that same morning. 13 sections, every claim checked 3 ways, then checked again by a pass that found 6 errors and fixed them. It still had the hole.

What caught it was a thing whose only job is to read those instructions before it touches anything. First time it ran.

What the thing is

Three pieces, and none of them are clever.

→	A written spec. Every procedure for one surface, in one file. What works, what broke, and which of my own past notes turned out to be wrong.
→	A specialist that reads it first. Not "has access to it." Reads it, in full, before doing anything, including before answering a question it thinks it already knows.
→	A gate that makes it the only door. Changes have to come through the specialist. Looking things up stays free. Only changes are stopped.

That third piece matters more than it sounds. I already had the written procedures. I had them for months. The problem was never that they didn't exist. It's that nothing made me open them at the moment I was about to act.

A procedure nobody is forced to read is a procedure you have to remember. That's the same problem again, one layer up.

The honest part

I want to be straight about what this was, because the tidy version isn't true.

I nearly shipped the gate in a way that would have blocked the specialist itself. The documentation doesn't say whether a gate like that also fires on the specialist's own actions, so I left it switched off, ran one harmless test, and looked. It does fire. The naive version would have built a lock and handed the key to nobody.

I also designed a whole tracking file to solve a problem that turned out not to exist. The test showed the information was already there. I deleted the file I'd just written.

I wrote that spec the same morning. It had already been through a checking pass that caught 6 separate errors. It was as good as I could make it. It still had the hole.

Didn't think much about it, to be honest. Other than I'm glad we caught it.

One thing I owe you straight: every other issue has pointed at something you could go click on and poke at yourself. This one does not. It is a document and a couple of files on my own machine, so on this one you have my word and nothing else. I would rather say that than dress it up.

The part you can steal

→	Write the procedure down for the thing you do badly, not the thing you do often. The surface that has cost you a bad afternoon is the one worth a file.
→	Write down what turned out to be wrong, not just what works. A quarter of my file is corrections, including a help page from the platform itself that says something the platform plainly doesn't do.
→	Make reading it a step, not a suggestion. Anything you have to remember to check, you will eventually not check. Usually on the day it matters.
→	Ask it to criticise your instructions before you trust them. That was the whole catch. I told it to be hard on the file, and it was.

What it cost

One working session, and no new tools. No new subscription, no new product, no new platform. It's three text files in a folder: a document, a set of instructions, and a small script that says "not that way."

The waste was real though: a chunk of that session went on the tracking file I threw away, and on designing around a problem I hadn't checked was a problem. Testing it first would have saved me the detour. I keep learning that one.

Would I tell another one-person business to do this? Yes I would. Anything that helps with efficiency and memory is a win in my book.

One caveat, because I said I'd be straight: I gave it a memory that's supposed to carry what it learns from one week to the next. I haven't proven that part works yet. If it doesn't, I'll say so in a future issue rather than quietly not mentioning it again.

See what I build →

If there's one job in your business that you get wrong in a slightly different way every time, that's the one to write down first. Hit reply and tell me what it is.

Or get the build free

Get 3 friends to subscribe and the $29 AI Concierge kit is on the house. No catch, just a deal between us. Subscribe free and you get your own referral link. Hit 3 and the code lands automatically.

Get your referral link →

Next week, a different build, same deal: the thing I made, and the part you can steal. If you know someone who keeps redoing the same job a slightly different way each time, send them this one.

Talk soon,
Tim

Some guy. Not an expert. Just building.

I wrote the instructions. They still had a hole.

Keep Reading

Some Guy & AI