The scoping document I deliver before the first line of code

People assume development starts with code. In the way I work, it starts with a written scoping document I call a PREDEV. It runs a few pages, and it is validated before a single line is written.

Its job is simple: lock a shared reading of the project while getting it wrong is still free. Once the code exists, a misunderstanding no longer gets fixed in a document, it gets fixed in a database migration. That is more expensive.

On Grimoire Culinaire, every lot of the MVP had its PREDEV before development. Fourteen lots, fourteen scoping documents.

The document is not a list of intentions. It is a series of verifiable blocks. In practice, a Grimoire PREDEV always has the same sections.

Lot 8 of Grimoire was improved authentication. Not the vague instruction 'do auth', but a precise block: a unified sign-in screen, Google OAuth via Supabase's PKCE flow, a 'browse without an account' mode, and email verification with a 200-muffin bonus attached.

What makes this lot bounded is not the list of what it does. It is the list of what it does not do, written into the scope: the Google Cloud dashboard config, Apple Sign-In and Lottie animations are explicitly out, pushed to other lots. Measurable result: 23 tests added, 282 tests green at close.

Another lot, adding eight AI actions to the recipe detail screen, listed 19 files to create, 5 to modify and around 42 expected tests before a single line was written. That level of detail is exactly what lets you say 'this is done' without a debate.

A method article that shows only successes is lying. On Grimoire, scoping failed twice, and both times it cost me rework.

First miss: a lot that was too big. I had planned a single '+14 AI actions' lot. Impossible to validate as one block. I had to split it mid-flight into an infrastructure lot, then 15a, 15b-1, 15b-2. The first breakdown was simply wrong, and I only saw it when I tried to phrase it cleanly.

Second miss, more expensive: an incomplete scope on the very first lots. The difficulty, visibility, imageUrl and servings fields were missing from the data models. Nobody had scoped them. I found them on March 12 during a compatibility audit, and they had to be caught up with corrective database migrations (Drift v2 to v3). An incomplete scope does not vanish: it comes back later, as rework.

The main benefit is predictability. You see where the project is going, in what order, and on which basis to validate each delivery. Scope creep becomes visible because adding something means writing it down somewhere.

Budget and timeline conversations get more concrete: you talk in delivery units, not feelings. And when a lot is badly cut, like my two misses, it shows at the scoping step rather than at the bug step.

Scoping guarantees nothing: it just makes mistakes visible earlier, while they are still cheap. Both of my Grimoire misses went through scoping, not through production, and that is exactly why they were recoverable.

The document does not disappear when development starts, it evolves. In the end the MVP ran to 14 lots, and on delivery day the project stood at 635 tests, with a database schema at version 11. It is past 700 today. What I keep from all this is not the code: it is a project that stayed readable from the first lot to the last.