# Grill With Docs

> Domain-driven grilling session that challenges a plan against the project's language, sharpens terminology, and writes documentation inline as decisions crystallise. Use when the user wants to stress-test a plan against domain language, says "grill with docs", "sharpen terms", "challenge against domain", or wants a grilling session that produces glossary updates and ADRs as it goes.

- Skill: `tovrleaf/grill-with-docs` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add tovrleaf/grill-with-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tovrleaf/grill-with-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tovrleaf (https://skillmd.com/u/tovrleaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tovrleaf/grill-with-docs

---


# Grill With Docs

Interview the user relentlessly about their plan while
maintaining domain documentation inline. Walk down each
branch of the design tree, resolving dependencies between
decisions one by one.

## Workflow

1. **Read the artifact** — Read the plan, spec, or design.
   Understand the full scope before asking anything.

2. **Explore the codebase** — Before asking questions, look
   for existing documentation:
   - `docs/context/GLOSSARY.md` — domain language
   - `docs/context/CODEBASE.md` — context boundaries
   - `docs/adr/` — existing architectural decisions
   - Code patterns related to the plan's domain

3. **Interview one question at a time** — Ask exactly ONE
   question per message. Never combine multiple questions
   in a single response, even if they seem related. For
   each question, state YOUR recommended answer first.
   Wait for the user's response before asking the next
   question. If a question can be answered by exploring
   the codebase, explore instead of asking.

4. **Challenge against the glossary** — When the user uses
   a term that conflicts with `GLOSSARY.md`, call it out:
   "Your glossary defines 'X' as Y, but you seem to mean
   Z — which is it?"

5. **Sharpen fuzzy language** — When the user uses vague or
   overloaded terms, propose a precise canonical term.
   "You're saying 'account' — do you mean the Customer or
   the User?"

6. **Discuss concrete scenarios** — Stress-test domain
   relationships with specific scenarios that probe edge
   cases and force precision about boundaries.

7. **Cross-reference with code** — When the user states how
   something works, check whether the code agrees. Surface
   contradictions: "Your code does X, but you just said
   Y — which is right?"

8. **Update GLOSSARY.md inline** — When a term is resolved,
   update `docs/context/GLOSSARY.md` immediately. Do not
   batch. Create the file lazily if it doesn't exist. See
   [glossary-format.md](references/glossary-format.md).

9. **Update CODEBASE.md if needed** — When context
   boundaries or relationships are clarified, update
   `docs/context/CODEBASE.md`. Create lazily. See
   [codebase-format.md](references/codebase-format.md).

10. **Offer ADRs sparingly** — Only when all three criteria
    in [adr-criteria.md](references/adr-criteria.md) are
    met. When warranted, explicitly state "Delegating to
    create-adr" and activate the `create-adr` skill to
    handle format, numbering, and file placement. Do not
    write ADR files directly.

11. **Continue until covered** — Keep going until all
    branches are resolved. Do not stop early.

12. **Summarize and offer to apply** — Summarize decisions
    made, then ask: "Want me to apply these changes to
    [artifact name]?"

## Boundaries

**DOES:**
- Interview relentlessly about a plan or design
- Update GLOSSARY.md inline as terms are resolved
- Update CODEBASE.md when boundaries are clarified
- Delegate to create-adr when ADR criteria are met
- Cross-reference claims against code

**Does NOT:**
- Implement code changes
- Create ADRs directly (delegates to create-adr)
- Replace grill-me for quick artifact reviews
- Modify files without resolving terms first

## Common Failures

- **Batching glossary updates** — write terms as they're
  resolved, not at the end. Users forget context.
- **Creating ADRs too eagerly** — most decisions don't
  need one. Apply the three-gate test strictly.
- **Accepting vague terms** — "the service handles it"
  is not precise. Push until the term has a one-sentence
  definition and an _Avoid_ list.
- **Bundling multiple questions** — NEVER ask two questions
  in one message. If you have a follow-up, wait for the
  answer first. One message = one question. Always.
- **Writing ADRs directly** — When an ADR is warranted,
  you MUST say "Delegating to create-adr" and hand off.
  Do not write the ADR file yourself. The create-adr skill
  owns the format, numbering, and lifecycle.