Lesson 2 · Failure mode #2: verbosity

Give the agent a shared language

An agent dropped into your project speaks a different language than you do. It uses twenty words where one would do, re-learns your jargon every session, and burns tokens guessing at what you mean. The fix is a single glossary file. Matt calls it the coolest technique in the repo, and it is one short document.

The problem, made concrete

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model. Eric Evans, Domain-Driven Design

You and the agent start every project speaking past each other. You say "the account", the agent hears something different than you mean, and the gap shows up in variable names, in questions it keeps re-asking, in long-winded explanations. Matt's example from his own repo:

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

Same meaning. One word instead of a sentence, every session, forever. That compression is the payoff.

Three compounding benefits A shared language does more than shorten sentences. Variables, functions, and files get named consistently from it, so the codebase becomes easier for the agent to navigate. And the agent spends fewer tokens thinking, because it reasons in one precise word instead of a paragraph.

The fix: CONTEXT.md, a glossary and nothing else

One file at the repo root. It defines the terms specific to your project. The format is deliberately tiny:

# {Context Name}

One or two sentences on what this context is.

## Language

**Order**:
A confirmed request from a customer to buy goods.
_Avoid_: Purchase, transaction

**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account

Four rules decide what goes in, and they are stricter than they look:

Be opinionated. When several words mean the same thing, pick one and list the rest under _Avoid_. The _Avoid_ list is half the value: it kills synonym drift.
Define what it IS, not what it does. One or two sentences. No behavior, no implementation.
Project-specific terms only. "Timeout", "retry", "error type" are general programming concepts. They do not belong even if you use them constantly. Ask: is this unique to this project's domain? Only then add it.
It is a glossary, not a spec. No implementation details, no decisions, no scratch notes. The instant it becomes a design doc it stops working.

grill-with-docs: build it while you align

You do not write CONTEXT.md by hand in one sitting. You grow it during grilling. /grill-with-docs is Lesson 1's grilling loop plus the domain-modeling skill running alongside it. As you talk, the agent actively does four things:

Challenges against the glossary. "Your glossary defines cancellation as X, but you seem to mean Y. Which is it?"
Sharpens fuzzy language. "You said account. Do you mean the Customer or the User? Those are different things."
Stress-tests with scenarios. Invents edge cases that force you to be precise about where one concept ends and another begins.
Cross-references the code. "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"

When a term resolves, it writes it into CONTEXT.md right then, not batched at the end. The glossary is a byproduct of getting aligned, which is why this feels free.

ADRs: capture the why, sparingly

The same session can produce Architecture Decision Records: a dated one-paragraph note in docs/adr/ saying what you decided and why. The discipline is in not writing most of them. Offer an ADR only when all three are true:

Hard to reverse (changing your mind later is expensive).
Surprising without context (a future reader will wonder "why on earth did they do it this way?").
The result of a real trade-off (there were genuine alternatives).

Easy to reverse? Skip it, you will just reverse it. Not surprising? Nobody will wonder. No real alternative? Nothing to record. ADRs stop the next engineer (or the next agent) from "fixing" something you did on purpose.

Check yourself

Which of these belongs in CONTEXT.md?

When should the agent offer to write an ADR?

What does /grill-with-docs add over plain /grill-me?

Do this now (your one win)

Pick one real project with its own jargon. A strong candidate in your world: the DuckyCutz VAPI work, or bobe-dashboard, both thick with domain terms (relay, squad, lens, cadence, location, calendar). Then:

In that repo, run /grill-with-docs on a change you actually want to make, or just say "build a CONTEXT.md glossary for this project, grill me on the fuzzy terms".
Let it challenge you on overloaded words. When it asks "do you mean X or Y?", give it the precise answer and let it write the term in.
Aim for 5 to 8 real terms, each with a tight definition and an _Avoid_ list. Resist adding general programming concepts.
If a genuinely hard-to-reverse decision comes up, let it write one ADR. Notice how many candidate decisions fail the three-part test.

Report back: which term turned out to be overloaded (meaning two different things), and what did you split it into? That is the misalignment a glossary prevents, and it becomes your next learning record.

Primary source · read this
domain-modeling/SKILL.md plus the "way too verbose" section of the README. For a real example, read this repo's own CONTEXT.md (Issue tracker / Issue / Triage role).

Your teacher is here Want me to grill you on a real project's vocabulary right now and draft its CONTEXT.md with you? Just ask. Or: "show me a CONTEXT.md for rejiglabs" and we will build one live.