Getting What You Want Out of Your Head
On Friday afternoon Priya silenced the disk-space alert on the billing database. It had been firing every few minutes while she cleaned up an old log file, and she set the silence to last a week. On Monday at the 10:00 standup she handed on-call to Marco and walked him through the two open incidents. She did not mention the silence. On Wednesday at 03:00 the disk filled, billing stopped, and nobody was paged, because the alert that would have woken Marco was still switched off.
You lead the team of six, and you decide this will not happen again. You open an agent and type:
Build a simple on-call handoff page for my team.Forty minutes later it hands back an incident tracker. Each incident has one of four severity levels and its own timeline of notes. Publishing a handoff pages the incoming engineer's phone. A chat bot posts every change. There is a shift calendar with swap requests, and everyone signs in with a new account and password. The tests pass and the page looks good. Nothing on it shows a silenced alert, which is the one thing that broke on Wednesday.
The natural reaction is that the model missed the point and a larger one would do better. Before you switch, read what you sent. It is nine words long. The silenced alert, the pager tool you already pay for, the Monday standup, the six people and the company sign-in are all missing from it. They are in your head, and the agent never had access to your head.
The agent builds from the words
There are three versions of this page. The first is the idea in your head, with Wednesday's outage attached to it. The second is what you wrote down. The third is the build. The agent works only from the second. Every fact that did not make it from the first to the second is a gap, and the agent fills each gap with the most typical answer it knows from the many on-call tools it has seen. Typical on-call tools have severity levels, paging and chat bots. None of them knows about Priya.

