Building Software
Sections

Contents Section 1, Ideal State

Articulating the Ideal State

Getting what is in your head into one written document an agent can build from and a stranger can check: ideal-state prose first, then constraints, dated decisions and criteria.

Section 1 of 9, subsection 1 of 5. Depth: do. Core 1 of 25. An 8-minute read.

Mistakes to catch in review

  1. A team switches to a larger model after an agent builds the wrong thing, when the prompt never stated the fact the build got wrong.

  2. Acceptance criteria written straight from a one-line request, so every check is precise and version one passes all of them while missing what the person needed.

  3. Accidental features of a first build, such as paging or a chat bot nobody asked for, getting tests because the code became the only record of what anyone wanted.

  4. A decision made in a chat thread that never reaches the ideal-state document, so the next rebuild brings back what the team had rejected.

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:

Output
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.

Three boxes from left to right: Idea in your head, with Wednesday's outage attached; What you wrote, nine words, highlighted; and The build, version one. An arrow labelled captured runs from the idea to what you wrote, and a dashed arrow labelled memory fills gaps runs back. An arrow labelled agent runs from what you wrote to the build. Under the idea, a group labelled left in your head holds silenced alert, pager tool, Monday standup and company sign-in. Under the build, a group labelled typical answers holds severity levels, paging and chat bot, with an arrow up into the build. Notes in the middle say the agent reads only the words and rereading hides the gaps.
The agent reads only what you wrote, so the silenced alert, the pager tool, the standup and the sign-in never reach it, and typical answers take their place. Rereading does not reveal the gaps, because your memory fills them in.

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:

Output
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:

Output
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.

Markdown
# 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.

Three boxes from left to right: Your intent, The document in the middle, highlighted, holding ideal state, constraints, decisions and criteria, and The build. Above the left pair a label reads loop one, with an arrow labelled write from intent to the document and a dashed arrow labelled reread, revise coming back. Above the right pair a label reads loop two, with an arrow labelled build from it from the document to the build and a dashed arrow labelled dated decision coming back. A note under the document says every change lands here.
Both loops end in the document. Rereading changes the writing, and anything a build shows you goes back in as a dated decision, so the next build starts from what you now know.

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.

At the top, What you meant, highlighted. Below it on the left, Prose, close but loose, joined to it by an arrow labelled near. On the right, Code, exact but far off, joined by a dashed arrow labelled far. Under prose, an arrow leads to Criteria, exact checks from prose. Under code, an arrow leads to Tests from code, accidents made official. A note says precise is not accurate.
Prose lands close to what you meant and code lands exactly, far off. Criteria carry exact checks out of the prose; tests read off the code carry its accidents.

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.

TypeScriptRuns in your browser
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);

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.

Check your understanding

