Scoping Against an Artefact

The document arrived in my inbox on a Thursday afternoon as a five-page PDF, and the first thing on the first page was a hyperlink. The link pointed at a private GitHub repository. Beneath it, in a monospaced font, sat a git hash. Anyone opening the document was being told, before any prose, that the thing under discussion already existed and could be checked out and run on a laptop that evening. The next four and a bit pages were not a specification. They were a set of annotations against what the reader had, by now, presumably cloned. This flow stays. This form goes. This page is load-bearing and has not been touched in six commits; do not touch it. At the back was a one-page table titled Hardening targets, and a short appendix that listed every third-party library in the repository with its licence, the date of its last CVE and a note on whether we could live with it.

That was the scoping document.

Two years ago that engagement would not have existed. Vlad, one of our PMs, put a number on the shift recently: somewhere between 50 and 60 per cent of new engagements now arrive with a working prototype attached, against essentially zero two years before. Not all of them run; another PM reckons perhaps 10 to 20 per cent run cleanly, the rest showing intent without being executable. One client handed over the full codebase for a car-marketplace product and asked us to make it production-ready and go to market. Vlad’s first move was to read the code to reconstruct the user story, then use the product as a user would, before any scoping document followed.

In 2015 Nadia’s scoping document ran to eighty-four pages: three months of discovery, six operations staff interviewed, a signature block on page eighty-three and a change-control log on page eighty-four. Thirty-two thousand dollars of studio time was baked into it, and it bought a specification detailed enough that she could have handed it to any competent agency and got the same application out the other end. Sliday had been paid for the same operation three years earlier in a less formal shape: a long year of extraction that began with a sketch on paper. The two documents differ in form, not in what they were for. Each was the product of the engagement up to that point; the software was what the next contract would pay for.

The five-page PDF is a different object entirely: a contract appendix.

What is in the new document, and what is not.

The new scoping document — and we have, at Sliday, now written roughly a dozen of them in the same shape — has six sections, and none of them are optional. Section one is the reference to the repository: URL, commit hash, a one-line summary of what it does when you run it. Section two is What stays. A numbered list of features in the prototype that will be preserved as-is into the production build, with a one-sentence reason each. Section three is What goes. The same list, inverted: features the founder built that will be removed before shipping, each with a one-sentence reason the founder will find it hard to argue with. Section four is What changes. This is the largest section, usually three to four pages, and it is where the sentence-level editing lives: this endpoint needs auth, this table needs a foreign key, this component will be rewritten because the model chose a state-management library the studio does not support. Section five is Hardening targets: the list from From Builders to Hardeners rendered against this specific repository. Section six is the commercial envelope: hours, fee, milestones and the one paragraph that names what the studio warrants and what it does not.

What is not in the document is striking only if you have recently read an eighty-four-page spec. There are no user personas, no flow diagram, no mockups, no acceptance criteria in the Gherkin sense, no glossary, no competitive analysis, no paragraph describing the market. Every one of those things existed in Nadia’s spec because, in 2015, the specification was the only artefact the reader had. The reader had to be told, in words, what the product did, because the product did not yet exist. In 2026 the product does exist, more or less, at the other end of the GitHub link. The document does not need to describe what the reader can clone and run.

The fintech engagement.

I will walk through this with a specific example. In the second half of 2025 we took on a fintech founder (a composite of two real projects of that vintage) who came to us with a prototype she had built over three weekends. The product was a small-business expense categoriser. Her prototype imported a bank feed, ran each transaction through a classifier she had strung together (an embedding model paired with a JSON file of rules) and dropped the output into a dashboard her accountant could export as a CSV. It worked. Her accountant had tested it against a quarter’s worth of transactions and was complimentary. She wanted us to turn it into something she could sell. A working prototype, the PM on it was firm, does not mean skipping discovery of the client’s actual business needs: how it works technically, what business goal it serves, and why it behaves the way it does.

Our scoping document ran to six pages. What stays was four items. The bank-feed import module, because it was already integrated with the two providers her customers would use and both integrations had been tested. The classifier, not because it was good but because it was correct enough at her customers’ scale that rewriting it would not improve the business outcome and would cost three weeks. The dashboard layout, because her accountant liked it and that was the voice we were building for. The CSV export, because it was twenty lines of code and we had no quarrel with any of them.

What goes was longer. Seven items. A second dashboard she had prototyped late one evening and never removed; two login screens she had built in parallel and never chosen between; an auto-categorisation rule that silently applied to every new transaction and that we judged, on inspection, to be legally hazardous in an expense product used for tax; a notifications module that sent an email for every import and would, at her first paying customer, become spam; a feature flag left over from a debugging session; a hard-coded admin user in a users.json file; and a subscription-tier toggle with no billing wired up. Each item had a one-sentence reason. Each reason was something the founder could test against her own memory of why she had built the thing in the first place, which in half the cases was I was curious and in the other half was the model suggested it and I did not remove it.

