4 min readproductbuildingdelivery
The one-page scope
Every project I've seen go badly went badly in the same place: the gap between what the client meant and what got built. One page closes it — exactly one.
The specification document is one of the great unexamined rituals of software. Thirty pages, written by someone who understands the problem, for someone who understands the technology, read carefully by neither.
I replaced it with one page. Not because I’m allergic to detail — the detail still exists, it just lives in the work rather than in a document nobody rereads. The page exists to close a specific gap: the distance between what the client meant and what someone eventually builds.
That gap is where projects die. Not in the code.
Why one page, exactly
The constraint is the mechanism. Everything below follows from it.
A page forces prioritisation. When there’s room for forty features, nobody chooses. When there’s room for four, the conversation you’ve been avoiding happens in the first week instead of the fourth month.
A page gets read. Actually read, by the person paying, before work starts. A thirty-page document gets skimmed and approved, which is not approval — it’s a signature on something nobody has evaluated.
A page can be held in one head. Both of us can argue about the whole thing at once. You cannot argue with a document you have to page through.
And a page is honest about what it is. A long spec pretends to certainty it doesn’t have: it implies every decision has been made, when most haven’t and several can’t be until we build something. A page admits it’s a starting agreement, not a contract with the future.
What goes on it
Five sections. No more.
The problem, in the client’s words. Not my restatement — theirs, from the intro call, quoted. If they can’t recognise their own problem in the first paragraph, nothing after it matters. This sounds like a formality. It is the single highest-yield line on the page, because it’s the one place a misunderstanding shows up early enough to be cheap.
Who it’s for, specifically. Not “small businesses”. “Accountants with between three and fifteen clients on monthly retainers who currently do this in a spreadsheet.” Specificity here decides the interface, the data model, and half the features. Vagueness here is deferred cost.
What “done” means, testable. The part that gets skipped and shouldn’t. Not “an invoicing module” — “a user can create an invoice, send it, and see whether it was paid, without leaving the app”. Something you can demonstrate on a screen while the client watches. If I can’t write the demonstration, I don’t understand the requirement yet, and I say so.
What’s explicitly not in it. The most valuable section, and the one that makes clients uncomfortable for about ten minutes. Roles and permissions: not in v1. Mobile app: not in v1. The three integrations we discussed: not in v1. Naming them turns silent assumptions into a decision made in daylight. Every disappointment I’ve ever caused was something a client assumed was included and I assumed was obvious.
What it costs and by when. In writing. Before anything starts.
What it deliberately leaves out
No technology choices. The client doesn’t care and shouldn’t have to; if the stack matters to them, it belongs in a separate conversation about ownership, not in the scope.
No screen designs. A wireframe on the scope page freezes a decision that should stay liquid for another two weeks, and clients treat pictures as promises in a way they never treat sentences.
No timeline in weeks per feature. It’s fiction, it’s read as commitment, and it converts every learning into a broken promise. One date for the whole thing, and weekly demos so the date is never a surprise.
No effort estimates. Whatever the client is buying, it isn’t hours. I’ve written separately about what agents changed about estimation — but the shorter version is that the number is a negotiating token, not a measurement, and both sides know it.
The part that makes it work
The client writes the last line.
After we’ve talked it through and I’ve drafted it, they add one sentence in their own words: what they’ll be able to do when this is finished that they can’t do today.
It sounds like a nicety. It’s a test. If the sentence they write doesn’t match the page above it, we’ve just found the misunderstanding — for the price of a sentence, in week one, instead of at the demo in month three.
It has caught something roughly a third of the time. Not because anyone was careless: because “what we’re building” and “what I’ll be able to do” are genuinely different sentences, and the second is the one that matters.
What happens when it’s wrong
It is wrong, sometimes. We build something and the world disagrees.
Then we change the page, in front of each other, and both of us can see exactly what changed and what it costs. The page becomes the record of decisions rather than the prediction that failed.
That’s the real argument for one page over thirty. Not that it’s faster to write. That it’s cheap enough to be honest about.
If you’re about to start something and nobody has written this page yet, that’s what the first thirty minutes are for.