6 questions on this lesson. Pick an answer to see whether it holds and why.

  1. 1A product lead sent this prompt. The agent's page lists every commit message from the last month, grouped by day. She wanted short customer-facing notes on new features, written by the product team, one entry per release. What should she do first?
    Output
    Build a page that shows the release notes for our app.
    Show the answer

    Answer D. Nothing in the prompt says who the readers are, who writes the notes or what one entry covers, so the agent filled each gap with the most typical answer, and a commit log is a typical answer. A larger model reading the same eleven words faces the same gaps. A test against commit messages patches one symptom and still leaves the rest of the page unspecified.

  2. 2An agent was asked for dark mode and wrote these criteria before building anything. Each can be checked by a test. What do they lack that more criteria of the same kind cannot supply?
    Output
    1. A toggle in Settings switches the app to a dark theme.
    2. The choice persists after a reload.
    3. All text has a contrast ratio of at least 4.5:1.
    4. Switching themes takes under 100 ms.
    Show the answer

    Answer A. Criteria are precise checks, and these four are precise, but nothing says what the feature is for. If the real need is nurses on a dark ward, the app may need to follow the device's setting and dim images, and no amount of hex codes or CI wiring reveals that. Prose about the person and the moment is what tells you which criteria to write.

  3. 3An agent built version one of a clinic's sign-up flow, then wrote tests by reading its code. The ideal-state document says patients are never emailed at sign-up, because the clinic texts them. Version two follows the document. What happens, and what is the right move?
    TypeScript
    test("sends a welcome email on sign-up", async () => {
      await signUp({ name: "Ada", phone: "555-0100" });
      expect(mailer.sent.length).toBe(1);
    });
    Show the answer

    Answer D. A test written by reading code records what the code happened to do, accidents included. Here the document says no email, so the test defends a mistake against its fix. Putting the email back to turn the suite green lets version one's code overrule the stated intent, and marking it flaky hides a real disagreement.

  4. 4In a chat thread, a team agreed that the checkout must never store card numbers and should keep only the payment provider's token, because storing cards would put them in scope for card-security audits. A month later an agent rebuilds checkout from the project's ideal-state document. What is most likely, and what prevents it?
    Show the answer

    Answer B. The agent works from what it is shown, and the decision lives only in a conversation it never sees. Writing it into the document as a decision with its date and reason means every later build starts from it, and the reason stops someone from undoing it as needless. Reviewing every diff can catch the slip, but it relies on a reviewer remembering the same chat.

  5. 5You are being interviewed by an agent before it builds a tool for tracking equipment loans at a school. Which of its questions is most likely to surface a fact your first written draft left out?
    Show the answer

    Answer A. A question about a real event makes you tell a story, and stories carry the facts you would never think to type, such as loans that cross the summer break or a laptop signed out under a student's name. The other three ask you to pick features or technology, which adds choices without telling the agent anything about your situation.

  6. 6Version one of an internal tool passes all 12 tests the agent wrote for it. The person who asked for the tool looks at it for a minute and says it is wrong. What does the passing suite tell you?
    Show the answer

    Answer C. Tests written from the build are precise about the build: a tight group of shots that can sit far from the bullseye. They say nothing about distance from what the person meant. Criteria taken from written ideal-state prose measure that distance, and more tests of the same kind only make the group tighter.

You understand it when you can

Drill

A baker wanted her regulars to pre-order Saturday bread, and an agent built the site from one line: 'make a pre-order site for my bakery.' Version one has customer accounts, card payments, delivery time slots and no limit on quantities, while she bakes 60 loaves, takes cash at pickup, closes orders on Thursday at 18:00 and does not deliver. Write the ideal-state prose, the constraints and the criteria version one would fail, each with its cheapest check, add one dated decision, and list two questions you would still need to ask her.

Topics

Writer's Blindness
Why a description that reads complete to its author leaves out what only the author knows, and why an agent can act only on the captured text.
Ideal-State Prose Before Criteria
Describing who it is for, the moment they use it and what good looks like in plain paragraphs, then deriving atomic criteria from that prose.
Dictation and Being Interviewed
Talking the idea through, having an agent ask one question at a time and asking it to restate the plan, so facts you would never think to type come out.
One Living Document
Ideal state, constraints, dated decisions and criteria kept together, with two loops writing back into it: intent against the writing, and the writing against the build.
Accuracy Over Precision
Why code says one thing exactly and can still be far from what you meant, and why a first build is disposable when the criteria live in the document.
Check What You Told It First
Tracing each wrong part of a build to the sentence it breaks, or to the sentence that was never written, before blaming the model.

Further reading

Start here

  • The Missing Piece Is Ideal State. Daniel Miessler, 2026. Explainer.

    Twenty minutes on the gap between what is in your head and what the AI knows you want, and on one document that serves as both the build spec and the test harness.

Short reads

  • Writing Is Closer to Thought Than Code. Daniel Miessler, 2026.

    The case for one written document holding ideal state, constraints, decisions and criteria as the source of truth, worked through an owl drawing, a web app and a kitchen remodel.

  • Putting Ideas into Words. Paul Graham, 2022.

    A short argument that writing about something you think you understand shows you the parts you did not, which is why the prose comes before the checklist.

  • Writing is thinking. Nature Reviews Bioengineering, 2025.

    A one-page editorial arguing that writing is where thinking happens, so handing the writing of your intent to a model hands over the thinking too.

Watch

Books

  • Working Backwards: Insights, Stories, and Secrets from Inside Amazon. Colin Bryar and Bill Carr, 2021.

    Describes a company that makes teams write a press release and a narrative memo in full prose before building anything, and why prose exposes fuzzy thinking that slides and bullet lists hide.

  • The Sense of Style: The Thinking Person's Guide to Writing in the 21st Century. Steven Pinker, 2015, Penguin paperback.

    Its chapter on the curse of knowledge explains why authors cannot see the gaps in their own writing, and gives practical ways to find them, including showing a draft to someone who lacks your context.

Primary sources