Lesson 1 · Failure mode #1: misalignment

Grill the agent before it writes a line

The most common reason an agent ships the wrong thing is not that it codes badly. It is that it never understood what you wanted, and neither of you noticed until the code existed. The fix takes five minutes and is the single highest-leverage habit in Matt's repo.

Why this is failure mode #1

Matt opens the repo with this:

"No-one knows exactly what they want." David Thomas & Andrew Hunt, The Pragmatic Programmer

You think the agent knows what you want. Then you see what it built and realize it understood something else. This is the same communication gap that exists between a client and a developer, now compressed into seconds. Writing code first and discovering the gap later is the expensive path. Closing the gap first is cheap.

You already feel this. Every time you've written a one-line prompt, watched the agent confidently build the wrong abstraction, and thought "that's not what I meant", you were paying the misalignment tax. Grilling is how you stop paying it.

What a grilling session actually is

The entire grilling skill is four sentences. That is the point: it is a posture, not a framework. Here is the real instruction the agent runs:

Interview me relentlessly about every aspect of this
plan until we reach a shared understanding. Walk down
each branch of the design tree, resolving dependencies
between decisions one-by-one. For each question, provide
your recommended answer.

Ask the questions one at a time, waiting for feedback on
each before continuing. Asking multiple at once is
bewildering.

If a question can be answered by exploring the codebase,
explore the codebase instead.

Four properties make it work, and each one is a rule you can hold the agent to:

One question at a time. A wall of ten questions is bewildering and you answer them shallowly. One question gets a real answer.
It recommends an answer to each. You are reacting, not generating from scratch. Reacting ("no, actually B") is faster and sharper than inventing.
It walks the decision tree in dependency order. Early answers reshape later questions. That is why one-at-a-time matters: question 6 depends on your answer to question 3.
It explores the codebase instead of asking when the answer is already in the code. It should never ask you what it can read.

The mindset shift Grilling inverts who interviews whom. Normally you brief the agent. Here the agent interrogates you, and that surfaces the decisions you didn't know you were making. The goal is not a perfect spec. It is shared understanding before code exists.

grill-me vs grill-with-docs

Two doors into the same loop:

/grill-me → the plain interview. Use for non-code planning or a quick alignment pass.
/grill-with-docs → same interview, but it also builds your project's shared language (CONTEXT.md) and records hard decisions as ADRs while you talk. That is Lesson 2. Start with /grill-me to feel the loop.

Check yourself

Answer from memory before moving on. Retrieval is what makes this stick.

Why does the grilling skill insist on one question at a time?

During a grilling session, when should the agent NOT ask you a question?

Why does each grilling question come with the agent's recommended answer?

Do this now (your one win)

You have /grill-me and /grilling available in this environment already. Pick a real change you are about to make, in rejiglabs or a client project, something with at least one open design decision. Then:

Open the project and type /grill-me (or describe the change and say "grill me on this").
Answer one question at a time. When the agent gives a recommendation you agree with, say so and move on. When you don't, push back.
Notice the moment a question surfaces a decision you hadn't consciously made. That moment is the misalignment you just caught before it became code.
Stop when you both clearly share the picture. Then let it build.

Come back and tell your teacher: what did the grilling surface that you would have otherwise discovered only after the code was wrong? That answer becomes a learning record and sets up Lesson 2.

Primary source · read this
grilling/SKILL.md and the "Didn't do what I want" section of the repo README. Both are under five minutes.

Your teacher is here Stuck, or want a question answered that this lesson didn't cover? Ask the agent directly. That is what I am for. Good followups: "grill me right now on <my actual change>", or "show me a grilling transcript that caught a real bug".