--- title: "What a written scope should contain before any build starts" url: https://automaark.com/insights/what-a-written-scope-should-contain canonical: https://automaark.com/insights/what-a-written-scope-should-contain description: "Most engineering engagements go wrong before the first line of code, in a scope that was a list of features instead of a description of a system. Here is what we put in ours, why each section is there, and what happens when one is missing." organization: Automaark language: en llms: https://automaark.com/llms.txt author: Olamide Dada author_url: https://automaark.com/authors/olamide-dada date_published: 2026-09-29 date_modified: 2026-09-29 tags: Engagement model, Systems architecture, Scoping related_services: https://automaark.com/services/software-platform-engineering, https://automaark.com/services/cloud-infrastructure, https://automaark.com/services/cybersecurity --- # What a written scope should contain before any build starts Most engineering engagements go wrong before the first line of code, in a scope that was a list of features instead of a description of a system. Here is what we put in ours, why each section is there, and what happens when one is missing. ## The short version - A scope is not a feature list. It is a description of the system: what it is for, what data it holds, what it must never do, what it talks to, and who owns what when it is live. - Every section exists because its absence has a specific, expensive failure mode. Missing non-goals produce scope creep; missing invariants produce data corruption; missing operations produce a launch nobody can support. - The scope is written before the price and before the timeline, because both depend on it. A quote without a scope is a guess dressed as a commitment. - You should be able to hand the scope to a different engineering team and get roughly the same system. If it only makes sense with us in the room, it is not finished. The most expensive document in an engineering project is the one that was never written. When a build goes wrong, the post-mortem almost always finds the same thing: the team was working from a list of features, some messages, and a shared understanding that turned out not to be shared. The scope existed in several heads and agreed in none of them. We refuse to start build work without a written scope. Not as a formality, but because the scope is where the architecture gets decided, and architecture decided by accident is the kind that has to be undone later at ten times the cost. This piece is what we put in ours, section by section, and what tends to break when a section is missing. ## It is a description of a system, not a list of features A feature list says what the screens do. A scope says what the *system* is: its purpose, its data, its rules, its neighbours and its owners. Features fall out of that; they are not the starting point. The test is simple. Hand the document to a competent engineering team that has never spoken to you. Would they build roughly the same system? If the answer depends on conversations that are not in the document, the document is not finished. Here is what makes that possible. ## 1. Purpose and non-goals One paragraph on what the system is for, in business terms. Then a list of things it is explicitly *not* for. The non-goals are the part people skip and the part that pays for itself first. "This platform does not handle payouts to hosts; those remain in the existing finance system" is a sentence that prevents three months of drift. Every ambiguous request later gets checked against this list. **When it is missing:** scope creep, not because anyone is unreasonable, but because nobody wrote down where the edge was. ## 2. The domain model The entities the business reasons about, what identifies each, and which relationships are real. Written in words first, then as a diagram. This is where "customer", "account", "organisation" and "user" stop being synonyms and become four things with defined relationships, or one thing with a defined name. **When it is missing:** the schema gets designed by whoever writes the first migration, usually under time pressure, usually to make a screen work. We wrote about what that costs in [Why AI-generated apps fail at the data layer](/insights/why-ai-generated-apps-fail-at-the-data-layer). ## 3. Invariants: what must never be true A short, numbered list of rules the system enforces regardless of which interface, job or integration is writing. Overlapping bookings. Negative balances. Orders without a customer. Records visible across tenants. Each rule names the boundary responsible for enforcing it. That is the part that makes it real: a rule with no owner is a hope. **When it is missing:** the rules get enforced in one screen's validation, and violated by the API, the import script and the retry job. ## 4. Integration surface Every system this one talks to, in which direction, with what contract, and what happens when the other side is down. Payment provider, email, analytics, the CRM, the partner API, the mobile app. For each: who owns the contract, how versions change, and where the failure is handled. **When it is missing:** the integrations get built ad hoc, each with its own retry logic, its own error handling and its own idea of what a customer ID looks like. The system works until one partner changes something. ## 5. Security and data boundaries Who can see and change what, at the level of roles and data classes, not screens. Which data is sensitive, where it may live, how long it is kept, and which regulations apply. For AI components: what data reaches a model, under what terms, and what never does. **When it is missing:** access control becomes a UI concern, the index becomes a way around permissions, and the compliance conversation happens after launch with a customer's lawyer in the room. ## 6. Operations: what "live" means Where it runs. Who is paged when it breaks. How it is deployed, backed up and restored. What it costs to run at expected volume and at ten times that. What is logged, what is measured, what "healthy" means. Who owns the accounts, the domain, the secrets. This is the section clients are most surprised to find in a scope and most grateful for a year later. A system that nobody can operate is not finished; it is abandoned in advance. **When it is missing:** a launch that works, followed by a first incident that nobody knows how to handle, followed by a quiet dependency on whoever built it. ## 7. Milestones and what each one proves Not dates. Milestones: named states of the system, each with a concrete demonstration that it has been reached. "Guests can complete a booking end to end in staging, with real payment in test mode, and finance can reconcile it." A milestone you cannot demonstrate is a wish. Dates get attached to milestones after the scope is agreed, because dates depend on what is being built, and until now nobody knew. **When it is missing:** progress is reported as percentages, which mean nothing, and the last 10% takes half the project. ## 8. Ownership at handover What you receive: the repositories, the cloud accounts, the documentation, the runbooks, the credentials. What you are able to do without us afterwards. This is written at the start, because it shapes how everything is built. A system designed to be handed over looks different from one designed to be maintained by its authors forever. **When it is missing:** lock-in, not always by intent, but by default. ## Why price and timeline come after A quote produced before this document exists is a guess. It might be a good guess; it is still a guess, and the person paying is the one carrying the risk of it being wrong. So the sequence is: scope, then price, then timeline. The scoping phase itself is short and paid, and it produces a document you own. If you take it to another team, it should still make sense. That independence is not generosity; it is the only way to write the document honestly. A scope that only works with its authors in the room was written to win the build, not to describe the system. ## The honest position None of this is novel. It is what careful engineering teams have done for decades, and what gets skipped when a market rewards demos over durability. We are writing it down because clients ask what "architecture first" actually means in practice, and this is most of the answer: before the code, a document that says what the system is, what it must never do, what it talks to, and who owns it when it is live. If your current project does not have one, that is the first deliverable, whoever builds the rest. ## Questions this raises ### How long does the scoping phase take? It depends on how much of the system already exists and how many parties need to agree. It ends with a written document you can review, not a date we pick in advance. It is short compared with the build, and it is the cheapest place to change your mind. ### Is the scoping phase paid? Yes. It is real architecture work and it produces a document you own, whether or not you continue with us for the build. That independence is the point: a scope you can take elsewhere is a scope written honestly. ### What if requirements change during the build? They will. The scope is versioned, and changes are made to the document first and to the system second. That keeps the record of what was decided and why, which matters more in month nine than in week one. ## Sources - [Writing Effective Use Cases (Cockburn, 2000)](https://alistair.cockburn.us/) - [The Mythical Man-Month (Brooks, 1975), on the cost of late change](https://en.wikipedia.org/wiki/The_Mythical_Man-Month) --- Written by Olamide Dada, Founder & CEO, Automaark. More: https://automaark.com/insights