Specs and scoping (the core craft)

5.1 What the builder actually holds

The build is delegated. The scope is not. Your real job is deciding what gets built, in what order, and what "done" means. Everything upstream of the code is yours: the intent, the slices, the trade-offs, the acceptance bar. Lose the scope and no amount of fast execution saves you.

5.2 The screen inventory, the best scoping tool there is

Before building a feature, list every screen it touches, and for each screen, the four states it must handle: loading, empty, error, success. This one habit catches most of the scope you'd otherwise discover mid-build. A feature is not "the happy path." It's the happy path plus the three states everyone forgets. No blank screens, ever.

The deeper principle: design for the path that fails, not just the one that works. The empty state and the error state are not edge cases, they are where trust is won or lost. Most unfinished features are unfinished precisely there.

5.3 "Definition of done", in its three forms

"Done" means different things at different altitudes, and naming them prevents arguments. Done-coded: it builds, it type-checks, the change exists. Done-verified: it's been tested in a real browser, the four states work, the edge cases are handled. Done-shipped: it's in production and you've confirmed it live, the smoke test passed. A thing can be done-coded and nowhere near done-shipped. Always say which one you mean.

Definition of Done, the checklist. A slice is done when: it builds and type-checks; the four states work in a real browser; the edge cases and money paths are tested for real; it's committed and pushed; it's deployed and confirmed live (the smoke test passed); and the doc or changelog is updated. Anything short of that is "done-ish," which is another word for not done.

5.4 The go rule, and why it's literal

When you say "go," it means go: the decision is made, we don't re-debate. When something is marked delivered, it's delivered: we measure and iterate, we don't rebuild it. This sounds obvious and is constantly violated. A large share of lost time is re-litigating settled decisions. Write the decision down, with its rejected alternative (Law 3), and move.

5.5 How a request becomes real work

A request is not a task. "Can it also do X" is a fuzzy want. Turning it into work means clarifying the actual outcome wanted, sizing it (increment or project), finding where it lives in the code, deciding the trade-offs, then slicing it. The gap between "sure, easy" and the real work is where every bad estimate is born. Scope in writing, not in your head.

For the CTO in you

the distinction that prevents the most disputes is bug vs change. A bug is the product not doing what it was specified to do. A change is a new thing you now want. Different urgencies, different owners, different queues. Conflating them turns every "it should also do this" into a false emergency.

5.6 Walk the journey before you spec, and slice vertically

Before you write a spec, walk the whole user journey out loud, step by step: how does this person arrive, sign in, reach the thing, and what do they see at each step. A spec that nails the data model and the endpoints but skips "how do they actually log in" ships a feature that technically exists and practically doesn't. The question "show me the end-to-end journey" comes before the spec, not after.

And slice vertically, not horizontally. Deliver a thin complete path first (a user signs up, signs in, lands on an empty screen that works), then deepen it. Building all the plumbing horizontally before any single journey works end to end is how you accumulate a class of bugs that only appear when the pieces finally meet.

5.7 The spec an agent can't misread

This is the highest-leverage skill of the whole role, and almost no one names it. A human reads a loose spec and fills the gaps with judgment. An agent reads a loose spec and fills the gaps with a guess, confidently. So you write for the reader that will not ask. A spec an agent can't misread has: one goal in one sentence; the exact files and functions to touch, and an explicit list of what NOT to touch; the decisions already made, so it doesn't re-decide; the tests it must make pass; and one trade-off at a time, never a pile. Ambiguity is not a small tax with an agent. It is the failure. If a sentence can be read two ways, an agent will pick one and build it well.

5.8 Decision hygiene: protecting the one scarce resource

The scarce resource in this way of working is not compute, it's your attention as the decider. Protect it. Decide one trade-off at a time, so each gets real thought. Say no in writing and with a reason, so the no holds and doesn't come back next week. Batch the small reversible calls and move fast on them; slow down only for the hard-to-reverse ones (Part 4). And keep a decision log with the rejected alternative (Law 3), so you're never re-litigating a settled call while a new one waits. A builder who spends attention on everything has none left for the decisions only they can make.