Is a written instruction file more reliable than “watch me do it once”?

Yes. A written instruction file is more reliable than letting an agent watch you do the task once, as long as the file is short, lives next to the work, and states the rule rather than the clicks. “Watch me once” records the path you took on that screen, that day, including the steps you skipped because you already knew them. The agent imitates the recording. Next week the screen is different and the imitation ships the wrong click. The file fails too, when it turns into an essay or when it disagrees with the tools. It still fails less often, and you can see why. A recording does not diff.

I keep the file. I delete the recording after I have turned it into five lines and tested those lines on a clean run.

The demo that taught the wrong click

I recorded myself publishing a draft on a small site. I wanted the agent to do the next one the same way. In the recording I opened the posts list, filtered to drafts, opened the top one, and pressed publish. That top draft was the one I meant, because I had sorted by modified time a month ago and never said so. The recording did not show the sort. It showed a click on the first row.

The next week the agent watched the procedure it had stored and published the first row again. The first row was an old draft I had left as a scratch pad. It went live. The instruction “publish the draft I was just editing” was in my head. The demonstration contained a coordinate on a screen. Coordinates are not rules. The agent was faithful to what I had shown and wrong about what I had meant.

I wrote four lines in a file in the repo: identify the draft by the slug we just saved, not by row position; if more than one draft matches, stop; do not publish if the status filter is not visible; never publish from the list view. I ran it once without the recording in context. It stopped, correctly, when two drafts matched. That stop is the reliability. The demo would have picked a row and felt finished.

What a demonstration actually captures

It captures timing and pixels. You hovered, you knew the password was already filled, you skipped a confirmation because your browser remembered it. The agent does not inherit the memory. It inherits the hover. On the next run the password box is empty, or the confirmation is back, and the imitation either stalls or clicks through a dialog you did not click because it was not there.

It also captures accidents. I scratched my trackpad and the cursor crossed a menu. A careful agent asked whether that menu was part of the task. A faithful one opened it. Neither response is something I want to debug from a video. A file never includes the scratch unless I write it down, and I will not write it down.

Speech during the demo is weaker than people think. I said “obviously check the date” while clicking publish. The word obviously is not a check. The click is the event the system stores. If you want the date checked, the file has to say: read the date field, and stop if it is empty or if it is more than a week old. A sentence you muttered is not in the artifact the next session loads, unless the product transcribed it, and the transcript will be full of “yeah, this one.”

What the file has to be, or it is worse than the demo

Short. A page the agent will not summarize into a different page. I aim for a list of stops and a list of names: which field, which slug, which command, what to do when two matches appear. If I need a story to explain the culture of the team, that story is for humans. The agent file is the stops.

Next to the work. A doc in a wiki the agent does not open is a wish. The file I trust is in the repo or in the folder the task already has to read. If there are two files and they disagree, the agent will pick the one closer to the verb it wants. I keep one.

Tested without the demo beside it. If the recording is still in the prompt, the agent will prefer the clicks when the file is ambiguous. I remove the recording and run the file on a fixture: two drafts, an empty date, a slug that does not exist. The run should stop three times. If it publishes any of them, the file is not ready and the demo would have been worse, not better.

Honest about tools. If the file says “publish” and the only tool is a raw click path, you have written a demo in prose. Say the tool name and the argument that identifies the draft. A file that cannot be followed without guessing is a demo that takes longer to read.

When watching once is the right first hour

I still do the task once myself before I write the file, because I do not know the stops until I have hit them. That hour is for me. I am not training the agent by performance. I am noticing that I relied on sort order. Then I write the file and I do not save the session as the procedure.

Watching is also reasonable when there is no stable name for the object. A one-off visual layout in a tool you will not automate again does not deserve a file. Do it yourself. The failure mode is saving that one-off as “the way we publish” because the agent was watching. I do not turn the recorder on for one-offs. The existence of a recording becomes a procedure someone will replay.

If the task is a judgment — is this sentence fair, is this date a promise — neither a file nor a demo will hold it. The file can say stop and show me. The demo will show me clicking yes, and the agent will click yes. For judgment, the reliable instruction is the stop, not the example of me proceeding.

How the file goes stale, and how the demo goes stale faster

The file goes stale when the button moves and nobody edits the line. I notice on the fixture run, if I still run it. I put the fixture next to the change that moves the button. A demo goes stale the same day the UI changes, and it fails by clicking the control that now occupies the old spot, which might be delete. Stale text stops. Stale clicks act. I would rather maintain a short file than re-record, because a re-record will teach the new coordinate and forget the slug rule again.

I date the file in a line at the top only so I know when I last proved the fixture. I do not write a changelog essay. The proof is a clean run that stopped when it should. If I cannot be bothered to re-run after a UI change, I should not let the agent do the task. The file is not magic. It is a thing I can check. The recording is a thing I will trust because it looks like me.

Where people file the demo by accident

A chat transcript of you doing the task is a demo. So is a screen recording the agent can re-open, and so is a “memory” the product saved because you said “remember this.” I treat those as the recording even if nobody pressed a record button. They will be replayed. If the transcript says you clicked the first draft, the next session has the same bug with a friendlier storage format. After I write the file, I do not leave the session pinned as a pinned example. Examples of success are how row position sneaks back in. The file is the example. If a product requires a demonstration clip to “learn a skill,” I would rather not use that skill. A clip cannot say stop when two slugs match. It can only show me not hitting that case.

Shared team folders make this sharper. Someone else’s recording becomes the procedure because it is the only artifact in the directory. I would rather a blunt file with their name on the stop conditions than their video. If they will not write the stops, the task is not ready for an agent. Watching them once trains every later run on their unsorted list. That is a process bug you can read in a file and cannot see in a replay until the wrong draft is already public.

The practice I actually keep

Do it once, silently, for yourself. Write the stops and the identifiers in a short file beside the work. Delete the recording. Run the file on a case that should stop. If it stops, the agent may follow the file next time. If you are tempted to say “just watch me, it’s faster,” you are about to store a click. The click was faster. The wrong draft going live was the cost of not writing the slug down.