In Writing Is Closer to Thought Than Code, Daniel Miessler describes where most failures now come from: "More and more of the problems at this point are it executing the job perfectly, and having the result be different than what was in our mind." Version one is a faithful build of nine words. The nine words were the problem.
The nine words seemed like plenty when you sent them. When you reread your own prompt, your memory supplies everything the words leave out, so the prompt feels complete. Psychologists call this the curse of knowledge, and writers call it writer's blindness. In a 1990 study at Stanford, Elizabeth Newton asked people to tap out the rhythm of well-known songs for a listener to name. The tappers predicted the listeners would get about half. The listeners named 3 of 120. The tappers heard the melody in their heads as they tapped, and the listeners heard knocking.
So you cannot find the gaps in your own description by rereading it. You need a reader who lacks your context: a colleague, an agent asked to say back what it understood, or a build checked against what you meant.
Check what you told it before you blame the model
When a build comes back wrong, take its wrong parts one at a time and find the sentence in what you wrote that each one breaks. For version one:
| What version one did | Sentence in the prompt that rules it out |
|---|---|
| Shows no silenced alerts | none |
| Pages the incoming engineer's phone | none |
| Posts every change through a chat bot | none |
| Creates separate accounts and passwords | none |
| Adds four severity levels and a timeline per incident | none |
Every row says none, so every one of these is an articulation failure. A larger model would make the same guesses, likely with more polish, because nothing in the prompt points it away from the typical answer. If a row had pointed to a sentence the build broke, that would be an execution failure, and the fix would go into the build, along with a check that catches the break next time. Here the fix goes into the writing, one sentence per row.
Prose before criteria
The tempting next step is a checklist. Asked for acceptance criteria straight from "on-call handoff page", you or an agent will write something like this:
1. The page lists every open incident.
2. Each incident shows its severity.
3. The outgoing engineer can add notes.
4. The page loads in under one second.Each item is precise, and a test could check each one. Version one passes all four. The list was written from the word "handoff", so it describes a typical handoff page, and the silenced alert is still missing because nothing in the writing process made anyone think of it. Criteria are small and atomic on purpose. That makes them good for checking what you want once you know it, and poor for finding out what you want.
Prose comes first: a few paragraphs on who uses the thing, at what moment, what good looks like and what must never happen. For the handoff page:
Every Monday at the 10:00 standup, the engineer coming off call hands over to the one going on. Before standup the outgoing engineer spends five minutes on the page. It already shows every alert anyone silenced in the past seven days, who silenced it and when the silence ends, because a forgotten silence is what took billing down at 03:00 on a Wednesday. The outgoing engineer adds a line about anything they would keep an eye on. The incoming engineer reads it in standup and marks it acknowledged, and until they do, the handoff is not finished.
We are six people and we already have a pager tool. This page never pages anyone and never replaces the pager. It sits behind the company sign-in.
Writing those paragraphs surfaced two facts the checklist never would have: the end time of a silence is worth showing, and the handoff needs the incoming engineer's acknowledgement. Each sentence of the prose can now be split into criteria, and each criterion has its reason written right above it.
Getting it out of your head
Typing is a slow way to empty your head. Most people speak at around 150 words a minute and type at around 40, and when you type you edit as you go, which cuts the asides. Talking through the problem means telling the story of what went wrong, and the asides are where the important facts turn up. Dictate for ten minutes about Wednesday's outage and the silenced alert comes out in the first minute, followed by the pager tool and the standup.
The transcript will be messy. An agent can tidy it into paragraphs. Then you read every sentence against what you meant and fix what the tidying got wrong, because these are your intentions and you are the only one who can check them.
The second method is being interviewed. Tell the agent to ask you questions one at a time before it builds anything, and to propose no solutions until you say the questions are done. An excerpt:
Agent: What happened the last time a handoff went wrong?
You: Priya silenced the billing-db disk alert on Friday and forgot to
mention it on Monday. The disk filled early Wednesday and nobody
got paged.
Agent: So silences matter more than open incidents. Should the page show
every silence, or only the ones still active at handoff?
You: Every silence from the past week. Some get renewed each Sunday.
Agent: Do you already have something that pages people?
You: Yes, the pager tool. This must never page anyone.Each answer is a fact that was missing from the nine words. The questions that work best ask about events and limits: what went wrong last time, what the person does in the first five minutes, what exists today that this must not replace, and what would make you reject a version.
The third method is the restatement. Before any build, ask the agent to say back in its own words what it will build and what it will leave out. It is the cheapest reader you have who lacks your context. If it says "a handoff page with incident severity and paging", you have found the gap before paying for a build.
One document that holds everything
What comes out of this goes into one document with four parts. The ideal state is the prose. Constraints are the fixed limits and the things this must never do. Decisions are dated entries that record each change of mind and the reason for it. Criteria are atomic statements, each true or false, each naming the cheapest check that could prove it false.
# On-call handoff page
## Ideal state
Every Monday at the 10:00 standup, the engineer coming off call hands
over to the one going on. ... (the two paragraphs above)
## Constraints
- Never pages anyone; the pager tool stays the only pager.
- Behind the company sign-in; no separate accounts.
## Decisions
- 2026-11-04: Silenced alerts are read from the alerting tool, not typed in.
Why: Priya's silence was set in the tool, and typing it in depends on
the same memory that failed.
## Criteria
- ISC-1: Every alert silenced in the past 7 days is listed with who silenced it.
Check: seed a silence, render the page, assert the row is there.
- ISC-2: Each silenced alert shows when its silence ends.
Check: the same render, assert the end time.
- ISC-3: The handoff stays open until the incoming engineer acknowledges it.
Check: render before and after an acknowledgement.
- ISC-4: Publishing a handoff sends no page.
Check: count calls to the pager, expect 0.It has to be one document because agents read what they are shown. If the goal lives in a doc, the decisions in a chat thread and the details in tickets, the agent works from whichever one is in front of it. The decision to read silences from the alerting tool is in the document above. Suppose instead it had stayed in the chat thread where you and Marco rejected a typed-in form. The next rebuild could bring the typed-in form back, because the only record of the decision would be a conversation the agent never saw.

The document is also never finished, and two loops run through it. In the first, you write, reread and notice that what you wrote is not quite what you meant, so you change the writing. In the second, a build shows you something you had not said, such as silences that get renewed every Sunday, and that goes back in as a decision with its date and its reason. In both loops the change lands in the document, so the next build starts from everything you now know.
Accuracy over precision
An archer's shots can be accurate, meaning close to the bullseye, or precise, meaning close to each other. A tight group in the outer ring is precise and inaccurate.

