The spec that survives contact with eng.

There is a line every officer learns and every builder relearns: no plan survives first contact with the enemy. The Prussian who wrote it, Helmuth von Moltke, was not being cynical about planning — he planned obsessively. His point was subtler. You plan not to script the battle but to be ready for the battle, because the moment it starts, the specifics you imagined will be wrong and you’ll have to improvise from something. The plan’s job is to make the improvising good.

A product spec is the same kind of object, and it dies the same kind of death. You write it in a quiet room, imagining a system that doesn’t exist yet, and every sentence is secretly a prediction. Then engineering starts building, and reality begins filing its objections: the API can’t return that field, the edge case you waved past is actually the common case, the “simple” toggle touches four services. This is not a failure of the spec. It’s the spec doing what specs do — meeting the world. The only real question is whether, when that happens, what you wrote bends or shatters.

Why most specs shatter

The spec that shatters is the one written entirely at the surface. It specifies the exact screens, the exact copy, the exact order of the happy path — and almost nothing about why. It reads like a blueprint, and blueprints are brittle by design: change one measurement and the drawing is simply wrong.

So when an engineer hits a wall — “we can’t load all of it at once, it’ll time out” — the surface-level spec has no answer. Every detail in it assumed the thing that turned out to be impossible. Worse, the spec now becomes a source of false conflict: someone says “but the spec says paginate on scroll,” someone else says “the spec is wrong,” and a meeting gets scheduled to relitigate a decision that was never really the point. The document that was supposed to align everyone is now the thing they’re arguing about.

What survives is the intent, not the pixels

Watch which parts of a spec make it through contact intact, and a pattern shows up. It’s never the specific layout. It’s the invariants — the handful of things that must always be true or must never happen — and the reasons behind the decisions. Those survive because they don’t depend on the implementation being any particular way. “A user must never see another user’s data” holds no matter how you paginate. “We’re optimizing for the second session, not the first” tells an engineer how to make a hundred small calls you never anticipated.

So the durable spec is written in layers, and it says out loud which layer each thing lives in:

• Invariants — what must be true or must never happen, regardless of how it’s built. These are load-bearing and rarely change. Guard them.
• Decisions, with their reasons — the calls you’ve made and why, so that when the situation shifts, an engineer can re-derive the right call instead of guessing or waiting for you.
• Details — the specific screens, copy, and flows. Genuinely useful for shared imagination, and genuinely disposable. Mark them as examples, not commandments.

The test that tells you the spec will hold

Here’s the cheap way to check a spec before it ever reaches an engineer. Imagine the most likely objection — “we can’t do it the way you wrote it” — and ask: can they figure out what to do instead from the document alone?

If the answer is yes, it’s because you told them what mattered and why, and they can re-derive a good call from that. You’ve already delegated the judgment to the moment it’s needed. If the answer is no — if the only way forward is to book time with you — then your spec specified the what and hid the why, and it was always going to become a bottleneck the first time reality pushed back.

This is why the layer of abstraction is the whole game. Specify too high and you’ve written a vision statement nobody can build from. Specify too low and you’ve written a blueprint that the first real constraint turns into a liability. The spec that survives lives in between, on purpose: firm about the handful of things that must be true, clear about the reasoning, and relaxed — explicitly, out loud — about the details that were only ever one way of getting there.

You are not writing instructions for a machine that will execute them. You are writing for a smart person who is about to learn things you don’t know yet, and who will do their best work if you’ve told them what you’re actually trying to protect. Plan so the improvising is good.

The idea, to trace: the aphorism is Helmuth von Moltke the Elder’s (“no plan of operations extends with any certainty beyond the first encounter with the main hostile force”); the engineering habit it maps onto is the old discipline of specifying invariants and intent over implementation — describe what must hold, not how to make it hold.