A free chapter from Don't Let the Robot Push to Main

Chapter 4. The prompt is a user story

Rule 4: Write the story for a teammate who will believe every word you wrote, and nothing you didn't.

Chapter 1 covered what I dropped from Scrum. This chapter is about the piece I kept without meaning to.

I didn't notice it at first. Well, I noticed eventually, a few dozen prompts in. Every prompt I wrote that went well had the same shape: what we're doing, who it's for, and how we'll know it's done. That's a user story. Description, use case, acceptance criteria. The prompts that went badly were missing one of the three.

So this chapter starts from something you probably already know. Then it adds the four things a user story never needed, because your new teammate is not a person.

What a user story already gives you

A good story on a human team has three parts.

The description. What we're building, in a sentence or two.
The use case. Who it's for and why it matters to them. This is the part people skip, and it's the part that lets a teammate make good small decisions on their own.
Acceptance criteria. The checklist that says "done". If you can't test it, it isn't a criterion, it's a hope.

I have a habit my AI partners have learned to read. When I'm actually asking something, I start with "Question?", the way Rocky does in Project Hail Mary. When I'm just thinking out loud, I don't. That one word tells the reader which kind of message they're holding. A story needs the same signal. The description and the criteria are the ask. Everything else is background, and it should look like background.

The old advice still holds. Keep the story small and about one thing. I learned this the expensive way: when I put two unrelated bugs in one prompt, the agent tangled them together and fixed neither cleanly. One story, one concern, one commit.

What changes when the teammate is an AI

A human developer on my old teams carried a lot of context the story never had to state. They'd been in the standups. They knew the billing code was sacred. They knew "done" meant the tests ran, not that the tests were written. When they got stuck, they tapped me on the shoulder.

An AI agent has none of that. It is fast, it is tireless, and it reads your story literally. It will also tell you it finished with complete confidence. That isn't malice. It's the job description of a very fast teammate who wasn't in the room.

So the AI version of a user story adds four parts.

Recon first. The story opens by sending the agent to read the actual code and report what it found, before it changes anything. Your agent hasn't been in your standups. Recon is how it catches up, and it's how you catch the agent's wrong assumptions while they're still cheap.
Fences. A short, hard list of what not to touch: no pushing to main, no rewriting a working component, no editing shared files this story didn't claim. A human knows where the fences are. The agent needs them written down every time. Early on, my AI partner cheerfully wrote "push to main" as the last step of a fix, and I asked it if it was going Ex Machina on me. It wasn't. It was doing exactly what nobody had told it not to do.
Stop gates. "Stop here, report what you found, and wait for my approval" before anything destructive or architectural. This is the AI version of the tap on the shoulder, except you have to ask for it.
Proof, not "done". Acceptance criteria the agent has to show, not claim. Which tests ran, with their output. And for anything that matters, proof the test can fail: put the defect back, watch the test go red, then fix it again. A check that passes without having run is worse than no check, because it makes you stop looking.

Two more lines sit at the very top of every story I write now: which model should run it, and which session it goes to. When you have several agents running at once, a story pasted into the wrong session is a story that builds the wrong thing very quickly.

When the criteria fight each other

Here's a version of this that bit me in production, not in a prompt to my coding agent but in the instructions for the AI coach inside the app.

My first tester in Ghana sat down with the app and asked the coach a series of questions. Almost every answer came back as the same canned block of text, word for word. The coach wasn't broken. Two lines in its instructions asked for things the safety checks then refused, so every real answer failed the check and the safe fallback won, every time.

That is exactly what happens to an agent when two acceptance criteria contradict each other. It can't satisfy both, so it satisfies one and reports success, or it quietly takes the exit you left open. Before a story goes out, I now read the criteria against each other and against the fences. If they can't all be true at once, the story isn't ready.

The template

This is the shape of every lane prompt I send. The full version, with notes, is in The Lane Kit as lane-prompt.md.

SESSION: <which session gets this>   MODEL: <which model, and why>
Close this session when: <the exit condition>

## Story
As a <who>, I need <what>, so that <why it matters to them>.

## Context
Why this matters now. What already exists. What "right" looks like.

## 1. Recon (no changes yet)
- Read: <the files, docs and invariants that apply>
- Report: what exists today, what you would change, and any risk you see
STOP. Wait for approval before building.

## 2. Build
Numbered steps, one concern only.

## Fences (do not)
- Do not push. Do not merge to main.
- Do not edit files this story doesn't claim.
- Do not rewrite working components; change only what this story needs.
- <6 to 10 lines, specific to this story>

## Acceptance criteria (show, don't claim)
- [ ] <testable behavior 1>
- [ ] <testable behavior 2>
- [ ] Tests listed by name, with their output pasted
- [ ] For each new test: the defect put back, the test failing, then passing

## Report
What changed, the commit, what you did NOT do, anything parked for later.

A real one, cut down

One of the release notes from launch week reads: "Monthly bills land on their real due day." A bill due on the 31st had been drifting earlier after a short month. Here it is written as a story in this template, cut to its bones.

SESSION: the date-fix lane   MODEL: Opus (date logic, money on the line)
Close this session when: merged, or I say it's parked.

## Story
As someone paying a bill on the 31st, I need it to come back to
the 31st after a short month, so the money I need before payday
is counted on the right day.

## 1. Recon (no changes yet)
Find every place a monthly due date is advanced. Report how a
bill due on the 31st moves through February. STOP.

## Fences
- A due date the user set themselves always wins. Never overwrite it.
- Do not repair existing bills in this story. That is its own story.

## Acceptance criteria (show, don't claim)
- [ ] Jan 31 -> Feb 28 -> Mar 31, not Mar 28
- [ ] Each payment counts toward its own month
- [ ] A user-set day is untouched
- [ ] Each new test fails with the old code put back

Notice the second fence. The repair of existing bills was real work, and it mattered. It got its own story, its own review, and its own day. Keeping it out of this one is what let this one be checked properly.

Make it yours

Small, low-risk fixes? Recon can be one line: "show me the function before you change it."
Working with a human reviewer? Their review can be your stop gate. Keep the fences anyway.
Short on time? Cut anything but the proof line. That's the one that saves you.

Try it

Take the next prompt you were about to send your agent and hold it against the template.

Does it say who this is for and why it matters to them?
Does the agent read before it writes?
Is there a written fence and at least one stop gate?
Can every acceptance criterion be shown, not just claimed?
Could any two criteria fight each other?

What I noticed:

Want the other twelve? The workbook is being finished now.

Back to the playbook