What changes ran to three pages. Auth, hardening, the classifier’s confidence threshold, the data model for multi-tenancy, rate limiting on the bank-feed poll, an idempotency key on the import pipeline, a migration plan for the users.json file and a cut-over to a managed Postgres. Nothing in that section was a surprise to a senior engineer. All of it was surprising to the founder, which is the point.

Agent first, judgement after.

Roughly two-thirds of that document was drafted by an agent. We point Claude Code at the cloned repository with a short operator prompt naming the six sections and the voice we want. The agent produces a first pass. The agent reads the code, identifies the endpoints, flags unused routes, lists the third-party dependencies with their licences, finds the hard-coded secrets, notes the missing tests and proposes — in prose that is serviceable but never quite right — an initial What goes list. It does a competent job on sections one, five and six, and a mediocre job on two, three and four. The mediocre work is the useful work, because the judgement calls are what the studio is being paid for. A senior engineer reads the agent’s draft the way an editor reads a good first pass: with a red pen. The What stays list grows by one, shrinks by two and has its reasons rewritten. What changes picks up the three items the agent missed because it could not see the business context. What goes is redone almost in full, because the agent will not tell a founder to delete the feature she is fondest of; a human has to do that, in language she will accept. Another PM approaches a prototype with deliberate suspicion, hunting weak points: her concern is that founders who build their own prototypes skip the prior question of whether anyone needs the thing, so edge cases a proper specification used to force into the open get discovered only at release.

The document is drafted in an afternoon. In 2015 the equivalent took three months. What has collapsed is the production of the artefact, not the judgement inside it; Alenezi’s paper on agentic software engineering, posted as a preprint in April 2026, makes the same point in broader terms and calls verification the new bottleneck.¹ The shape of our scoping work is the shape of that claim when it is pushed down to the contract level.

The founder’s side of the first read.

When the founder opens the document, the page that matters to her is What goes. She is going to find, on it, two or three features she wrote in the small hours of a Saturday and was pleased with at the time. The document will name them and say why they are being removed. The language will be direct; we have learned, writing a dozen of these now, that hedging the deletions is worse than doing them cleanly. If the document has done its work, she should finish reading it in thirty minutes, disagree with one or two items, agree with the rest and feel that she now owns the next six weeks of the build rather than having surrendered them. The document is, for the first time, a map of her own repository drawn by somebody who reads repositories for a living. That is usually the sentence that persuades the founder to hand the keys over, and it is the sentence we have learned to say out loud on the scoping call rather than leaving it implicit in the PDF.

The commercial outline.

The scoping document defines the commercial envelope: what survives, what needs hardening and what the studio will charge to do it. The studio and founder agree whether that work belongs within the engagement or needs a separate fee. The deliverable can become the appendix to the production contract; accepting it means accepting the envelope on its last page. Who Warrants What works through the contract mechanics. The practical change is a short review of an existing repository rather than a large specification written before anyone can run the product.

What the document commits to the repository owner.

What the document commits the studio to is, by 2015 standards, unusual. Hardening targets is a named list and the fee on the last page covers it: the hardening checklist from From Builders to Hardeners, run against this specific repository. Licence provenance is addressed in the dependency appendix — every third-party package listed with its licence, anything incompatible flagged for replacement, anything generated verbatim by the model noted as such. Data handling is a single paragraph in What changes that describes how tenant data is separated, where logs are retained and which fields are redacted before they reach a model. None of the commitments are aspirational. Each line is a line the studio can be held to, and the reason it is written down rather than shaken on is that the evidence we trust points the same way from two directions. Borg and Tornhill found model refactorings breaking more often in unhealthy code; the DORA reports find AI gains landing hardest on teams that already run mature delivery platforms.²³ Neither studied our engagements, and our own PR-reversion numbers are what connect the two. We would rather name that investment in the appendix than discover it missing in production.

Where the engineer learns.

The last question is the most important one, and it is the one that takes longest to answer honestly. The scoping document is drafted, on our team, by a senior engineer or a studio lead — not because a junior cannot hold the tools, but because the judgement calls are what the document is. An agent produces the raw material; the senior makes the calls; the junior, for now, reads the finished document alongside the repository and watches the pattern. Over the course of a quarter a mid-level engineer on our team will have sat through perhaps eight of these documents being produced and will have written the first draft of two of them. That is the apprenticeship. It is slower than we would like. It is the honest answer we have, and The Recalibration takes the question up again later in the book.

The document the fintech founder signed in November of 2025 will not age as well as Nadia’s eighty-four pages did. It is written against a git hash, and the hash will move. Two of the items on What stays are, nine weeks later, in What changes. A Hardener on our team redlined Hardening targets in December and we issued a revised appendix. None of this is a defect of the document. A contract appendix is, by definition, the sort of thing that gets issued in revisions, and the prototype it sits against is the sort of thing that gets edited in commits rather than frozen in a signature block.

The scoping document used to predict the future; now it edits the present.