How to write a spec developers don't have to guess at

Every unresolved question in a specification gets resolved eventually. If it isn't resolved by the person who understands the business, it gets resolved by a developer at 4pm on a Thursday, based on a reasonable guess, and nobody finds out until UAT. That's not a discipline problem or a communication problem. It's arithmetic: the code cannot be ambiguous, so the ambiguity has to go somewhere.

The purpose of a spec is not to be complete. It's to decide, on purpose, which questions you're answering up front and which ones you're delegating.

Start with the states, not the screens

Screen-first specs describe the happy path beautifully and say nothing about what happens when a payment half-succeeds or a document is rejected twice. State-first specs start from the object at the centre of the feature — an order, an application, a shift — and list every state it can be in and every transition between them.

Once the states exist on paper, the missing cases become obvious to everyone in the room rather than to a developer three weeks later. In our experience this single change removes more mid-build surprises than any other.

• List the states the entity can occupy, including the unpleasant ones like Failed, Expired, and Under Review
• For each transition, name who or what triggers it and what must be true beforehand
• Mark the transitions that are irreversible, because those are where the expensive bugs live
• Only then draw the screens that expose those transitions to a person

Write acceptance criteria you could argue about

"The report should load quickly" cannot be failed. "The report renders in under two seconds at the 95th percentile with 12 months of data on a mid-range Android device" can be, and that's the point. An acceptance criterion that nobody could ever dispute isn't specifying anything.

The same applies to behaviour. "Users can export their data" leaves format, size limits, permissions, and whether an export includes deleted records entirely undecided. Each of those will be decided by someone. Better it's you.

Say what's out of scope, explicitly

Scope arguments are almost never about what the spec said. They're about what the spec didn't say, and what each side assumed that silence meant. A short 'Not in this release' section costs ten minutes and prevents a large number of uncomfortable conversations.

It also has a useful side effect: writing down what you're deliberately not doing tends to surface the items someone assumed were obviously included. Better to have that conversation while it's a line in a document.

Include the data, not just the shape of it

A field labelled 'Customer reference' tells a developer to build a text input. Three real examples from your existing system tell them it's sometimes 8 characters, sometimes 40, occasionally contains a slash, and is not actually unique. Real sample data is the highest-value, lowest-effort thing you can attach to a spec.

This matters most for anything you're migrating. The shape of legacy data is almost never what the legacy documentation claims, and the discovery usually happens during import, at the worst possible moment.

Name the decision owner

No spec survives the whole build. Questions will come up. The one thing that reliably prevents them turning into delay is a named person who can answer within a day, with the authority to actually decide. Not a committee, not a weekly forum. A name.

“A spec doesn't remove uncertainty from a build. It decides who gets to resolve it, and when.”

A workable structure

1. 1The problem, in the words of the person who has it
2. 2The states and transitions of the central entity
3. 3Acceptance criteria specific enough to fail
4. 4Real sample data, including the messy cases
5. 5What's explicitly out of scope for this release
6. 6The named decision owner and how fast they'll respond

That's usually four to six pages, not forty. Longer specs aren't more precise; they're just harder to check, which is why the ambiguity in them survives to the code.