Product requirements

A specification exists to prevent expensive rediscovery — of decisions already made, of scope already agreed, and of the edge cases that are found either now on a page or later in production.

Lead with the problem and the number, not the solution

Open with who has the problem, what it costs them today, and what you expect to change if this ships — expressed as a measure with a target and a date. A document that starts with a solution invites the team to optimize the wrong thing and gives you no way to tell afterward whether it worked.

Decide the success measure before building, not at launch. A number chosen afterward is chosen to be met.

State scope by exclusion

Everyone reads what is in scope and assumes the rest is coming. An explicit "not in this" list is the cheapest thing in the document and prevents most scope arguments — including the ones that arrive as clarifications rather than as requests.

Say what is deferred versus what is rejected. Those are different, and conflating them means the rejected thing comes back.

Describe behavior, not implementation

Write what the user experiences and what the system guarantees. Leave the how to the people who will own it — a specification that dictates implementation gets a worse implementation and blurs who is accountable for it.

The states nobody writes down are where the rework comes from. Empty, loading, error, partial, permission-denied, offline, and the first-run case with no data. Also: what happens to records that already exist, what happens at the limits, and what happens when two people do it at once. Most "that wasn't what I meant" traces back to one of these.

Make acceptance criteria testable

Each one should be a statement someone can evaluate as true or false without asking you. "Fast" and "intuitive" are not criteria; a response-time budget and a task someone completes unaided are.

If a criterion cannot be tested, it is either a principle — say so and move it — or it is not finished being thought about.

Name the open questions and who owns them

Every specification has unknowns. Listing them, with an owner and a date needed by, is what separates a document that is honestly incomplete from one that is quietly wrong. Buried uncertainty gets resolved by whoever hits it first, usually at the least convenient moment and without anyone noticing a decision was made.

Keep it alive, or state that it is frozen

A specification that diverges from what was built becomes a trap for the next person. Either update it as decisions change, or mark it as-of-a-date and point at wherever the truth now lives. The worst outcome is a document that looks current and is not.

Never

• Open with a solution and leave the problem implied.
• Ship a specification with no explicit out-of-scope list.
• Write an acceptance criterion that requires asking you whether it passed.
• Leave an unresolved question inside the body where it reads as a decision.