Shaping: writing the contract
Shaping is how the product owner and an assistant turn a want into a contract a stranger can build. The output isn't a sketch or a ticket — it's a spec precise enough that an agent who wasn't in the room can build the right thing without asking you a single question. Everything in this chapter is in service of that one bar.
The builder won't be in the room. The page has to hold the whole decision.
Hold that fact through every move below. The agent that builds this feature is a fresh, different agent — it starts cold, reads what's on the page, and builds it. It can't tap you on the shoulder. So the spec carries the whole decision, or the decision gets made by a stochastic builder filling your gaps with guesses. The moves of shaping all exist to get the decision out of your head and onto the page tightly enough that it can't.
Go after the why before the solution
The assistant doesn't start filling in boxes. It asks who this is for, what changes for them, what winning looks like. You don't reach the what until the why is solid — because solutions are cheap and seductive, and grabbing one early means building the wrong thing well. The why is also what survives to memory; the solution will be rewritten ten times.
Force a falsifiable Goal
This is the hinge — the move a spec is built around. State, out loud, how you'll both know it's done, as an outcome you could check rather than a feeling. "Improve the quote flow" doesn't survive. "A customer with a valid VIN sees a dollar figure in under three seconds" does. That sentence is the moment a want becomes a contract — and it's the target the implementer builds toward.
Fence the non-goals
A strong model over-builds on purpose, so write down the fence that stops it. "Should it also quote things you don't carry? Save quotes? Email them?" Every no gets recorded. This is the most valuable part of the session and the part everyone skips — an unfenced agent will gold-plate the thing you never asked for, and you'll find out at review when it's expensive to unwind.
Defer unknowns with defaults
When you hit something undecided, the assistant writes the question down, picks a sensible default, and keeps moving. Indecision becomes a logged choice with your override still open — never a roadblock. Nothing stalls the session, and the one or two things you couldn't settle arrive at the build marked, with instructions for what to do when the build hits them.
Two of these moves shape what's on the page, and one move shapes what
isn't. Build mechanics — "change line 412, branch the proration here" — are
gold for the builder and poison for the contract, because they're right today and wrong
next week. They get relocated to implementation.md, the build-scratch slot, not
discarded: kept for the builder, dropped at graduation, never allowed to rot in the
part that becomes permanent memory.
And acceptance proves the Goal, never the floor. "Tests pass, lint clean" is baseline hygiene every branch is held to, not acceptance — the razor is would this check appear in every spec? If yes, it's a baseline; the codebase's standards own it. Each acceptance check is the Goal decomposed into something settleable, tracing back to a clause of the Goal or a numbered behavior. That's what keeps a spec specific without turning into a manual.
Reference: spec body sections (Goal, Non-goals, Acceptance), and the frontmatter fields that route and govern the build.