The launch ended at 4 a.m. after fifteen hours of fixes, arguments and one missing paragraph. Nobody had written what “done” meant. The project did not fail because of code; it failed because the spec was a chat thread. That night is what production hell looks like from the inside.
Since 2006 I have watched the same launch fail in teams of two and in teams of twenty-seven.
What a spec actually is
Not a hundred-page document. Four things: scope, roles, acceptance and change. Scope says what is inside and what is not. Roles say who decides. Acceptance says how we know it works. Change says what happens when a new idea arrives in week three.
Five signs the spec is missing
- The phrase “we will figure it out as we go” appears in the first meeting.
- Two people describe the same screen differently.
- Every new request is accepted without a date change.
- “Done” is decided by whoever is in the room at launch.
- The test plan is “we will click through it”.
What it saves
A one-page spec catches the expensive misunderstandings before code exists. It also protects the team: a written scope turns “you missed this” into “this was out of scope, here is the change”. The conversation moves from blame to a decision.
A one-page spec
Write the goal in one sentence. List five to seven user stories with acceptance criteria. Name the owner and the approver. List known risks. Describe the change process: who asks, who estimates, who approves. That page is enough for most projects.
When the client cannot write it
Then you write it and ask for a yes or no. A spec written by the contractor and confirmed by the client is better than a perfect spec nobody reads. Send it as a short document, not a 40-slide deck.
The habit that prevents the next 4 a.m.
Before the first line of code, read the spec aloud with the team. Any sentence that causes a shrug goes back for a rewrite. Ten minutes of that saves the launch night. The spec is not bureaucracy; it is the cheapest test the project will ever run.
Production hell is rarely caused by a hard technical problem. It is caused by an agreement nobody wrote down.
Questions before the first spec
Who writes it? The person closest to the business problem writes the first draft; the contractor edits it for feasibility. Two readers, one page.
How long should it be? One page for most projects. Ten pages usually means the scope is unclear, not that the document is thorough.
What if the client refuses to write anything? Write your assumptions and ask for a yes or no. Silence is not approval.
Does a spec kill agility? No. It defines what a change costs, which is exactly what agility needs to make a decision.
Checklist before the kickoff
- Goal in one sentence.
- Five to seven user stories with acceptance.
- Owner and approver named.
- Out of scope written down.
- Risks listed.
- Change process agreed.
- Launch date and rollback plan.
The spec is not a contract with the future. It is a snapshot of what everyone agreed to today, detailed enough to notice when reality diverges. Update it when the agreement changes, and keep the old version.
How to leave production hell
The fix is boring: one page, written before the first line of code, reviewed by whoever will be called at 4 a.m. User stories are a decent starting point for the acceptance part. Production hell is a process problem, not a talent problem.
The document survives people leaving; the chat thread does not.
Related reading: Why a business without goals does not grow and Software architecture: six patterns and how to choose.