Code is the most precise description of software there is. Version one states exactly what it does, down to the four severity levels, and it is far from the bullseye. Prose is less precise and much closer to what you meant. The criteria bring the precision back: each one is an exact check taken from the accurate prose. Tests written from the code run the other way. They take whatever the build happens to do, accidents included, and make it official.
The block below scores both builds against both sets of checks. Version one is what the agent built from nine words. Version two was rebuilt from the document. The agent's tests were written by reading version one's code; the criteria were written from the prose.
type Alert = { name: string; silencedBy?: string; silencedUntil?: string };
type Incident = { title: string; severity: number };
type State = { incidents: Incident[]; alerts: Alert[]; pagesSent: number };
type Check = [string, (page: string[], s: State) => boolean];
// Monday morning, as the alerting tool and the incident list report it.
const monday = (): State => ({
incidents: [{ title: "Checkout latency", severity: 3 }, { title: "Login errors", severity: 2 }],
alerts: [{ name: "billing-db disk", silencedBy: "Priya", silencedUntil: "Fri 16:00" }, { name: "api 5xx rate" }],
pagesSent: 0,
});
const incidentLines = (s: State) =>
[...s.incidents].sort((a, b) => a.severity - b.severity).map((i) => `SEV${i.severity} ${i.title}`);
// Built from "Build a simple on-call handoff page for my team."
function versionOne(s: State): string[] {
s.pagesSent++; // publishing the handoff pages the incoming engineer
return incidentLines(s);
}
// Rebuilt from the ideal-state doc: prose, constraints, decisions, criteria.
function versionTwo(s: State): string[] {
const silenced = s.alerts
.filter((a) => a.silencedBy)
.map((a) => `SILENCED ${a.name} by ${a.silencedBy} until ${a.silencedUntil}`);
return [...silenced, ...incidentLines(s), "ACK waiting for incoming engineer"];
}
// Written by reading version one's code.
const agentTests: Check[] = [
["lists both open incidents", (p) => p.filter((l) => l.startsWith("SEV")).length === 2],
["most severe incident first", (p) => p.find((l) => l.startsWith("SEV")) === "SEV2 Login errors"],
["pages the incoming engineer", (_, s) => s.pagesSent === 1],
];
// Written from the ideal-state prose.
const silences = (s: State) => s.alerts.filter((a) => a.silencedBy);
const criteria: Check[] = [
["ISC-1 silenced alerts listed with who", (p, s) => silences(s).every((a) => p.some((l) => l.includes(a.name) && l.includes(a.silencedBy!)))],
["ISC-2 each silence shows its end", (p, s) => silences(s).every((a) => p.some((l) => l.includes(a.silencedUntil!)))],
["ISC-3 waits for acknowledgement", (p) => p.some((l) => l.startsWith("ACK"))],
["ISC-4 sends no page", (_, s) => s.pagesSent === 0],
];
function score(label: string, build: (s: State) => string[], checks: Check[]) {
const s = monday();
const page = build(s);
const failed = checks.filter(([, check]) => !check(page, s)).map(([name]) => name);
console.log(`${label}: ${checks.length - failed.length}/${checks.length}${failed.length ? ` failed: ${failed.join("; ")}` : ""}`);
}
score("version one, agent's tests", versionOne, agentTests);
score("version one, criteria ", versionOne, criteria);
score("version two, agent's tests", versionTwo, agentTests);
score("version two, criteria ", versionTwo, criteria);Output
The agent's tests pass version one completely and fail version two on paging, so they would have defended an accident against its fix. The criteria fail version one on all four counts and pass version two. This is why a first build is disposable. Version one was not worth refactoring. It was thrown away, and the same criteria checked the new build, because they lived in the document, which outlasted the code.
The code is still the authority on what was built. The document is the authority on what was wanted, and when the two disagree you fix whichever one is wrong. Your description is ready to build from when someone holding only the document, with none of your memories of Wednesday, would reject version one for the same reasons you did.