How to write a spec a developer can actually quote

You get a vague number back because your brief describes an outcome, and a quote is priced on decisions. Between “a portal where our clients can track their orders” and something anyone can put a fixed figure against sit six answers: who the users are and what each one is allowed to do, the workflows in the order they happen, what the system does when a step fails, which external systems are involved and who holds the credentials, what data you hold and where it is allowed to live, and what you have decided not to build for version one. Leave any of those out and the vendor fills the gap themselves.

This is written from our side of the table: what follows is what happens to your document after you send it, not advice about formatting. The difference between a wish list and a spec has nothing to do with length. A wish list defers decisions. A spec makes them, and a made decision is the only thing anyone can price.

What actually happens to a gap in your brief

Estimating is decomposition plus assumption. The work gets broken into pieces someone has built before, each piece gets a number, and every place your document is silent gets an assumption written next to it. The assumption is not a guess at what you meant. It is a position sized to survive being wrong, because whoever wrote it has to live inside the total afterwards.

There are only two ways to handle that, and both cost you. Price the ambiguity wide and you pay for the vendor’s ignorance in a buffer that never gets refunded when the risk fails to land. Price it narrow and the proposal looks excellent right up to the point where every conversation after kickoff becomes a change order. We took the mechanics of that trade apart in fixed price versus time and materials, and the short version is that contingency is proportional to what the estimator does not know.

The consequence buyers miss is what this does to comparison. Send a loose brief to four firms and the four numbers back are not four prices for the same thing. They are four guesses about what you meant, each wrapped in a different amount of protection. You cannot choose between them, because the variable that moved is the one nobody wrote down.

Named users and roles, not “users”

Write down every kind of person who touches the system and one sentence about what each may see and change. Three roles is common. Customer, staff member, administrator. What matters is the second half: can a staff member see every customer’s records or only the ones assigned to them, can an administrator act on a customer’s behalf, can a customer invite a colleague, and does that colleague then see the first person’s history.

Absent that, the assumption is one role and a login. It is the cheapest defensible reading, and it is wrong more often than not. The cost when it turns out wrong is structural rather than cosmetic. Permissions live in the data model, not in the interface: a role added after the schema exists means a new relationship, a filter on every query that touches the affected tables, a migration over existing rows, and a test for each combination of role and record. That is why our own brief tool weights users and roles at eight points out of a hundred, above platforms and above budget.

One line saves most of the argument: say whether people belong to organisations that must not see each other’s data. That single sentence decides an architecture, which is the subject of shared database or database per tenant, and it is nearly free to answer before anyone writes code.

The workflows, in order, with a trigger and an owner

A feature list is nouns. Dashboard, notifications, reporting, profile. Nouns are unpriceable because each one is a container for between a day and a quarter of work. A workflow is verbs in sequence, and it reads like this: a customer submits a request, it lands in a queue, a coordinator assigns it, the assignee uploads a document, a manager approves it, the customer is notified, the record closes.

Seven steps, each with an actor and a trigger. Every step is now a screen or a job, and the transitions between them are the statuses your database will hold. An estimator can count that. They cannot count “approvals”.

Do three to five of these and stop. If you cannot write the one workflow that has to work on launch day, the problem is not the document, and no amount of further writing will fix it. Our tool weights the must-have list at thirteen points, the highest of any field it scores, because everything else on a quote adjusts a total that this list sets.

The unhappy path is most of the software

Briefs describe the day everything works. Most of the engineering is the other days, and this is the single largest source of the gap between the number you were given and the number you end up paying.

For each workflow above, answer what happens when the step fails. The card is declined. The upload is a 40 MB scan rather than the tidy PDF everyone pictured. The approver left the company two weeks ago and the request is still sitting with them. Someone double-clicks submit and you now have two records or, worse, two charges. The external system is down for ninety minutes and eleven orders arrived during it.

Left unanswered, the assumption is that failures show the user an error message and someone deals with it by hand. What you often need instead is a retry policy, an idempotency key so a repeated request cannot double-charge, a queue that survives a restart, and a reconciliation view for a human. That is real work. It is also work nobody argues about once it is written down, which is exactly why writing it down moves your price toward the honest end rather than the padded one. We wrote up two of the common cases in what breaks with Stripe webhooks in production and running background jobs in Next.js.

A useful test on your own draft: count the sentences containing the word “if”. If there are none, you have written a demo script.

Which integrations, and whose credentials

Name the system, the edition, the direction of travel, what triggers the exchange, and roughly how much moves. “Sync with our CRM” is a sentence with a factor of ten inside it. “Push a contact and a deal to HubSpot when a quote is accepted, roughly two hundred a month” is a task.

Then answer the question almost every brief skips: who holds the account. An integration is only priceable once someone has seen the thing they are integrating with. Sandbox access, an API key, and permission to create test records in your instance change an estimate from a risk line into a work line. Without them the assumption is a documented REST API with a working sandbox and an administrator who answers within a day. When it breaks, it breaks as weeks of waiting rather than as a technical problem, and waiting is what a fixed schedule cannot absorb. The full cost breakdown sits in what a third-party integration really costs.

