Grill With Docs

grill-with-docs

A grilling session builds and defends shared understanding. Precise shared vocabulary is the highest-leverage investment in an agent-driven repo - it's how you and the agent stop talking past each other and how the agent stays consistent across sessions. This skill is the antidote to silent definition drift.

> Credit: the original grill-with-docs skill is by Matt Pocock > (mattpocock/skills). > This version keeps his protocol and adds a lived-experience layer (the discipline rules, the > grilling-vs-executing boundary, the standalone fallback) from running it across real repos.

> Read [LIVED-EXPERIENCE.md](./LIVED-EXPERIENCE.md) before a serious grill. This SKILL.md is > the protocol; the lived-experience doc carries the discipline rules (grep-first, analytical-vs- > operational, confabulation ledger), the grilling-vs-executing mode boundary, and a standalone > domain-modeling fallback for runtimes without a /domain-modeling skill. The protocol is ~20% of > the value; that doc is the other 80%.

This is a GRILLING session, not an executing one

The human's input is the important signal here. Default to "ask, don't ship." Do not let an execution-shaped habit push an unmade decision into a doc or into code. The autonomy rule (run approved work without re-asking) does NOT apply here.

Procedure

1. Read the actual docs first. Before asserting what the model says, grep/read the glossary,

relevant ADRs, and PRODUCT.md. Cite what you find. Never reconstruct the model from memory - that's how confabulation enters the record. If you can't find it, say "this isn't documented" rather than inventing it.

1. Challenge the plan/concept against the documented model. For every domain term the human

used, ask:

• Is this the same term already defined in the glossary, or a new sense of it? If new, that's

a collision - resolve it (rename, or redefine deliberately).

• What is its cardinality / relationship to the other terms? (one-to-many? a subtype? a

synonym?)

• Does it contradict a documented decision (an ADR)? If so, surface the conflict - either the

plan is wrong or the ADR needs superseding.

1. Find the ambiguities. Where could the human and the agent reasonably read the same word two

ways? Name each one explicitly and ask. These are the future bugs.

1. Crystallize decisions into the substrate, in this session. When a definition or relationship

settles, write it:

• New/sharpened term → the glossary (strict format: definition + cardinality to other terms,

NO implementation detail - that rots).

• A real, hard-to-reverse trade-off that got decided → a short ADR (docs/adr/NNNN-*.md).
• Get explicit human sign-off before writing each one.

1. Keep a flagged-ambiguities ledger. Anything left unresolved goes on a list (in the session

notes or the glossary's "open questions") to drain at the next grill. Don't force-resolve; record and move on.

Output

• Glossary entries added/sharpened (with sign-off).
• ADR(s) for any decided trade-off.
• A short list of ambiguities surfaced and where each landed (resolved → which doc; unresolved →

the ledger).

Why it matters

Most "bugs" in an agent-driven system aren't logic bugs - they're a term that meant one thing to the human and another to the agent, or a definition updated in one place and not the others. Grill early (before building on a term) and the whole downstream chain stays coherent. See cross-system-audit for propagating a vocabulary change once it's settled.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chrismccann-dev
• Source: chrismccann-dev/agent-bootstrap-kit
• License: MIT

Install and usage instructions live in the source repository linked above.