# /grill-with-docs: Plan interviews that build a project glossary

Source: https://trendhub.net/skills/mattpocock-skills/grill-with-docs
Skill folder: https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs
Pack: Skills for Real Engineers (https://trendhub.net/skills/mattpocock-skills)
Works with: Claude Code, Codex, GitHub Copilot, Gemini CLI, Cursor, OpenCode, Windsurf, Amp and others

The grill-with-docs skill runs a structured interview about a plan or design and, during the same session, records agreed terms in GLOSSARY.md and significant decisions as ADRs. It combines the pack's grilling and domain-modeling skills, so you leave with both a settled plan and shared vocabulary the agent reuses later.

## When to use it

- Before starting any non-trivial change, to make sure the agent understands what you want.
- When a project's jargon is fuzzy and the agent keeps describing things at length.
- When a design choice is hard to reverse and future readers will need to know why it was made.

## How it works

1. **Map the decisions**: The agent treats the plan as a tree of decisions and finds the ones whose prerequisites are already settled.
2. **Ask in rounds**: It asks that whole set of numbered questions at once, each with a recommended answer, then waits for yours.
3. **Look up facts itself**: Questions that depend on facts in the codebase are answered by a sub-agent instead of being put to you.
4. **Sharpen terms**: It challenges vague or conflicting words, tests them with edge-case scenarios and writes resolved terms to GLOSSARY.md.
5. **Record key decisions**: It offers an ADR only for decisions that are hard to reverse, surprising and the result of a real trade-off.

## What it steers the agent away from

- Starting to code before the plan is actually agreed
- Glossaries cluttered with implementation notes
- ADRs written for decisions that did not need one

## What it can touch

Reads your codebase, may dispatch sub-agents to look up facts, and creates or edits GLOSSARY.md and files under docs/adr/ in the repository. It is user-invoked only and does not run your code.

## Pairs well with

- `/grill-me`
- `/to-spec`
- `/domain-modeling`
- `/improve-codebase-architecture`

## Questions

### How is grill-with-docs different from grill-me?

grill-me only runs the interview and suits non-code topics. grill-with-docs adds domain modeling, so it also maintains a glossary and ADRs in your repo.

### Does the agent start implementing after the interview?

No. The session ends when every decision is resolved, and the agent waits for you to confirm shared understanding before acting.
