What a good specification settles

Nothing here is specific to one platform. Every project writes specifications, and the ones that hold up tend to settle the same few things.

Why this matters

A specification earns its place by settling decisions. The ones that hold up under a build are the ones that answered the questions nobody had thought to ask yet — what happens when a service is down, who decides when the document is unclear, where the work stops. Those decisions get made either way. The only question is whether they are made early, by the people they belong to, or late, by whoever is free.

The decision — Treat the specification as the place where decisions get closed, not the place where the feature gets described. Spend fewer words on the happy path and more on the edges.

What it gives you — The business decides the things the business should decide, at the point where deciding is cheap. Rework drops, because fewer choices are made by the wrong person under pressure.

The risk it removes — A developer choosing, at five o'clock on a Friday, what a customer sees when a payment fails.

In one sentence: a good specification is not longer than a bad one. It spends its words differently.

The problem

Ask where rework comes from and most people say the code. It rarely does. It usually comes from a decision that was never settled, discovered at the point where it can no longer be avoided.

Here is the shape of it. A specification describes a new feature. It explains what the customer sees, which buttons exist, and what happens when they are pressed. It is detailed, it is reviewed, it is signed off. Then the build starts, and within a week someone asks: what should happen if the payment provider does not answer?

Nobody knows. The document does not say. So an answer gets made — quickly, by one person, without the people whose decision it was. It is often a reasonable answer. It is just not anybody's decision.

Not because anyone was careless. The specification was read by people who each assumed the question had been settled somewhere else — earlier in the document, in a previous conversation, by someone closer to it. That assumption is what makes the failure silent. Nobody notices the question that was never asked.

That is the pattern, and it repeats. Each unsettled question becomes a small unowned decision. Together they become the rework.

What a specification is for

The useful reframe is this: a specification's job is not to describe the feature. It is to close the decisions the build would otherwise have to guess at.

Those are different jobs, and they pull in different directions. Describing a feature means writing about the part everyone can already picture. Closing decisions means writing about the parts nobody has thought about yet — which is harder, less satisfying, and much more valuable.

Most specifications do the first job well. The second is the one that needs deliberate effort, because nothing about the act of describing a feature leads you to it.

Where the words go

Count the length of a typical specification and roughly eighty per cent of it describes the happy path: the customer does the expected thing, every system responds, everyone is pleased.

That is the part everyone already agrees on. It causes almost no rework, because there was never any disagreement about it.

The remaining twenty per cent — what happens when things go wrong, who decides, where it stops — is where nearly all the rework comes from. It gets the least attention because it is the hardest part to write, and the part where the answers are not yet obvious to anyone.

So the fix is not a longer document. It is the same length, spent differently.

The decisions worth settling

These are the ones that repay settling early. None of them is technical. Each belongs to the business — and each one, left open, reaches the build later as a technical surprise.

What the customer sees when something is broken. Settle this and the business owns the words a customer meets at the worst possible moment. A payment provider times out. A loyalty service is down. A delivery partner cannot give a date. What should the customer see? It is a question about trust, and about whether you would rather lose the sale or risk the order — which makes it a business decision, not a technical one. Left open, it is first asked during a production defect, and answered by whoever is unblocking the ticket.

The actual words. Settle the message text and a customer reads something that was chosen. Left open, somebody invents it late, and the invented words are the ones that reach real people. "An error occurred" is a sentence no business ever chose, and it is on more sites than anyone would like.

How many, and what happens on launch day. A number here lets the design be sized before it is built. A feature used two hundred times a day and a feature used two hundred thousand times a day are not the same feature, even when the screens are identical. Without the number, sizing happens after the fact — which is the normal way a launch becomes an incident.

Which markets, which brands. Settled in week one, a difference between markets is a paragraph. The same difference found in week six is a redesign, because the shape of the solution is already fixed. It is among the cheapest questions to ask early and the most expensive to answer late.

Where it stops. A line saying what is out of scope is what lets someone say no later. Scope creep is rarely a fight; it is a series of small reasonable additions, none of which anyone can refuse, because there is no line to point at. The sentence "this release does not include X" is worth more than three pages describing X.

Who decides when the document is unclear. This is the single most useful sentence a specification can carry. Ambiguity is not the problem — every document has some. Ambiguity with nobody's name against it is the problem, because it gets resolved silently by whoever reaches it first.

