grill-with-docs and domain-modeling: a glossary and ADRs your agent writes while you talk

grill-with-docs is the version of grill-me for when you're working inside a repository: the same round-based interview, but while you talk the agent maintains a project glossary (GLOSSARY.md) and records hard-to-reverse decisions as ADRs. The discipline that does that work is another skill, domain-modeling, which is why we cover them together. Both come from the mattpocock/skills repository, MIT licensed.

This is part four of the Matt Pocock skills guide. Its author says this technique "might be the single coolest technique in this repo".

The problem: the agent uses 20 words where one will do

At the start of a project, developers and the people they build for speak different languages. Agents have the same problem: they're dropped into a project without its jargon and work it out as they go, so they talk around what the team names in a single word.

The README gives an example from one of the author's projects:

• Before: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)".
• After: "There's a problem with the materialization cascade".

The fix comes from Eric Evans' *Domain-Driven Design*: a ubiquitous language, one vocabulary shared by people, code and now the agent too. The benefits the repository lists:

• Variables, functions and files are named consistently.
• The codebase is easier for the agent to navigate.
• The agent spends fewer tokens thinking, because it has a more concise language.

How they split the work

grill-with-docs is another one-line skill: "call the grilling skill and the domain-modeling skill". The first brings the round-based interview; the second, the vocabulary discipline.

domain-modeling also works on its own. The agent loads it when you discuss the code's terminology or edit a GLOSSARY.md or an ADR.

What domain-modeling does during the session

The SKILL.md defines five active behaviours:

1. Challenge against the glossary. If you use a term that clashes with GLOSSARY.md, it says so on the spot: "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?".
2. Sharpen fuzzy language. Faced with a vague or overloaded term, it proposes a canonical one: "You're saying 'account': do you mean the Customer or the User? Those are different things".
3. Test with concrete scenarios. It invents edge cases to force you to define where one concept ends and another begins.
4. Cross-reference with code. If you say how something works, it checks whether the code agrees: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?".
5. Update GLOSSARY.md on the spot, never batching changes for the end.

And one strict rule: the glossary holds no implementation details. It isn't a spec or a scratch pad. It's a glossary and nothing else.

The GLOSSARY.md format

Each term gets a one- or two-sentence definition and an _Avoid_ line with the synonyms not to use:

# Ordering

Receives and tracks customer orders.

## Language

**Order**:
A customer's request to purchase that the warehouse must fulfil.
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

The format rules: be opinionated (pick one word and send the rest to _Avoid_), keep definitions to one or two sentences, include only project-specific terms (no "timeout" or "cache"), and group under subheadings when families of terms appear.

A normal repository has a single GLOSSARY.md at the root. A monorepo with several contexts has a root GLOSSARY-MAP.md that points to each context's glossary and describes how they relate.

When a decision deserves an ADR

An ADR (Architecture Decision Record) records *that* a decision was made and *why*. They live in docs/adr/0001-slug.md, 0002-slug.md... and can be a single paragraph. domain-modeling only offers one when all three conditions hold:

1. Hard to reverse: changing your mind later has a real cost.
2. Surprising without context: someone will read the code and wonder "why did they do it this way?".
3. The result of a real trade-off: there were alternatives and you picked one for specific reasons.

Examples that qualify: "we use hand-written SQL instead of an ORM because X", "we can't use AWS for compliance reasons", "Ordering and Billing talk via events, not synchronous HTTP". If the decision is easy to reverse or surprises nobody, no ADR.

Real test: rescheduling appointments at a bike repair shop

We created a minimal repository with two TypeScript files and the typical mess of a real project. The code is in Spanish, which matters here: it uses three different words for "appointment" (Turno, Reserva and Cita):

export type Turno = { id: string; clienteId: string; bici: string; fecha: Date; estado: "pendiente" | "confirmada" | "cancelada" };

export function crearReserva(clienteId: string, bici: string, fecha: Date): Turno { /* ... */ }

export function cancelarCita(t: Turno): Turno { /* ... */ }

// Work order: created when the bike arrives at the shop
export type Orden = { id: string; turnoId: string; mecanico: string; repuestos: string[]; total: number };

We ran it in Claude Code 2.1.316 (Sonnet 5.5), with write permission in that folder, with this request in Spanish:

/mattpocock-skills:grill-with-docs I want customers to be able to reschedule their appointment from a link in the WhatsApp confirmation, without calling the shop.

Round 1: vocabulary first

Before asking anything, the agent read the code and spotted three words for the same thing: Turno, Reserva and Cita. Its first question was to pick one:

Q1 - Vocabulary: Cita, Turno or Reserva? The code mixes all three today. Do we keep Cita as the single canonical term (the one the customer uses), rename Turno/crearReserva to Cita, and record it in the glossary?

The second already used the code to question the design: does rescheduling change the same appointment or create a new one, given that an Orden points at turnoId and a new appointment would break that link? Then came reschedulable states, minimum notice, a change limit, link security and availability.

Round 2: the glossary appears

We answered (changing the notice from 24 to 12 hours) and the agent created GLOSSARY.md with four terms: Cita (avoid Turno, Reserva), Reprogramar (avoid "cancel and rebook", "move"), Capacidad diaria (daily capacity; avoid cupo, aforo) and Orden (avoid ticket, trabajo). It deliberately left out the unresolved terms.

Round 2 continued with questions the glossary made sharper: how daily capacity counts when rescheduling, whether an appointment has a time or only a day, what happens with an expired link.

What it did well and what it didn't

• Good: it spotted the vocabulary problem unprompted and made it the first decision.
• Good: it created no ADR. No decision in these two rounds met all three conditions.
• Could be better: the definition of Capacidad diaria included the value "(8)". That's a configuration value, exactly what the skill forbids in the glossary. Review GLOSSARY.md in every commit as you'd review code.

Cost of the two rounds: 0.24 USD.

grill-with-docs vs grill-me

The author is blunt: in a working directory, grill-with-docs is strictly better.

How it fits with the other skills

The glossary outlives the session. tdd, diagnosing-bugs, to-spec, to-tickets, triage and pr read GLOSSARY.md to name tests, tickets and PRs with the same vocabulary. wait-what uses it to re-explain something you didn't follow. The earlier the glossary exists, the more the other skills deliver.

Common mistakes

• Using the glossary as technical documentation. No paths, config values or implementation decisions.
• Asking for an ADR for everything. If the decision can be reversed in an afternoon, it doesn't need a record.
• Not granting write permission. Without Write or Edit, the agent runs the interview but can't save the glossary.
• Forgetting _Avoid_. It's the part that keeps synonyms from creeping back.

FAQ

Do I need to create GLOSSARY.md first? No. It's created when the first term is resolved, and docs/adr/ when the first ADR is needed.

Can the glossary be in another language? Yes. The format uses English headings (## Language, _Avoid_), but terms and definitions follow the project's language, as in our Spanish test.

What about an old CONTEXT.md? Earlier versions used that name. /setup-matt-pocock-skills offers to rename it to GLOSSARY.md.

Next step

Run /grill-with-docs on your next change and review the GLOSSARY.md it leaves behind. In part 5 of the guide we turn the outcome of a grilling session into executable work with to-spec and to-tickets.