The same discipline applies to the systems you assume are free. Authentication is the usual one: “users log in” and “single sign-on with your customers’ identity providers, and access removed when their HR system deactivates someone” are the same sentence in a brief and different quarters of work, which is the argument in build versus buy for authentication.

What data you hold, and where it is allowed to live

Four short answers. Which categories of data the system holds, whether anything is regulated, whether it must stay in a particular country, and how long you have to keep it. Personal data, card details, health records and information about people under eighteen each pull in a different set of obligations, and they pull them in at the architecture layer rather than at the end.

Silence here is read as ordinary business data, hosted wherever the team normally hosts, with no residency constraint and no retention rule. When that turns out to be wrong it is one of the few discoveries that can force a hosting decision to be made twice, and it tends to surface late, because it usually arrives with a security questionnaire from your first serious customer rather than from anyone on the project.

Say also whether anyone needs to prove after the fact who changed a record and when. A row-level audit trail is not expensive if it is designed in and is genuinely awkward to retrofit, since it needs every write path to go through it.

What is explicitly out of scope for version one

This is the highest-leverage paragraph in any brief and the one almost nobody writes. Exclusions are how you buy a smaller number on purpose rather than by accident.

Absence of a request is not read as a decision. It is read as an open question, and open questions are priced. Write the list plainly: no mobile applications in version one, the web application is responsive and that is the whole platform story; no single sign-on, email and password with a reset flow; no multi-currency; no public API; reporting is a CSV export rather than a dashboard; one language.

Then do the thing that makes an exclusion useful rather than defensive, and say what happens if you want it after all. “Excluded for version one, quoted as a change order if required” tells a vendor you have thought about the sequence rather than forgotten the feature, and it stops the exclusion reading as a trap. The shape of a good exclusion clause is set out in the fixed-price piece linked above.

The six gaps and what gets assumed instead

Two lines that cost nothing and change the answer

Expected scale, and who signs. Scale rarely changes a price at small numbers and always changes it at large ones, so a sentence saying you expect two hundred users and forty thousand records in year one tells a vendor which architecture is honest. Guessing high is what produces a quote for infrastructure you will not need for four years.

And name the person who can say yes. How many people are in the room predicts how long decisions take far more reliably than the price does.

The honest problem with everything above

A good spec is not free. It is a week or three of the attention of the people who understand your business best, which is the same attention currently keeping the business running. Nobody bills you for it, so it never appears in a budget, and it is nonetheless the most expensive input on the project.

Worse, some of that effort is unrecoverable. Written in the dark, a long specification for genuinely novel work is confident about things nobody can know yet, in a form that is hard to argue with later. We have seen sixty-page documents that specified the wrong product beautifully, and every hour spent making them internally consistent made them harder to abandon.

So the rule we actually hold: specify heavily where the work is well-understood and the failure modes are known, and refuse to specify where the answer depends on something you have not tested. If the honest state of your project is that you do not yet know which workflow matters, a paid, bounded scoping engagement beats a document written alone. Our piece on what an MVP actually costs is about the same trap from the budgeting side.

There is also a whole class of project where none of this applies. A brochure site does not need a role matrix or an unhappy-path analysis. It needs a sitemap, the page count, who writes the copy, and whether the content is ready. Bringing a requirements document to that conversation wastes your week and buys you nothing.

What it costs to buy the spec instead of writing it

Our published rate card, not a figure invented for this article. A scoping sprint is $3,500 for one week and is credited in full against a build that starts within thirty days, which makes it free if you go ahead with us and a cheap way to leave with a document if you do not. Our minimum for a build is $7,500. A marketing site is $7,500 to $15,000 over two to four weeks for up to eight pages, and is the case described in the paragraph above. Most projects we take land between $18,000 and $45,000. Those are estimates in US dollars, not quotations; the quote that follows scoping is fixed in writing before kickoff.

The output of that week is the same six things this article asks for, written down in a form other vendors can quote from. That is the test to apply to anyone selling discovery: if what you receive is only usable by the firm that produced it, you bought a sales document rather than a specification. Buy it elsewhere or write it yourself over a fortnight if you prefer. The artefacts are the point.

What a good brief changes on our side is narrow and worth stating precisely. It does not make the work cheaper. It makes the range around the number smaller, it moves the contingency line down because there is less unknown to protect against, and it makes the quote you receive comparable to the one next to it. Those are three different benefits and only the second one is money.

The compressed version

Roles with permissions. Three to five workflows as ordered steps with an actor and a trigger. For each one, what happens when it fails. Each external system named, with its direction, its volume and the person who holds the credentials. The data categories, the residency rule and the retention period. An explicit out-of-scope list for version one, with a note on what happens if you change your mind. Then expected scale and the name of whoever signs. Two pages is plenty; ten is usually a sign that features got described where decisions should have been made.

If you want the structure without the blank page, our project brief generator asks these questions in order, scores what you have against fourteen weighted fields, and produces a document you can send to any firm, including ones that are not us. It runs in your browser, and nothing you type is sent anywhere.

And if you reach the end and find the gaps are real, that is a useful result rather than a failure. Send us the half-finished version and tell us which parts you cannot answer yet. The answer may be a scoping week first, from us or from anyone, rather than four vendors guessing at the same six things in four directions. What we sell, and how we scope it, is set out across our services.