grill-with-docs: make the AI stop nodding along and grill your plan first

30-second TL;DR · no time for the whole thing? grab these

The problem: the AI is too agreeable. Hand it a half-baked plan → it writes code → your confusion ships with the project.

grill-with-docs does the opposite: it grills you. Uses your project’s CONTEXT.md glossary + source to poke holes in your plan, one by one.

How it grills: one question at a time, recommended answer first; reads the code instead of asking when it can; a term gets settled → into CONTEXT.md; a hard-to-reverse decision → an ADR.

Install: npx skills@latest add mattpocock/skills · Use: “grill my plan with grill-with-docs: ”

Best for: adding a complex feature to a mature project where a few words mean different things to different people. Don’t bother: empty repo / trivial change / expecting it to write the code for you.

1. An agreeable AI is a hidden liability

The most dangerous thing about pair-programming with an AI is that it almost never pushes back.

You toss it a half-baked plan — “add a feature: let users cancel a few items from an order, then refund them” — and it doesn’t blink: “Sure!” and the code pours out. But that one sentence is full of things you never pinned down, and it asked about none of them: is “cancel” before or after shipping? Whose job is the refund? Is it the same thing your codebase already calls a cancellation? It doesn’t ask. It just assumes for you, and bakes those assumptions into the code.

Three weeks later you find out that one word, “cancel,” means three different things to product, to your code, and to the database. The codebase is mush.

It’s not that the AI isn’t smart. It’s that it wants to help so badly it won’t stop to make you think.

grill-with-docs does the reverse: it stops the AI from nodding along and grills your plan first (to grill is to interrogate, to put over the fire). Until the words are sharp, you don’t move on.

2. How it works: an interview that remembers your project

The mechanism in one line: it uses your project’s own language and decisions to grill your new plan.

A few specifics (the author split this behavior into two skills, grilling and domain-modeling — more below):

One question at a time, recommended answer first. It walks your plan’s decision tree branch by branch, and every question leads with “I’d go with this, because…” — instead of dumping a twenty-item questionnaire on you.

If it can read the code, it won’t ask you. Anything a quick look at the source can answer, it looks up itself.

It holds you to the glossary. That CONTEXT.md in your project root is its ruler. Say a word that doesn’t match the definition and it stops you cold: “Your glossary says ‘void’ means X, but you clearly mean Y — which is it?”

Fuzzy words get sharpened. Say “account” and it asks: “Do you mean the Customer or the User? Those are two different things.”

It cross-checks against the code. Claim a feature works a certain way and it reads the code to verify; if they don’t match, it points it out: “The code voids the whole order, but you just said partial — which one counts?”

Once a term is settled, it goes straight into CONTEXT.md. No batching, no “later.”

Only a hard-to-reverse decision earns an ADR. It’s stingy with ADRs (architecture decision records): it proposes one only when all three hold — hard to reverse, confusing without context, the result of a real trade-off.

This is really domain-driven design’s two serious habits — ubiquitous language and leaving a decision trail — folded into a conversation you can’t wriggle out of.

One change worth knowing: it’s actually two skills bolted together. Matt split grill-with-docs into grilling (the relentless interview) and domain-modeling (the glossary + ADR discipline), leaving grill-with-docs as a thin shell whose body is one line: “run /grilling, using /domain-modeling.” Nothing about the behavior changed, but you can use the halves on their own: just want the grilling, /grilling; just want to maintain the glossary and ADRs, /domain-modeling; want both — that’s grill-with-docs.

3. Getting started: install it, then hand it a plan

Install. It’s in mattpocock/skills — one official command, tick grill-with-docs when prompted:

npx skills@latest add mattpocock/skills

Because of that split, grill-with-docs now needs grilling and domain-modeling to be whole, so tick all three (or use the latter two directly). Already cloned the repo? Copying those directories into your project’s .claude/skills/ works too.

Feed it. Stop saying “implement X for me.” Say this instead:

Grill my plan with grill-with-docs: <drop in the plan you haven’t fully thought through>

Note: it’s tagged disable-model-invocation, so it won’t surface on its own — you have to call it by name (or type /grill-with-docs) to start it. Then brace yourself: it won’t agree with you, it’ll start asking.

The first real result is usually its first question: something you thought you’d figured out, and one question in, you realize you hadn’t. Here’s a run I actually did.

4. Watch a real grilling

I set up a small project for it to grill, with a trap baked in on purpose. The project already had a CONTEXT.md:

**Cancellation**:
An order is voided in full before shipping; stock returns to inventory as-is. No refund flow is involved.
_Avoid_: Refund, Return

The code in src/orders.ts plays it straight too: cancelOrder() only voids whole orders, only before shipping, never touches money.

Then I handed it the plan (the one from the top): “Let users cancel a few items from an order (not the whole thing), then refund the money for those items.”

It read the code and the glossary, and its first line wasn’t “Sure” — it was:

Before we start, two terminology conflicts need flagging.

Your “cancel a few items and refund” collides with two existing definitions:

CONTEXT.md defines Cancellation = full-order void + no refund flow. You’re describing a partial cancellation, with a refund — both clash.

The glossary’s _Avoid_ list explicitly rules out the word “Return.”

So the action you’re describing has no existing word. We need to name this new concept before we go on.

I genuinely hadn’t noticed: the “cancel” in my sentence and the Cancellation already pinned down in the project were not the same thing. It didn’t just catch it — it went and read the code:

The current cancelOrder at src/orders.ts:3 only allows orders with status === "PLACED". Your “cancel a few items” — before shipping only, or after as well?

My recommendation: before shipping only. Post-shipping returns are a returns flow in business terms, an order of magnitude more complex… ship the before-shipping path first; the boundary is cleanest.

I answered “agreed, before shipping only.” Then it did something more important — it named the nameless concept and wrote it straight into the glossary:

Partial Cancellation: before shipping, remove some (not all) line items from an order; the removed items’ stock returns to inventory. No refund flow involved. _Avoid_: Partial refund, Partial return, Item cancellation

This one it actually wrote into the CONTEXT.md file, not just in chat. The refund half it explicitly pushed away: “That belongs to Billing — not written here.”

Grilling on toward the boundaries, it paused to decide whether to leave a trail, then actually generated an ADR:

Landed an ADR at docs/adr/0001-partial-cancellation-no-refund.md: “Partial Cancellation does not trigger a refund; refunds are left entirely to the Billing context. … The alternative was to trigger the refund inside Ordering, making ‘cancel + refund’ one atomic operation — we rejected it because it would make Ordering depend on Billing’s internals and break the existing context boundary.”

The best part is its next question, which cited the very ADR it had just written:

Question 3 / How does Billing know to refund? The current cancelOrder emits no event at all (src/orders.ts:7).

A. Emit a domain event; Billing subscribes and refunds.

B. Ordering calls Billing’s refund API directly.

C. Emit nothing; let the caller wire it up.

My recommendation: A. Option B makes Ordering depend on Billing directly — exactly what ADR 0001 rejected.

Sit with that loop: it made me sharpen a word → wrote it into the glossary → recorded a boundary decision as an ADR → then used that ADR to block a later option that would have broken the boundary. It’s using the language you just built together to guard every step that follows. That’s what “an interview that remembers your project” means.

5. Its temperament: when to use it, when not to force it

It’s bracing, but it’s not a cure-all and not always the right call:

It needs something to grill. With a CONTEXT.md and some code, it has material to hold you to and cross-check against. In a brand-new empty repo it’ll build a glossary from scratch (still useful), but nowhere near as sharp as poking holes using the language you already have. So it’s best for adding to a project that’s already grown up.
It sharpens clarity, not code. A grilling leaves you with sharpened terms, a few ADRs, a plan you’ve actually thought through — not a pile of implementation. Writing code is the next step, after you’re clear; don’t expect it to do that for you.
Don’t grill the trivial stuff. A button color, a throwaway field — force it through the process and it’ll dutifully play along, pure waste. Its value is where a fuzzy word breeds endless trouble: domain concepts, context boundaries, places where a few ideas get tangled. A sledgehammer on a fly: the fly’s fine, you’re tired.
It’s stingy with ADRs — that’s a feature, don’t resent it. It records one only when all three hit: hard to reverse, confusing later, a real trade-off. When you catch yourself wishing it logged more, ask: do you actually need the trail, or do you just want the ceremony of completeness? More ADRs isn’t better; recording the ones that matter is.

In a line: adding a complex feature to a mature project, with a nagging sense that “some words mean different things to different people” — turn it on. That’s its home turf.

6. Cheat sheet

Install: npx skills@latest add mattpocock/skills   # tick grill-with-docs at the prompt
Grill:   tell the AI "grill my plan with grill-with-docs: <plan>"

What it does:
  one question at a time, recommended answer first
  reads the code instead of asking when it can
  holds you to the CONTEXT.md glossary; stops you when a word doesn't match
  sharpens fuzzy words ("account" = Customer or User?)
  cross-checks against the code; flags mismatches
  term settled -> written straight into CONTEXT.md (glossary, no implementation details)
  hard-to-reverse decision -> an ADR (docs/adr/, only if all three criteria hit)

CONTEXT.md: glossary only — a line or two per term, the word to use + _Avoid_ the ones to skip
ADR's three tests: hard to reverse + confusing without context + a real trade-off (miss one, skip it)

Best for: adding a complex feature to a mature project where "some words mean different things to different people"
Don't bother: empty repo / trivial change / expecting it to write the code for you

7. Further reading

The source: grill-with-docs (MIT), plus the two it split into, grilling and domain-modeling. The glossary and ADR format guides now live in domain-modeling: CONTEXT.md format, ADR format — both worth a read.
Want to go deeper? Look up ubiquitous language and ADR (Architecture Decision Record) in domain-driven design (DDD) — grill-with-docs is just a lightweight shell that makes both effortless.
Like this “collaborate with the AI from a different angle” trick? Last time we took apart caveman (make the AI shut up and just say the thing) — a perfect pair: one makes it cut the filler, the other makes it ask the hard questions. The series will keep taking apart other skills from Matt’s repo.

This is original teaching content from usesuperpowers.com. The grill-with-docs skill it covers comes from mattpocock/skills (source_commit: 6eeb81b), used under its MIT license. The grilling session shown is a real run (incidental details elided); the original skill’s rules remain the copyright of their author; our breakdown, demo, and writing are original.

On versioning: This article is based on 6eeb81b. In this version Matt split the single grill-with-docs into two skills, grilling + domain-modeling, with grill-with-docs becoming the entry point that combines them; the behavior described and the real grilling above are unaffected — there’s just an extra “you can use the halves separately” layer.