Grill-with-Docs: Make Your AI Agent Question Your Plan Before Writing Code

You tell your AI Agent to build a feature. It works for a day. You look at the result — it’s not what you wanted.

Not a bug. Not a performance issue. A fundamental misunderstanding. You thought the Agent understood your business logic. It thought you were talking about something else entirely. This misalignment isn’t an edge case. It’s the default state of AI coding.

Matt Pocock’s skills repository has 120k stars, but the most important skill isn’t a code generator or a testing framework. It’s called grill-with-docs — and its job is simple: before you write a single line of code, it forces you to think through every design decision with a series of pointed questions.

The Problem Isn’t the Agent, It’s the Communication

Most AI coding failures stem from one basic issue: you and your Agent lack a shared language.

In your head, there’s a domain model — what “user” means, what “cancellation” implies, where the boundary of “order complete” lies. In the Agent’s head, there’s a different model — it guesses from your code, from your README, from your prompt. When the two models don’t align, the code diverges.

grill-with-docs takes an counterintuitive approach: it doesn’t let the Agent write code. Instead, it makes the Agent ask you questions. One at a time, branch by branch, until the entire design tree is traversed.

How It Works

grill-with-docs is an engineering skill from Matt Pocock’s skills repository. After installation, you trigger it in a session and it:

1. Explores your codebase first — if an answer can be found in existing code, it looks instead of asking you
2. Challenges your plan against your domain model — you use a term, it checks CONTEXT.md to see if it conflicts with an existing definition
3. Stress-tests design decisions with concrete scenarios — not “how would you handle edge cases” but “user A performs action Y on order B in state X — what happens”
4. Updates CONTEXT.md and ADRs in real time — terms get recorded the moment they’re clarified, no post-mortem summaries

CONTEXT.md is a pure glossary. No implementation details. It only records what you and the Agent agreed on about domain concepts.

/
├── CONTEXT.md          ← domain glossary
├── docs/
│   └── adr/            ← architectural decision records
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

Why Question Before Building

This sounds slow. But compare it to the normal flow:

Without grill-with-docs: You describe the requirement → Agent understands (possibly wrong) → Agent writes code → You spot the misalignment → You correct → Agent rewrites → You spot another issue → Correct again → Rewrite again. Three or four rounds per feature is normal.

With grill-with-docs: Agent asks you 20-40 questions → You answer each one → Terms and decisions get recorded → Agent starts coding → gets it right the first time.

The former looks faster because the questioning phase produces no code. But the latter eliminates all rework.

Matt Pocock puts it bluntly:

“The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they’ve built — and you realize it didn’t understand you at all.”

This logic holds in the AI coding era, and it’s even more critical. Human developers can catch misalignment in code review. AI Agents won’t proactively question your requirements.

When to Use It

grill-with-docs isn’t needed for every interaction, but it delivers massive value in these scenarios:

• New feature design: Clarify edge cases, data flows, and error handling before writing code
• Refactoring existing modules: Agent reads your code and docs first, confirms it understands current behavior before touching anything
• Multi-module changes: When a change touches multiple modules, questioning exposes dependencies and contracts between them
• Team shared context: If multiple people use the same Agent, CONTEXT.md becomes the single source of truth

What It’s Not Good At

• Small changes: Renaming a variable, tweaking a parameter — 30 rounds of questioning is overkill
• Exploratory prototyping: If you want the Agent to try a few directions and see what sticks, questioning slows you down
• Blank-slate projects: No codebase to explore, no existing terminology to reference — grill-with-docs has less to work with
• Quick validation: When you’re spinning up a 5-minute proof of concept, you don’t need ADRs

Installation

One-line install across 30+ agents:

npx skills@latest add mattpocock/skills --skill grill-with-docs

After installation, run /setup-matt-pocock-skills to configure your issue tracker and label vocabulary.

The Real Output

The most powerful thing about grill-with-docs isn’t the questions it asks — it’s what it produces: a living, evolving domain model document.

Imagine you’re designing a cancellation flow for an e-commerce system. In a normal conversation, you might say “users should be able to cancel orders” and the Agent implements it its own way. grill-with-docs will ask:

• “Is this a partial cancellation or a full order cancellation?”
• “Can shipped orders be cancelled?”
• “How does inventory roll back on cancellation?”
• “Is the refund immediate or asynchronous?”
• “Do user-initiated and merchant-initiated cancellations follow the same flow?”

Every answer updates CONTEXT.md. Next time you or your team mention “cancellation,” everyone (including the Agent) uses the same definition.

The effect of this shared language is compounding. Every conversation improves the domain model. Every subsequent conversation starts from a higher baseline.

A Real Usage Example

Imagine you’re adding a “team invitation” feature to a SaaS project. You trigger grill-with-docs, and the conversation goes like this:

You: I want to add a team invite feature. Users should be able to invite others to join their team.

Agent: Let me look at your codebase first. You already have Team and Member concepts. Does “invite” mean sending a link that lets strangers register and auto-join, or does it send an invitation that becomes a Member only after acceptance?

You: Send an invitation first, they become a Member after accepting.

Agent: Got it. How long does an invitation stay valid?

You: 7 days.

Agent: Is there a limit on how many pending invitations a team can have?

You: No hard limit, but I’d warn the team admin if it goes over 50.

Agent: Noted. If a team already has 5 pending invitations and you send a 6th, do you reject or override the oldest?

You: Allow them to coexist. No override needed.

Agent: After acceptance, what role does the new member get?

You: Default is member. The team admin can specify a role when sending.

Agent: If the invitation link leaks and someone uses it on day 8, what happens?

You: Expired. Should reject.

Agent: One more: if the sender’s team permissions get revoked, do their already-sent invitations remain valid?

You: Yes. Once sent, the invitation is independent of the sender.

Agent: Last one: what if two people invite the same email at the same time?

You: Merge into a single invitation record. No duplicates.

The conversation ends. The Agent asked 9 questions. Not a single line of code was written. But CONTEXT.md is now updated:

## Invitation

- **Definition**: A credential sent to unregistered users to join a team, becomes a Member only after acceptance
- **Validity**: 7 days, expired invitations cannot be accepted
- **Role**: Specifiable at send time, defaults to member
- **Independence**: Once sent, the invitation is independent of the sender — sender permission changes don't affect existing invitations
- **Dedup**: Duplicate invitations for the same email are merged

Then you tell the Agent to start coding. It implements based on the definitions in CONTEXT.md. No more “expired invitations still work” or “duplicate invitations sent to the same email” bugs.

One Thing to Take Away

Code can be rewritten. Misunderstanding costs ten times that to fix.

Asking first isn’t slow. It’s fast. Next time you ask your Agent to build something, try making it question you first.

GitHub: https://github.com/mattpocock/skills | skills.sh: https://skills.sh/mattpocock/skills/grill-with-docs