The argument has to happen somewhere
Every project contains a disagreement: about the data model, the boundary between systems, what happens when a third party is down. That disagreement will surface eventually. The only question is whether it surfaces in a document, in a code review, or in production at 2am.
Documents are the cheapest of the three by an enormous margin, so we deliberately front-load it.
What the document contains
Six sections, and nothing else.
1. The outcome
What changes for the business when this works, written so that it could be measured. "Reduce month-end close from three days to under a day" is an outcome. "Modernise the finance stack" is a mood.
2. The data model
Entities, ownership, and where the source of truth lives for each one. Most integration pain traces back to two systems both believing they own the same record.
3. The boundaries
Every system we talk to, and what happens when each is unavailable. Not "we will handle errors" — specifically: retry, queue, degrade, or fail loudly.
4. The security surface
Who can reach what, and how that is enforced rather than intended. A sentence saying "only admins can do this" is worthless unless it names the mechanism.
5. Trade-offs made
Each significant decision with the alternative we rejected and why. This is what makes the document useful to the engineer who joins in a year and wonders why it is built this way.
6. What we are not doing
The section that prevents the most rework.
Why section six matters most
Scope creep rarely arrives as a request to build something new. It arrives as an assumption nobody wrote down — the client assumed multi-currency was included, we assumed it was not, and neither of us discovered the gap until the demo.
Listing non-goals explicitly, and having the client acknowledge them in writing, has prevented more waste than any process we have tried.
When it is not worth it
For work under roughly two weeks, this is overhead. We write a paragraph and start.
The document earns its cost when several people, several systems, or several months are involved — which is most of what we are asked to build.