Main idea

A specification describes an intention. A PRD describes a goal, expected rules, scenarios. A mockup describes a desired interface. None of these documents describes what the customer will meet: between them and the release, compromises are made, details are adjusted, edge cases surface, technical constraints force slight changes of behavior, and decisions are taken in the course of a pull request without ever making it back into the original document.

These arbitrations are not accidents to be eliminated: a living product isn't built the way a frozen document is. But they have a consequence for what you have to look at in order to know a product. The specification remains a useful approximation at a given moment; the version in production is the only complete description of what was shipped.

The effect can also be read on tracking tools: tickets drift out of sync just as specifications do, because the arbitrations taken during implementation make it back into neither.

Layer added by "The Backlog Is Not a Dumping Ground: It's a Tool for Action" (2026-06-03).

Layer added by "PM, Developers, and AI: Roles Are Blurring, Responsibilities Remain" (2026-08-01). These arbitrations have a name and an author: they are product decisions, and it is the developers who take them. A complete specification is a fiction — even a good one leaves silent zones: edge cases, error messages, implicit behaviors, security rules, timeouts, invisible priorities, micro-interactions, fallback decisions. So the observation doesn't only describe a gap between the document and production; it names who, in practice, decides what the customer will meet.

Why it matters

This shifts where you go looking for the truth of a feature: in the shipped behavior, not in the ticket that requested it. The gaps aren't compliance errors, they are the very material of product decision.

It also says what you lose by staying upstream: the share of choices that determines the customer's experience was played out after the document, in exchanges that document doesn't record.

Nuances and limits

On some scopes the gap is small and the intention holds: a label change, a parameter, a simple business rule reach production exactly as they were written.

And a product under regulatory constraint partly inverts the rule: there, compliance is demonstrated on the document as much as on the shipped behavior, and the gap becomes a defect in itself.

Open questions

• By what mechanism could an arbitration taken in a pull request make it back to whoever designed the feature, without rebuilding the documentary load you are trying to avoid?