Grill Me & Grill With Docs: Align With Your Agent Before You Build

The most expensive failure in AI-assisted coding isn’t a bug — it’s building the wrong thing well. You describe a feature in two sentences, the agent nods, writes three hundred lines, and only when you read the diff do you realize it understood something different from what you meant. The Pragmatic Programmer put the root cause bluntly decades ago: “no-one knows exactly what they want.” The requirements don’t exist yet in a form anyone can hand over — they have to be discovered through conversation.

/grill-me and /grill-with-docs are two slash-command skills from Matt Pocock’s mattpocock/skills pack that force that conversation. Instead of you interviewing the agent, the agent interviews you — relentlessly, one question at a time — until every branch of the decision tree is resolved. They’re consistently his most-installed skills, because they fix the single most common failure mode before a line of code is written.

Note

Both are user-invoked skills (you trigger them by name; the agent won’t auto-fire them), and both wrap one shared grilling loop. They’re plain Agent Skills, so the same install and commands work across Claude Code, Cursor, and Codex. From the mattpocock/skills repo (MIT-licensed) by Matt Pocock.

What you’ll walk away with

• Why a “grilling” interview beats letting the agent jump straight to a plan
• The exact mechanic the skill runs — and how to get the most out of a session
• When to reach for /grill-me versus /grill-with-docs
• How /grill-with-docs builds a ubiquitous language (CONTEXT.md) and ADRs as a side effect
• How grilling and Plan mode compose — align first, then gate execution

What a grilling session actually does

Invoke /grill-me (or /grill-with-docs) with a rough idea — anything from a fully-formed spec to a vague hunch — and the agent starts interrogating it. The instruction behind the skill is short and worth reading in full:

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 question before continuing. Asking multiple questions at once is bewildering. If a question can be answered by exploring the codebase, explore the codebase instead.

Three things make it work:

• One question at a time. A wall of ten questions is paralysing; a single sharp question you can actually answer keeps momentum. You reply, it asks the next.
• A recommended answer with every question. It’s not a blank interrogation — the agent proposes what it would do and why, so you’re reacting to a concrete suggestion, not generating everything from scratch. Often you just say “yes.”
• It resolves dependencies in order. Decisions get walked branch by branch, so early answers shape later questions instead of everything landing at once.

Before AI, developers called this rubber ducking — talking an idea through until you’d found every permutation. A real session runs long (often ~45 minutes for a meaty feature) and the output is a rich, shared understanding: your actual intent, the edge cases you hadn’t considered, and answers to the hard questions — all before the agent writes anything.

/grill-me vs /grill-with-docs

Same interview, two homes:

• /grill-me — the general-purpose pressure-test. Use it when there’s no codebase in play: planning a curriculum, thinking through a decision, even drafting a eulogy. It’s a pure thinking tool.
• /grill-with-docs — the engineering version. Use it when you have a codebase. It runs the identical grilling loop but layers in domain modeling: it grounds questions in your actual code and writes documentation as you go.

The rule of thumb is simple: codebase → /grill-with-docs; no codebase → /grill-me.

Install

npx skills@latest add mattpocock/skills

1. Run the installer, then pick the skills you want (grill-me, grill-with-docs) and which agents to install them on.

2. For /grill-with-docs, also select setup-matt-pocock-skills and run /setup-matt-pocock-skills once per repo — it asks where to keep the docs the skill creates (glossary and ADRs).

3. Start a session by typing the command, e.g. /grill-with-docs I want to add subscriptions to the billing module.

Tip

In Claude Code the skill name is the slash command, so /grill-me works the moment it’s installed. In Cursor and Codex you invoke it the same way through the Agent Skills interface.

What /grill-with-docs adds: a ubiquitous language

The second failure mode these skills target is verbosity. Drop an agent into a project and it has to guess at the jargon, so it uses twenty words where one would do. The fix, straight out of Eric Evans’ Domain-Driven Design, is a ubiquitous language: one shared glossary that developers, domain experts, and the code all draw from. /grill-with-docs builds it for you, inline, during the interview:

• Challenges your terms against the glossary. “Your glossary defines ‘cancellation’ as X, but you seem to mean Y — which is it?”
• Sharpens fuzzy language. “You’re saying ‘account’ — do you mean the Customer or the User? Those are different things.”
• Cross-references with the code. If what you say contradicts what the code does, it surfaces the conflict instead of papering over it.
• Writes it down as terms crystallise in a root CONTEXT.md (or a CONTEXT-MAP.md for multi-context monorepos).

The payoff compounds session after session. Once “the cascade where a lesson is given a real spot in the filesystem” has a name, you say “the materialization cascade” — and so does the code. Variables, functions, and files get named consistently, the agent navigates the repo faster, and it spends fewer tokens thinking because the language is tighter.

Caution

CONTEXT.md is a glossary and nothing else — definitions of what terms are, not how anything is implemented. Don’t let it drift into a spec or a scratchpad.

It also offers Architectural Decision Records — one-paragraph notes in docs/adr/ — but sparingly. It only proposes an ADR when all three are true: the decision is hard to reverse, surprising without context (a future reader will wonder “why on earth did they do it this way?”), and the result of a real trade-off. If any one is missing, there’s nothing worth recording.

How it fits with Plan mode

Grilling and Plan mode solve adjacent problems and compose cleanly. A grilling session gates your understanding — it won’t let you move on until every branch of the decision tree is resolved. Plan mode gates your execution — the agent researches in a read-only sandbox and writes a plan you approve before any edit lands.

The trap is reaching for Plan mode first. Claude Code will happily produce a confident, well-formatted plan before you and it actually agree on what you’re building — and a plan built on a misunderstanding just makes the wrong direction look official. Run the grill first:

1. /grill-with-docs to surface and resolve the ambiguity (and capture the vocabulary in CONTEXT.md).
2. /plan to turn that shared understanding into a gated, file-by-file plan.
3. Execute — now the plan is worth approving, because the thinking behind it is sound.

Grilling is what makes Plan mode’s plan trustworthy. Without it you’re often just rubber-stamping a polished guess.

When to reach for it

• Starting a feature whose requirements are still fuzzy in your own head.
• Working in an unfamiliar domain where the terminology isn’t pinned down yet.
• Stress-testing a design you think is finished — to find the edge cases before the agent does.
• Any high-stakes decision, code or not, where talking it through beats deciding alone.

Where to go next

Plan mode The execution gate that pairs with grilling: research in a sandbox, approve the plan, then let it run.

Domain-Driven Design The discipline behind /grill-with-docs -- ubiquitous language, bounded contexts, and modeling the domain.

shadcn/improve Audit with your best model, execute with a cheap one -- the architecture-quality counterpart to grilling.

Installing and managing skills How npx skills add works, and how to keep skills updated across tools.