Section 3Align — grill before you code
The oldest failure in software is building the wrong thing because nobody was aligned. It predates AI by half a century: the customer meant one thing, the developer heard another, and the misunderstanding only surfaced after weeks of work. Agents make it worse, not better: the same eagerness that has them declaring victory (Section 1) has them start coding your first vague sentence immediately. A human developer with a vague brief at least hesitates. An agent just builds. The agent you set up in Section 2 will do exactly that the moment you let it — which is why this section comes before any building.
It's worth being precise about why the agent builds instead of asking. A language model fills every gap in your request with the most statistically common interpretation — "user login" usually means email and password, so that's what you get. It isn't wrong exactly; it's average. Which means every detail you leave unspecified is a decision you've silently handed to an averaging machine. Alignment is the act of taking those decisions back before they get built into the code.
The grill — one question at a time
The fix is grilling — you make the agent interview you, one question at a time, until every fuzzy decision is nailed down. Only then does anyone write code. Run /grill-me (or /grill-with-docs, which also reads your existing docs). The agent asks one sharp question, waits, asks the next. It hunts for the decisions you skipped.
The value isn't the questions you could have asked yourself — it's the ones you didn't think to ask. A good grill probes edge cases ("what happens on the third failed attempt?"), scope boundaries ("who is explicitly not allowed to do this?"), and hidden defaults ("expires after how long?"). Each of those is a decision that will be made either way. The only choice is whether you make it now, in a ten-minute conversation, or discover three days later that the agent made it for you.
Why one question at a time? Because each answer should change the next question. If you answer "Google SSO only," the follow-up about password-reset emails disappears and a sharper one about blocked Google accounts takes its place. Ask five questions in one batch and you get five shallow answers and no follow-ups — the same reason a good doctor doesn't hand you a form when your symptoms are unclear.
You: "Add user login."
Agent: builds email/password auth. You wanted Google SSO (Single Sign-On — logging in with an existing Google account instead of a new password), sessions that expire in 8 hours, and no self-signup. Two hours wasted.
Agent: "SSO or password? Who can sign up? How long do sessions last? What happens on the third failed attempt?"
You answer four questions. The agent now builds the thing you actually meant.
How do you know when to stop? When the questions stop surprising you. A grill that's still producing "oh — I hadn't thought about that" is earning its keep; once the answers feel obvious, you're aligned. And "I don't care" is a perfectly good answer — said out loud. An explicit "don't care, pick something sensible" is itself a decision: it frees the agent to choose and tells everyone the choice wasn't load-bearing. The silent version of the same thing is how misunderstandings start.
Ubiquitous language — one word, one meaning
As you grill, capture your project's real terms in a context.md file. This shared glossary is your ubiquitous language (an idea from Domain-Driven Design). Once "standalone video" has one agreed meaning, the agent names variables consistently, stops re-explaining itself, and even spends fewer tokens thinking. It's documentation and a token-saver at once.
The test for whether a word belongs in the file: could two people on this project mean different things by it? In a salon-booking app, is a "customer" the salon that pays you, or the person booking a haircut? Until that's written down, half your conversations — with the agent and with humans — quietly run on different definitions, and the code ends up with customer, client and user all meaning slightly different things. One word, one meaning, one place where the meaning lives.
The same leverage applies to UI vocabulary, not only domain terms. Knowing the name of an established pattern turns a vague request into a precise one: "add a skeleton screen while it loads" gets you something specific and well-understood on the first try; "show something loading, like, greyed-out boxes or whatever" makes the agent guess. This is the practical case for knowing the pattern catalogue in the appendix — not just so you avoid a bad pattern, but so you have the words to ask for a good one.
Record decisions as ADRs
When grilling settles a real decision, write it down as an Architecture Decision Record (ADR). That's one small file in docs/adr/ — the choice, and why you made it. The "why" is the valuable half: six months from now, nobody debates what you decided (the code shows that); they debate whether the reasons still hold. An ADR with its reasoning intact settles that argument in thirty seconds.
What an ADR actually looks like. A dozen lines of plain text with three parts: the context (what problem forced a choice), the decision (what you picked), and the consequences (what gets easier, what gets harder). For example: "Context: salons need booking to work offline in the back room. Decision: store bookings locally first, sync later. Consequences: works with bad Wi-Fi; syncing conflicts must be handled." That's the whole format — the discipline is writing it at all.
ADRs are how you steer a system without holding all of it in your head — and with agents they pay twice, because the agent reads them too. An agent that finds docs/adr/ proposes changes that respect yesterday's reasoning instead of cheerfully re-litigating it. You wrote the "why" once; every future session inherits it for free. Section 10 leans on them heavily.
Every later phase inherits this alignment. A bad grill produces a confident agent building the wrong feature fast. A good grill is the difference between amplifying your judgment and amplifying your mistakes.
Know who it's for and what it's solving — once, not every feature
Grilling above nails down one feature. Before the first one, grill the product itself, once, and write the answer down somewhere every future feature request gets checked against: who is this actually for — a specific person, not "everyone" (the owner of a two-chair salon books very differently than a 40-employee chain) — and what problem does it solve for them that they'd otherwise solve worse (a phone and a paper diary, a generic calendar tool, a competitor). Keep the answer in context.md alongside your ubiquitous language.
Two honest sentences are enough, but they have to be sharp enough to exclude things. "Helps businesses manage bookings" excludes nothing and therefore decides nothing. "Lets a solo salon owner take bookings while both hands are in someone's hair" tells you instantly that a five-step booking wizard is wrong and a phone-friendly one-tap confirmation is right. It's the yardstick every "should we build this" question gets measured against, not a one-time exercise for a pitch deck.
Question the feature before you build it
A customer asking for a feature is describing a solution, not necessarily the problem. Before grilling how to build it, grill whether to: what are they actually trying to accomplish — the job they're "hiring" this feature to do, in the jobs-to-be-done framing — and is the feature they asked for really the best way to do that, or just the first thing they thought of? Sometimes the honest answer is a smaller change, a setting that already exists, or nothing at all. Henry Ford's line about the faster horse is a cliché because it keeps being true: a request tells you the destination, not necessarily the route.
"Jobs to be done," in plain words: people don't want products, they want progress — they "hire" a product to get a job done, the way you hire a plumber. Someone asking for "export to Excel" may really have the job "my accountant needs last month's numbers." A monthly email to the accountant might do that job better than any export button — but you only find out by asking about the job, not the feature.
Validate before you build
Agents make building cheap, and cheap building has a failure mode all its own: building becomes the default response to every idea. When a feature — or a whole product — costs an afternoon, "let's just build it and see" feels rational, and premature building quietly replaces validation as the way ideas get tested. But code was never the expensive part of a wrong product; the months of attention, positioning, and maintenance that follow it are. Before the salon app exists at all, the question isn't "can an agent build this?" — it obviously can — but "would a salon owner actually switch from the phone and the paper diary?" That's a question about demand, and no amount of building answers it.
So validate demand first, sized to a solo builder: five real conversations with salon owners about how they take bookings today and what actually goes wrong; a one-page landing site describing the product with a waitlist button and a little traffic pointed at it; ideally a pre-sale — a yes that costs money is the only yes that predicts anything. Name your riskiest assumption out loud ("owners will let customers book unsupervised") and design the cheapest test that could kill it. The pleasant twist: agents cheapen validation exactly as much as they cheapen building — they'll draft the interview script, argue against your leading questions, and build the landing page in an afternoon. Validation is agent work like everything else; it just comes first.
And keep one blunt question on the table throughout: should this be software at all? Sometimes the job behind the idea is done better by a spreadsheet, an existing tool, or a change to how the salon runs its book — and discovering that in week one is the method working, not failing.
Say no on purpose — feedback doesn't scale by building everything
Once real users exist, feedback arrives constantly, and building all of it is how a focused product turns into a pile of settings nobody can find their way around — more surface area is also, mechanically, more code and more bugs (Section 7). Run intake through a structured board (a public feedback tool, or even a simple issue tracker) where a request is logged as the underlying problem, not the literal ask, so five different phrasings of the same need collapse into one signal instead of five separate tickets.
Prioritise with something more disciplined than "who complained loudest" — a simple score like reach × impact × confidence ÷ effort (the RICE framework) forces the comparison into the open. It doesn't have to be precise to be useful: "affects maybe 40 customers a month, big improvement for each, I'm 80% sure, costs three days" versus "affects 3 customers, minor, certain, costs two weeks" is not a hard call once it's written down — the point of the arithmetic is making you write it down. And publish the "no"s too, with the reason — a visible decision, even a negative one, builds more trust than silence.
Make the agent challenge you, not just agree with you
Grilling is the sharpest version of this, but the same posture should hold for every consequential decision along the way, not only the first one. Left to its defaults, a model trained to be helpful leans toward telling you what you want to hear — Anthropic's own analysis of real Claude.ai conversations found the model gets measurably more accommodating specifically in conversations where the user pushes back, exactly backwards from what you want out of a system meant to catch your mistakes. Don't mistake the model's agreeableness for honesty, and don't let a session where the agent never once pushed back read as proof everything was fine — it's at least as likely a sign nobody asked it to disagree.
Make disagreement structural, not a hope. Give any consequential decision — a UX pattern choice, a technology pick, not only architecture — the same "design it twice" treatment as Section 10: one agent proposes it, a second one is explicitly tasked with the counter-case (the strongest argument against, a real risk assessment, not a token objection), and you decide between the two rather than rubber-stamping the first answer. Some teams give that second role an explicit name — an "opponent" or devil's-advocate agent whose only job is to argue against the proposal — which makes the disagreement a designed part of the process instead of something you'd have to remember to ask for. Explain the decision in concrete terms as it's presented: not "there are trade-offs" but "pick A and this specific thing gets harder later; pick B and this specific thing costs more now."
The cheap everyday version needs no second agent: end consequential requests with "argue against this before you agree," or ask "what would make this a bad idea?" before accepting a proposal. The answers are often mediocre and occasionally decisive — but you only get them if asking is a habit rather than an inspiration. The structural point is the same at every scale: agreement you didn't have to earn is not evidence. What the grill leaves behind — decisions frozen in context.md and ADRs — is the raw material Section 4 turns into a plan and tickets.
Quick check: you type "add user login" and the agent immediately starts writing code. What went wrong before the first line?
Nothing was aligned — so every decision you left unspecified (SSO or passwords? who can sign up? how long do sessions last?) is being made right now by an averaging machine. The move: stop it and run the grill. One question at a time until the answers stop surprising you, with "don't care, pick something sensible" said out loud where it's true; the settled words go in context.md, the real decisions become ADRs, and the agent argues against the plan once before you accept it. Then — and only then — it builds: the same feature, minus the guesses.