---
name: grill-agent-with-docs
description: Agent-to-agent grilling of a Markdown spec that also writes the paper trail — glossary terms into CONTEXT.md and hard one-way decisions as ADRs — as the interview runs. Use when a spec needs relentless refinement by an agent standing in for the product owner AND the resolved vocabulary and decisions must survive the session. Trigger on "grill agent with docs", "grill this spec with an agent and write ADRs", "agent grilling with glossary".
disable-model-invocation: true
---

# grill-agent-with-docs

Run a **`grill-agent`** session — the full agent-to-agent interview, with a second agent CLI in a
visible tmux pane standing in for the product owner — following the **`grill-with-docs`** skill
throughout, so the alignment leaves a paper trail instead of evaporating when the pane closes.

Two files govern this, and both are read before starting:

- `~/.claude/skills/grill-agent/SKILL.md` — the agent-in-the-loop machinery: setup questions,
  interviewee brief, one-question-at-a-time flow, answer handling, stop condition, and leaving
  the pane open at the end.
- `~/.claude/skills/grill-with-docs/SKILL.md` — **the source of truth for the interview and the
  documentation discipline**: domain awareness, challenging terms against the glossary, sharpening
  fuzzy language, concrete-scenario stress tests, cross-referencing code, updating `CONTEXT.md`
  inline, and the three-part test for offering an ADR. Its `CONTEXT-FORMAT.md` and `ADR-FORMAT.md`
  are the formats to use.

This skill changes only *who answers* — never how the questions are asked or how the docs are written.

## What changes when the interviewee is an agent

`grill-with-docs` already carries the documentation rules — glossary challenges, inline
`CONTEXT.md` updates as terms resolve, lazy file creation, and the sparing three-part ADR test.
Apply them exactly as written. What an agent interviewee adds is one hazard:

- **The interviewee is a source of vocabulary, not the author of it.** Terms come from the
  project's own words as evidenced in the repo and the spec. When the interviewee coins a term,
  check it against existing code and docs before canonising it — a plausible-sounding new term
  that contradicts established naming makes the glossary worse, not better.

## Writing discipline

Use the formats in `~/.claude/skills/grill-with-docs/CONTEXT-FORMAT.md` and `ADR-FORMAT.md`. Two
rules matter most here, because an agent interviewee will happily generate volume:

- **A term earns its entry by being contested.** If nobody was confused about it, it does not need
  canonising. Glossary bloat destroys the glossary's value.
- **Never let the interviewee rubber-stamp an ADR.** An ADR records a trade-off that was actually
  argued. If the decision arrived without tension, it is a normal decision — it belongs in the
  spec, not in `docs/adr/`.

## Output

As `grill-agent`, plus: name every file written or amended — each `CONTEXT.md` term added and each
ADR created — in the final report, so the human can review the paper trail in one pass.