Delivery
How I scope a build so it does not run over
The specification format I use before writing any code, what goes in it, what deliberately stays out, and why scoping is now the constraint rather than implementation.
Key takeaways
- Now that implementation is fast, the binding constraint on delivery is decision-making. Scoping is where projects are won or lost.
- A useful specification fits on two pages and states outcomes, constraints, non-goals and how you will know it worked.
- Non-goals are the most valuable section, because they are the only part that prevents scope from expanding silently.
- Every milestone ends with something deployed. A milestone with no running artefact is a status update wearing a costume.
Software projects overrun for the same reason they always have: nobody agreed precisely enough what was being built.
That has become both less forgivable and more consequential. When implementation took months, a vague brief got corrected by the slow drip of demos and conversations along the way. When implementation takes days, a vague brief produces a finished, confident, wrong thing before anyone has had the corrective conversation.
So I spend disproportionate time on the document that comes first.
The specification
Two pages. Five sections. Written before any code exists, and signed off by whoever gets to say the project succeeded.
1. Outcome
One paragraph, in the language of the people who will use it. Not "build a notifications service" but "an operations manager finds out within two minutes when a shipment misses its window, without watching a dashboard."
If this paragraph mentions a technology, it is written at the wrong level.
2. Constraints
What is fixed and not up for negotiation. Existing systems that must be integrated with. Compliance requirements. Performance floors. Team skills the result has to be maintainable by. Budget ceilings, including runtime cost, which is frequently forgotten until the first bill.
3. Non-goals
The most valuable section in the document, and the one people most often skip.
Everything a reasonable reader might assume is included but is not: the adjacent feature, the second user type, the integration that would be natural to add, the edge cases consciously deferred. Written explicitly, because unstated exclusions get quietly re-included by whoever is closest to the code.
4. Acceptance
How we will both know it works, stated concretely enough that two people would agree on whether it had happened. Usually a handful of scenarios in plain language, which become the tests.
This section is what turns "done" from a judgement call into an observation.
5. Milestones
Each one ends with something deployed and usable. Not "backend complete", a working slice, narrow but real.
The discipline here is that a milestone with no running artefact is not a milestone. It is a status update, and it hides risk rather than reducing it.
Why this matters more now
The old constraint was engineering hours, so the rational thing was to spend planning time proportional to build time. Two days of scoping for a three-month build felt about right.
That ratio has inverted. When a well-specified two-week feature can be substantially built in two days, the two days spent getting the specification right are no longer overhead, they are the majority of the value-adding work, and the place where the outcome is actually determined.
What I do when scope is genuinely unknown
Sometimes the honest answer is that nobody knows what should be built yet. Writing a specification for that is theatre.
In that case the first engagement is explicitly a scoping engagement, one to two weeks, with a written specification, an architecture outline and a milestone plan as the deliverable. It is priced separately and structured so the output is useful regardless of who builds it, including if that turns out not to be us.
That is not generosity. A project that starts from a real specification is one I can price honestly and deliver on time, and those are the only kind worth taking.
Frequently asked questions
How long should a specification be?
Two pages. If it needs more, the milestone is too large and should be split. Long specifications are usually a symptom of unresolved decisions being deferred into detail rather than made.
What goes in a non-goals section?
Everything a reasonable person might assume is included but is not, the adjacent features, the edge cases you have consciously decided to handle later, the integrations that come in a future milestone. It is the section that stops scope from growing without anyone deciding it should.
Does fixed-scope work when requirements change?
Yes, provided the milestones are short. Fixing scope for four weeks is realistic; fixing it for six months is fiction. Changes between milestones are normal and expected, the structure exists so a change is a visible decision rather than a quiet accumulation.
References & further reading
- [1]Martin Fowler, Specification by Example
martinfowler.com
- [2]
- [3]
Related resources
Senior fullstack engineering
Contract senior fullstack engineering for product teams. TypeScript, React and Next.js on the front, Node, Python and Java services behind, Postgres and cloud infrastructure underneath, delivered with tests, CI/CD and observability.
AI integration
Contract AI engineering for production products: retrieval over your documents, structured extraction, assistants and agent workflows, with the evaluation suite, guardrails and cost controls needed to run them for real users.
Data reconciliation: how to sign off a report when two systems disagree
A practical guide to choosing the control total, tracing a difference and deciding when a replacement report is ready to use.
Turn the trend into shipped software
I contract as a senior fullstack and data engineer, building the production systems your customers and your reporting depend on.