Write your first specification

The first draft is usually longer than you want, and it is usually the request’s fault, not the model’s. This page is about making a request that produces a specification you can review in one sitting.

Start with the outcome, not the mechanism

A good request states what should be true when you are done. It does not describe how to get there.

Weak: "Add an endpoint that checks a customer’s subscription and cancels it if they’re over the limit."

Stronger: "When a customer is over their plan limit at the end of the billing month, their subscription is cancelled and they receive an email explaining why."

The second one is still missing detail, but it is missing checkable detail, and the difference matters: the draft you get back is about a rule, not about an implementation, which means you can review it as a rule.

The three things that most often make a draft long

Unstated defaults. Every system has defaults: rounding mode, currency, timezone, what happens when a field is absent, whether an empty list is an error. The model has to pick something. Each pick becomes a clause you then have to review.

If you care about the default, say it. If you do not care, say that too — "use whatever is standard for this codebase" is a legitimate instruction, and it is much cheaper to review one clause saying "rounding follows the ledger convention" than to review a rounding clause and a currency clause and a timezone clause.

Unstated scope. "Handle refunds" can mean one endpoint, five endpoints, a service, or a subsystem. Say which. "Handle refunds for a single order" is a complete scope in four words.

Unstated failure behaviour. The most expensive omission. What happens when the refund provider times out? When the order is already refunded? When the amount is zero? Failure paths are where the specification gets long, and long specifications are exactly what you are trying to avoid — so decide the failure behaviour up front, in one sentence, rather than discovering it clause by clause.

Give the model something to be consistent with

If your repository already contains specifications, they are the strongest possible input. The draft will follow their conventions: phrasing, tag structure, whether scenarios use Background, how parameterised examples are written.

If it does not, seed it. Write one feature file by hand, in the style you want, and let the draft follow. This is the single highest-leverage thing you can do to make later reviews cheap — the review cost is dominated by inconsistency, and inconsistency is far cheaper to prevent than to fix.

What a good first request looks like

A customer can request a refund for a settled order. If the order was settled less than 30 days ago, the full amount is refunded and the order becomes "refunded". If it was settled more than 30 days ago, the request is refused with code REFUND_WINDOW_CLOSED and the order is unchanged. Refunds are issued in the order currency. If the payment provider fails, the order stays "settled" and the customer sees a retryable error.

That is one paragraph, and it contains four checkable outcomes, one boundary condition, one currency rule, and one failure behaviour. The resulting draft should be short, and every clause in it should be something you can answer yes or no to without hesitating.

What to do with the draft

Do not read it top to bottom looking for problems. Read it clause by clause, and for each one ask a single question:

If this clause were false, would I be upset?

If yes, it is a clause worth your attention. If no, approve it and move on. Most clauses in a good draft pass that test, and the review should feel like a sweep rather than an interrogation.

For the mechanics of doing that, see review and approve.

Next