Before any code is written, an agent interviews you about your idea until you both understand it the same way. Matt calls this grilling. It's where the main Flow starts: grill-with-docs sharpens the idea by interview.
How a grilling works
The agent maps your idea as a design tree: every decision branches into the decisions that hang off it. Say you're building a FastAPI booking site. "Can guests cancel?" hangs off "Do guests need accounts?"
The agent asks in rounds. A round holds every question it can ask now without guessing at answers it hasn't heard yet. Matt calls that set of questions the frontier. Each question comes with the agent's recommended answer, worded so that "yes" accepts it. Then it waits for your answers before the next round. Your answers settle some decisions, which opens up the questions that depended on them.
a FastAPI booking siteevery decision branches into the decisions that hang off it
Do guests need accounts?Your answers settle some decisions (settled)
Can guests cancel?the frontier (frontier)
The agent maps your idea as a design tree
Facts and decisions
Grilling splits the work in two:
Facts are the agent's job. Which database does the repo use? What's already in src/? The agent looks these up itself, often with a subagent (a helper agent that starts with a fresh context window), instead of asking you.
Decisions are yours. The agent puts each one to you and waits.
When it's done
The grilling ends when the frontier is empty: every branch of the tree visited, and nothing left silently assumed. Even then, the agent doesn't act until you confirm that you share an understanding.
When talk isn't enough
Some questions can't be settled in conversation: how a state model behaves, or what a page should look like. Then the main Flow detours through a throwaway prototype, and brings the answer back to the grilling.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's README states the problem plainly: "The most common failure mode in software development is misalignment." You think the developer knows what you want, then you see what they built. He says this is "just the same in the AI age": there is "a communication gap between you and the agent". His fix is a grilling session. (Matt wrote these README lines on 2026-04-28, and they are unchanged at the pin commit of 2026-10-29.)
His AI Coding Dictionary entry on grilling (last changed 2026-06-05) names how the gap shows up with agents: "The technique exists because agents fill gaps silently." Given a two-line prompt, the agent "picks defaults and writes them in". The result looks finished, and "the guesses are indistinguishable from the choices, so you discover them late". Grilling turns this around: "instead of guessing, the agent has to ask."
How it works underneath
The idea underneath is the design concept, a term Matt's dictionary credits to Brooks (The Design of Design). It means the shared understanding of what's being built. The conversation, handoff documents such as a Spec, and the code are all attempts to capture it, but none of them is it.
The dictionary explains the usual cause when "the agent writes exactly what you asked for and it's still wrong". You hadn't worked everything out yet. Your prompt "was silent on the parts you hadn't", and the agent "filled those silences with its own assumptions". Nothing broke. There just wasn't a whole design concept to share yet. That's also why it warns that writing a Spec too early "just captures the misalignment in a more durable asset".
The README opens this part with a quote from The Pragmatic Programmer: "No-one knows exactly what they want". So grilling isn't a test of a plan you already hold. It's how the plan gets made.
Citations (64)
From snapshot/skills/grilling/SKILL.md, line 6: “Interview the user relentlessly until you reach a shared understanding. Map this as a design tree: every decision branches into the decisions that hang off it.”
From snapshot/skills/grilling/SKILL.md, line 8: “The frontier is every decision whose prerequisites are already settled: the questions you can ask now without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.”
From snapshot/skills/grilling/SKILL.md, line 26: “Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them.”
A second reason it works is the model's own knowledge. Matt's "9 Things People Get Wrong" (updated 2026-05-25) says that during grilling you rely on the model's parametric knowledge (what it learned in training) "to suggest things you might not have considered". Hence his warning: "A dumb model won't give you good ideas." Use a big model to grill. A smaller one can do the building, where most of what it needs is already written down.
Parametric and contextual knowledge, the two kinds Matt contrasts, from his 2026-05-25 article. From aihero.dev, 30 October 2026.
Anthropic recommends the same move in its own Claude Code docs. When you don't yet know what you want, "Ask Claude to interview you instead". Once the Spec is written, it says to "start a fresh session to build from it".
A real example
Anthropic's best-practices page gives a backend example you could run on a FastAPI app:
I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.
The page says Claude comes back with questions about "per-user versus per-key limits, what happens to requests over the limit, what's out of scope". Each of those is a default the agent would otherwise have picked for you.
Matt's own work shows the other side of the rule. In his video editor he has a feedback button. A note becomes a GitHub issue, an implement agent works on it "immediately", and a code review agent reviews it. Only then does he "do my alignment". He says this works for "things that are very easy to specify things that I don't need to grill on" (interview, 2026-09-17).
Where it goes wrong
Grilling things that are cheap to fix. In the interview (2026-09-17) Matt says "you shouldn't be using Grill Me for everything". It's for work that is "quite large and hard to row back from", where wrong code would sit in the context window "influencing everything that comes afterwards". For "move this button three pixels to the left" or "a fiveline change", you "can align afterwards". His rule: "where you can you should shift right as much as possible", meaning check after building rather than before. He gives three questions:
"Is it a small enough thing that I can align afterwards?" "Then don't use grill me."
"Does it fit into a single session?" "Then use grill me."
"Does it span multiple sessions?" Then he uses wayfinder.
The README says to use the grill Skills "every time you want to make a change". Matt wrote that line on 2026-04-28, and it is still there at the pin commit (2026-10-29). The interview (2026-09-17) is newer than that line, and it is his more detailed answer. No SKILL.md settles it. Read "every time" as every change that is worth aligning on first.
A scope too big for one session. Matt's Skill page for grill-me (updated 2026-08-24) asks: "It asked me two hundred questions. What went wrong?" His answer: "Usually the scope was too large." His "9 Things" article (2026-05-25) adds that a too-large scope hides high-fidelity questions and runs into the context window's limits. The fix is to "Have the agent break it into smaller, grillable chunks" and grill each one.
One scope broken into smaller pieces, from Matt's 2026-05-25 article. From aihero.dev, 30 October 2026.
Being too passive, or too active. The same article says: "Many long grilling sessions fail because people are too passive with their agent." On 2026-04-19 a user opened issue #44, "Codex just asked me 200 questions". A second user wrote that it "feels like I'm being tested". Matt replied: "remember that you are the one in charge." He added: "It's a conversation, not an exam." The article also names the opposite failure: "If you're just planning and planning without building, you're over-grilling."
From passive to active: Matt's spectrum for how you steer a grilling, 2026-05-25 article. From aihero.dev, 30 October 2026.
Throwing the decisions away. A finished grilling leaves "a context window full of design decisions". Matt's advice is not to clear that context just to write a document. Every decision should "either become code or be documented in a handoff artifact".
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick two changes. One small: change a label on the TypeScript website. One large: let a member cancel a class booking.
Ask Matt's first question of each: is it small enough to align afterwards? Build the small one straight away, then look at it.
For cancellations, run grill-with-docs before writing any code.
Afterwards, list the questions you hadn't thought of yourself, such as late cancels or refunds. Each one is a default the agent would have filled in silently.
Read more
Grilling, AI Coding Dictionary, Matt Pocock, last changed 2026-06-05
Design concept, AI Coding Dictionary, Matt Pocock, last changed 2026-06-05
Going deeper's Check questions are asked in Next up.
“Finding facts is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent with a fresh context window to find it; don't ask the user for anything you could look up yourself.”
From snapshot/skills/grilling/SKILL.md, line 30: “The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.”
From snapshot/web/aihero.dev/ai-coding-dictionary-design-concept.md, line 51: “The shared understanding of what's being built, held in common between user and agent but separate from any asset. Brooks' term ( The Design of Design): the conversation, handoff artifacts, and the code are all assets that try to capture or reach the design concept, but none of them are it.”
From snapshot/web/aihero.dev/ai-coding-dictionary-design-concept.md, line 53: “the agent writes exactly what you asked for and it's still wrong. The usual cause is that you hadn't fully figured out what you wanted. The design concept wasn't finished in your own head — your prompt captured the parts you'd worked out, and was silent on the parts you hadn't. The agent filled those silences with its own assumptions, because there was nothing to align with. Nothing malfunctioned. There was no shared design concept, because there wasn't yet a whole one to share.”
From snapshot/web/code.claude.com/docs-en-best-practices.md, line 118: “Claude comes back with multiple-choice questions about the parts you haven’t pinned down: per-user versus per-key limits, what happens to requests over the limit, what’s out of scope.”
From snapshot/web/youtube.com/watch-v-4dhcspkebwi.md, lines 774–775: “Because I believe that you shouldn't be using Grill Me for everything. [73:03] Essentially, you need grill me for um pieces of work where the actual thing being done is going to be quite large and hard to row back from.”
From snapshot/web/youtube.com/watch-v-4dhcspkebwi.md, lines 780–782: “But for some cases, like simple bug fixes or just like move this button three pixels to the left, it's obvious that you don't need to align before that. [73:52] You can see the thing if it's just like a fiveline change or something. [73:54] You [clears throat] can align afterwards.”
From snapshot/web/youtube.com/watch-v-4dhcspkebwi.md, lines 790–794: “Is it a small enough thing that I can align afterwards? [74:39] Then don't use grill me. [74:40] Does it fit into a single session? [74:42] Then use grill me. Does it span multiple sessions? [74:45] I need to align over the entire thing then use wayfinder.”
From snapshot/web/youtube.com/watch-v-4dhcspkebwi.md, lines 784–786: “I have a a button that I can send feedback to it. [74:12] And I often use this for very simple tasks where I send the feedback it goes into a GitHub issue. [74:16] This immediately gets picked up by an implement agent gets just worked on immediately.”
