Formats›A specification, in nine lines

A specification, in nine lines

A reusable format. Copy it, fill it, use it again — for a class exercise, for a capstone, for anything you are going to hand to somebody or something else to build. Nothing in it is specific to one course.

Download specification-format.md The file you fill in. Plain text — open it in any editor, or hand it to an agent.

What this is for

A specification is a description of a thing that does not exist yet, in your own words, complete enough that somebody or something else could build it from it.

Until recently that was a document nobody read. It is now the input: hand these nine lines to a coding agent and what comes back is an attempt at the thing. Which means the description is the source, and the code is what came out of the build — the same relation a markdown file has to the PDF made from it. Nobody edits the PDF.

🔵 This is a claim of mine and not a settled finding. What I think has happened is that the scarce skill moved from writing the instruction to saying what you want. What would show me wrong: agents producing good work from thin descriptions, consistently, without the person having thought it through.

Keep it to nine lines. A source you cannot hold in your head is not a source — at four pages nobody keeps it true, and an untrue source is worse than none, because the code at least admits what it does. One line each. Where a line will not come, you have not decided that thing yet, and that is the finding rather than a failure.

Everything about how it gets built stays out. No language, no library, no hardware, no file layout. Those belong to whoever builds it.

The format

THE THING       one sentence, no adjectives

STATE           what it holds from one moment to the next
CHANGE          what happens each time it runs
DECISION        the count, the threshold, what it concludes
EDGES           first run · nothing there · a wrong reading · failure
FIXED OR FREE   what is baked in, what a stranger can change, and where that lives
ENOUGH          what somebody who did not build it does, to see that it works
HOW LONG        how long it can be built in, and what you drop first

NOT THIS        what it will not know, and cannot be made to say

A name above, a refusal below, and seven lines between.

What each line is asking

THE THING. What you would call it to somebody outside the project, in one sentence. Not how it works, and no adjectives — smart, seamless and intuitive are the words that survive when the thinking has not.

STATE. What it holds between one moment and the next. What it knows if you stop it and ask. Say what it does not keep as well; that is usually the more interesting half.

CHANGE. What is different after one pass, one frame, one tick, one visit. How often that happens.

DECISION. The count, the number it is compared against, and what the comparison concludes. If your thing decides anything at all, this line has three parts and most first drafts have one.

EDGES. Four situations, always the same four: the first run before anything has happened, the empty case, a reading that is wrong, and outright failure. The interesting answer is usually that two of them are being treated as one — say which two, and say that you meant it.

FIXED OR FREE. What somebody other than you could change without rebuilding it, and where that value lives. Everything else is baked in, and saying so is a decision rather than an omission.

ENOUGH. A person doing something, not a property. It works reliably is not an answer. A stranger unplugs it, waits two minutes and watches is. This is what would make you wrong asked about an object.

HOW LONG. How long it can be built in — the hours you actually have, not the hours it would take if you had them — and what you drop first if it will not fit. The number comes from your week, not from the thing. A specification you cannot build in the time available is not a plan; it is a wish with structure.

NOT THIS. What it will not know, and could not be made to say. Not a disclaimer and not a limitations section — the thing it could have known and does not.

🔵 A claim of mine, and the one I would most like argued with: a refusal survives only if something in the built thing makes the other path impossible. Written down it is an intention, and intentions lose to defaults. It must never read that file is a wish; it runs with no permission to open that file is a mechanism. What would show me wrong: an object whose refusal lives only in its documentation, handled by other people for a year, and still intact.

A worked one

THE THING       A lamp that goes amber when the sensor stops reporting.

STATE           How long ago the file was written. No history.
CHANGE          Every ten seconds, take that age again.
DECISION        Amber above 120 seconds, white below. One count, one threshold.
EDGES           No file yet: amber. Clock jumps back: fresh.
                File empty: fresh — it never looks inside.
FIXED OR FREE   Free: the 120, in a file beside it. Fixed: the colours, the ten
                seconds, and that it never opens the reading.
ENOUGH          A stranger unplugs the sensor, waits two minutes, sees amber,
                plugs it back in, sees it come back.
HOW LONG        Three hours, which is what I have. Enough for the lamp and
                the file. A real lamp rather than a line on a screen would
                need another three, and that is the half I drop.

NOT THIS        Whether anybody is in the room. It knows the sensor is writing,
                never what it wrote.

Note what it does not say: not the language, not the board, not what the lamp is made of, not how the reading gets into that file. And note the decision hiding in EDGES — no file at all and a file two hours old take the same branch, so unknown and stale are one state here. That is a choice, and on a different day it would be a different one.

The last line took longer than the other eight together. It is also the only one anybody would argue with.

How to use it

  1. Write the nine lines alone, on paper, before any code exists. Leave blank whatever will not come.
  2. Hand it to somebody else and ask them for three questions about the thing you described — questions they genuinely cannot answer from what is written. Not suggestions.
  3. Answer the three in writing, and put each answer back under the line it belongs to. The specification grows out of the conversation rather than out of a second sitting.
  4. Cost it. Write HOW LONG against the hours you actually have, and say what you drop.
  5. Hand the nine lines to a coding agent. Read what comes back for the decisions it took that you had not — a log it started keeping, a default it chose, a retry it added. That list is the finding. It is not a list of the agent's mistakes; it is the exact list of things you had not decided, printed by something that had to decide them.
  6. Then delete what it wrote and build it again from the same nine lines. If the second thing is the same as the first, your specification was the source. If it is not, something was living in the code that was never written down — and you have just found out what, by losing it.

⚠️ Do step 6 on a copy.

Three ways a specification fails

Underdetermined. It does not say, so something else decides. This is the common one and it is invisible until you read the code back. And the gaps do not fill with nothing — they fill with whatever is ordinary, and what is ordinary is keeping things: log the event, store the timestamp, keep the address you needed for a second. Knowing arrives by itself. Not knowing has to be written down.

Over-determined. It fixes what did not need fixing. Sixty frames a second, blue, 400 pixels — decisions taken before there was a reason for any of them, which then survive because nobody remembers they were arbitrary. A long specification is usually full of these.

Unfalsifiable. It should feel smooth. It should be intuitive. There is no way to tell whether it was met, so it is never met and never not met. This is the one design education teaches you to write. Watch for it in your own.

Prayas Abhinav. Licensed CC BY 4.0 — copy it, change it, build on it, including commercially. Say where it came from, and if you changed it.

Take a copy: specification-format.md. Yours to alter.