The big-bang spec

A big-bang spec is a complete specification authored up front — the whole system pinned down on paper before any code is written and before any feedback is received. Every screen, every rule, every edge case, decided in one pass, then handed to the build as a finished document.

Hold it against a thin spec: only enough definition for one slice — one behaviour, the invariants it must hold, and the checks that prove it — written so the slice can ship and be answered this week. The thin spec is small and current. The big-bang spec is large and, the moment it is declared done, already ageing.

The distinction matters because the lesson is precise: this is not an argument against specifying. A definition of what to build, and of how its correctness is judged, is the contract every rung needs. The failure is in two properties of the big-bang form — its bigness (it tries to pin down everything at once) and its timing (it is written before any contact with reality). Specify; specify thinly, and late enough to be answered.

A big-bang spec fails for four reasons, and each is a property of writing too much too early, not of writing a definition at all. Named plainly, they are: it is never finished; it drifts; it returns no feedback until the end; and it discovers its risk last.

Completeness is unbounded. There is always one more edge case, one more interaction, one more rule the document could pin down — so a spec that aims to be complete keeps expanding. Worse, it expands against a moving target: while the document grows toward a frozen picture of the system, the requirements it describes keep changing underneath it. The spec is chasing a destination that walks away as it is written.

A document written before contact with reality diverges from that reality — and from the code that eventually meets it. Nothing in a static specification re-checks itself against what is actually built, so the two separate the instant the first line of code disagrees with a paragraph. The spec stops describing the system and starts describing a system that was imagined. A living specification — one whose examples are executed as checks — cannot drift, because a divergence fails the check; a prose document carries no such alarm.

This is the cost of delay. Every claim in a big-bang spec — every assumption about what users want, what the data looks like, how a rule should behave — stays unvalidated until the one big release. The single moment that could confirm or refute the plan is pushed to the latest possible point, so the plan is steered for the entire build by guesses no one has tested. The widget below makes the size of that delay concrete.

All the integration risk — the parts that only reveal whether they fit when they are wired together — lands at the end, in one collision, where it is most expensive to fix. A thin slice meets that risk in week one, on a small surface, while the cost of being wrong is a single increment. A big-bang plan meets it after months of work built on top of the unproven assumptions, where being wrong invalidates the stack above it.

The third force — no feedback until the end — is the one that can be measured. Set how many weeks of specification precede the first shippable increment, and the figure plots when the first real feedback arrives under each plan. A big-bang plan returns it at the end, after the full span. A thin-slice plan returns it in week one. The gap between the two is the count of weeks the big-bang plan carries its assumptions unvalidated.

Put the four forces on the Portal — the learning platform this course builds, with its branded Snowflake ids and its event-sourced engine behind one facade. The over-plan path opens with a single artifact: a forty-page Portal specification. It fixes the whole platform up front — the store, the engine, the web surface, the bot, the dashboard — every rule and every screen, written before a line of code exists.

For months it ships nothing. The build is "in progress" against the document, but no increment reaches a user, so nothing in the plan is tested. While the pages are written and re-written, the requirements move: how a student's progress should be recorded changes; what the store should surface changes. By the time code starts in earnest, the spec already disagrees with the world — and, forty pages deep, it disagrees with itself: an early section assumes one shape for an event, a later section another, and no executed check ever forced the two to reconcile. The document is large, internally inconsistent, and unvalidated, and it has returned exactly zero feedback.

Every force is visible at once. It was never finished — the forty pages kept growing. It drifted — from the world and from itself. It returned no feedback — nothing shipped. And the integration risk is still entirely ahead, waiting for the single release that has not happened. The same chapter, sliced thinly, would have shipped a branded id and one stored event in week one, and learned something true.

The over-plan failure lands twice: as the principle that names it, and as the concrete shape it takes on the Portal.

A big-bang spec is the whole system defined up front, before any code and before any feedback. It fails by four forces, each a consequence of bigness and bad timing: it is never finished, because completeness is unbounded; it drifts, because a document written before reality parts from it; it returns no feedback until the end, so its assumptions stay unproven; and it discovers its risk last, where risk costs the most. The Portal makes it concrete — forty pages, months, nothing shipped, a document at odds with the world and with itself. The remedy is not less rigour but a smaller, later, testable unit of definition.

Primary sources for the case against the big-bang spec, and where this dive connects in the course.