Whether it can be switched off. Settled before the build, this is a design constraint and costs almost nothing. Left until an incident, it is a crisis with an audience. Can this be turned off if it goes wrong, and who has the authority to say so?

How anyone will know it works. Criteria someone could check, and could disagree about, turn "done" into something observable. "The feature works" is not testable. Neither is a list of acceptance criteria that restates the requirement in slightly different words — a very common and easily missed failure, because the list looks complete.

How anyone will know it was worth doing. A number, a behaviour, or a complaint that stops arriving. Settled, it tells you whether to do more of this. Left open, every feature is a success, which makes the word meaningless.

What data is collected, and on what basis. Whether the business is asking for consent, and for what, is a business decision with legal weight. Settled early it is a design input. Left open it arrives as a technical surprise, usually late, usually when a consent banner turns out to be needed.

What is expected of accessibility. Decided here, or not at all. It is far cheaper as a line in a specification than as a remediation programme, and in some markets it is a legal obligation rather than a preference.

The limit that matters most

None of this is an argument for writing more.

A specification cannot answer everything up front, and pretending otherwise produces filler. Some things genuinely are not knowable when the document is written. Forcing an answer produces a confident sentence that later has to be unpicked, which is worse than an honest gap. The honest move is to name the unknown, name who will resolve it, and say roughly when. "We do not yet know, and the trading team will decide before build starts" is a complete and useful answer. "TBC" on its own is not.

Over-specifying has its own failure mode. A forty-page document nobody reads protects nobody. It gets approved on trust and then ignored, which is worse than a short document people actually use, because everyone believes the questions were answered. Size the specification to the change: a small adjustment and a new payment integration should not get the same treatment.

And this is not a request for more work from product people. It is a redistribution. Fewer words on the screens everyone already understands. More on the edges nobody has thought about. Done properly, the document gets shorter and the arguments happen earlier, which is where arguments are cheap.

Options considered

Option	Decision	Reasoning
Spend the words on the edges, and name an owner for every open question	Chosen	Costs nothing in length. Moves the difficult conversations to the point where they are cheap, and gives every unknown a person rather than a label. Accepts that some sections will be uncomfortable to write.
Write longer, more detailed specifications	Rejected	Treats the problem as insufficient effort. Produces documents nobody finishes reading, and the gaps remain — they are just harder to find.
Leave the gaps and settle them during the build	Rejected	This is the current state in most places, so it is worth naming plainly. The questions do get answered. They are answered late, by whoever is available, without the people whose decisions they are.
A long template everyone must complete before work starts	Rejected	Front-loads the whole document at the point of least knowledge. Forces invented answers into sections that could honestly have said "not yet", and invented answers are worse than gaps because they look settled.
Rely on workshops and conversation instead of a document	Rejected	The conversation is genuinely valuable and should still happen. But six weeks later nobody agrees on what was decided, and an unwritten decision is not a decision — it is a shared impression.

The rejected options fail for the same underlying reason. Each one leaves the question of who decides unanswered, so the deciding happens anyway, somewhere nobody is watching.

What I would watch

Specifications that describe the screen instead of the decision. A detailed description of a page tells you what it looks like, not what should happen when the thing behind it fails. The second is the part that costs money.
"TBC" that nobody owns. A named unknown is a plan. An unnamed one is a defect with a long fuse. Every open item needs a person, not a label.
Acceptance criteria that restate the requirement. If the criterion reads like the requirement with the words rearranged, nothing has been made checkable. Ask whether two people could look at the result and disagree.
A specification that is approved but not read. Approval is not comprehension, and long documents get approved on trust. If nobody can summarise it back, the sign-off means very little.
Ambiguity being resolved silently. The most expensive thing in this piece. When a developer makes a judgement call because the document was quiet, the decision leaves no trace and nobody knows it was made. Watch for decisions that only appear in the code.

What it gives you

The people who should make a decision make it, at the point where changing their mind is cheap.
Rework falls, because fewer choices are made late by people who were only trying to unblock themselves.
The words a customer reads in a bad moment were chosen by the business, not improvised at the end of a sprint.
Scope has a defence, because something written down says where it stops.
The unknowns are visible and owned, instead of being discovered one at a time during the build.

None of this needs a new process or a new tool. It needs the same document, with its attention moved to the parts that are difficult to write.

Related: Using AI as a consistency engine for architecture work makes the same argument one step later in the process, for the technical design rather than the functional specification: fix the structure, keep the judgement with a person.