Main idea

A specification, a PRD, a mockup all get accused of lying the moment someone discovers the gap between what they announce and what the product does. The accusation targets the wrong object: those documents weren't wrong, they stopped filling the function they were written for.

Before it ships, a specification serves the dialogue. It gives the Product Manager, the developers and the business something to argue with: it lets you explore a hypothesis, frame a scope, surface a disagreement before it gets expensive, decide. Its value doesn't lie in being right but in its capacity to provoke objections — a document nobody argued with has failed even if it describes exactly what will be delivered.

Shipping removes that function. The compromises made during development, the edge cases discovered, the trade-offs settled inside a merge request have entered the product without passing back through the document. What it said about behavior is no longer a proposal to discuss: it is a description competing with the one the repository carries, and losing. The artifact doesn't become false, it becomes regenerable — what it states about behavior can be rebuilt from the code, and maintaining it by hand amounts to keeping up a duplicate that drifts.

So the switch is dated, and the date isn't the one it was written on. The same document is legitimate before delivery, illegitimate after, without a single one of its sentences having changed.

Why it matters

This lifts the false dilemma between "we need better specs" and "we should stop writing them". Both camps assume the specification has a single status; it has two, and the common mistake is to extend the first past the moment it expires.

It also redirects the effort: rather than rewriting a document after every delivery so that it stays true, you write it frankly for the conversation it should open, and you accept that it expires the moment the feature ships. The care moves toward the quality of the discussion upstream and toward the capacity to regenerate downstream — two things which, unlike manual updating, don't degrade over time.

Nuances and limits

The switch only concerns the descriptive share. A specification almost always contains, mixed into the same paragraphs, the description of a behavior and the reason it was chosen — the second regenerates from no repository and has to survive the document.

A specification can also be legally binding: an annex to a customer contract, a piece of a regulatory file, a written commitment in a tender. It then keeps an authority that shipping doesn't remove, even when the product departs from it — and the departure is precisely what becomes the subject.

Finally, "shipping" assumes a clean border. A progressive rollout behind a feature flag, a delivery to a few pilot customers, a rollback all spread the moment of the switch instead of marking it.

Open questions

• What, concretely, marks this change of status on the document itself, so that a reader reopening it eight months later knows which of the two regimes they are consulting?
• Is a specification written in the knowledge that it will expire on delivery written differently — shorter on behavior, longer on the alternatives ruled out?