There’s a fantasy at the center of a lot of product work, and it goes like this: if I write the spec well enough, I won’t have to be there when it’s built. The document will be complete. Engineering will read it, nod, and return the thing I described. The better the writer, the cleaner the handoff.
It’s a comforting fantasy because it makes the spec a finished object — something you can perfect alone, at a desk, and be done with. And it is almost entirely wrong. Not because specs don’t matter; they matter enormously. It’s wrong about what a spec is. A spec is not a description of the thing to be built. It’s the opening position in a negotiation with reality, and reality does not sign off in advance.
Why the wall breaks the spec
The moment your requirements meet implementation, they meet information you did not have when you wrote them. This feature that took one line to describe touches a table that can’t be changed cheaply. That “obviously we’ll just” hides a week of work; this other thing you agonized over turns out to be free. The data you assumed exists is missing a field. The edge case you waved off is actually 30% of traffic.
None of this is a failure of the spec. It’s the spec doing its job — surfacing exactly the questions that could only be answered by trying. The problem is what the handoff model tells you to do with those answers: nothing. The document is finished, the writer has moved on, and now the person holding the new information (an engineer, at 4pm, alone with a decision) either interrupts to renegotiate or quietly guesses. Guess wrong and you get a feature that matches the words in the doc and misses the point of it. Interrupt and you find out the author treated the spec as law instead of a proposal.
Writing a spec you intend to renegotiate
If requirements are a negotiation, the goal of the document changes. You’re no longer trying to specify every outcome. You’re trying to make the intent impossible to lose while leaving the implementation free to move. That’s a different craft.
Say why before what. If the engineer knows the job the feature is doing — the actual thing the user is trying to get done — they can make a hundred small trades in your favor without asking. A spec that lists behaviors without the intent behind them forces a guess every time reality deviates, and reality always deviates.
Rank the requirements out loud. Mark what is load-bearing and what is a first guess. “This threshold is a placeholder; the real requirement is that it feels instant” tells an engineer they may move the number. A flat list of equally-weighted must-haves tells them nothing may move, so when something has to, they’ll cut the wrong thing.
Stay in the room. The most valuable spec conversations happen after building starts, when the cost of each requirement is finally known — because cost is information about value. You cannot make a good priority call about a feature until you know what it costs, and you don’t know what it costs until someone tries to build it. A PM who disappears after the handoff has opted out of the one negotiation that had real numbers in it.
The handoff feels efficient. It just moves all the decisions to the least-informed moment and the least-empowered person. Requirements that survive contact with engineering aren’t the ones written most precisely. They’re the ones whose author was still at the table when the price tags came in.
Liked this? Get the next one in Working Theory.
Going weekly in August (it's in beta now). One genuinely interesting read on building, the brain, and the science most people missed.
Subscribe →