# Grill With Docs

> A relentless interview to sharpen a plan or design, capturing decisions in this repo's canonical homes as they land. Use when the user wants to stress-test a design and record what comes out of it.

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

---


Run a `/grilling` session over the plan or decision at hand, then capture what
crystallises where it belongs. Capture inline, as each decision lands — not
batched at the end.

## Where things land in this repo

**Hard-to-reverse decisions with a real trade-off → write the ADR now.**
`project-docs/adr/`, shape and bar in [`.claude/rules/adr.md`](../../rules/adr.md).
Read that rule before writing one; it is stricter than the generic advice
(sequential numbering, supersede rather than edit, and a `TestADR_NNNN_*` test
when the decision is one a test can pin).

**Format or vocabulary changes → flag them, do not write them.** A new schema
key, a renamed concept, a changed definition: note it for the implementing
change and move on. Format vocabulary lives in three places that are checked
against each other — `internal/schema/v1/modelith.schema.json`,
`internal/model/model.go` (guarded by `TestSchemaStructSync`), and
`docs/06-schema-reference.md` — plus the golden `examples/`. Editing one of
them mid-grilling leaves the repo failing `task check` with the design still
half-argued.

**Running state → `HANDOFF.md`** at the end of the session (gitignored,
local-only; see `CLAUDE.md`).

## This repo has no CONTEXT.md, deliberately

The upstream version of this skill maintains a `CONTEXT.md` glossary. Don't
create one here. modelith's domain *is* the domain-model format, and that
vocabulary is already defined in the schema, the Go structs, and the schema
reference — two of which a test holds in sync. A `CONTEXT.md` would be a fourth
copy that nothing checks.

For the same reason, don't propose modelling modelith in `*.modelith.yaml`.
It would drift from the enforced definitions and compete with `examples/` for
the worked-example job.

## During the session

Beyond the interview itself, the angles worth pressing:

- **Sharpen fuzzy language.** When a term is vague or overloaded, propose a
  precise canonical one. Two names for one concept, or one name for two, is the
  bug that this whole tool exists to catch — don't let it pass in our own
  design conversation.
- **Stress-test with concrete scenarios.** Invent cases that probe the edges
  and force precision about where one concept stops and the next starts.
- **Cross-reference against the code.** When a claim is made about how modelith
  behaves, check it. The linter, the renderers, and the schema are right here;
  a contradiction between what we believe and what the binary does is a finding.
- **Probe emission frequency.** When the design emits something observable — a
  lint diagnostic, a log line, a rendered element — pin down how often it fires:
  once per model, per entity, or per attribute? A diagnostic that turns out to
  fire per attribute is a wall of output, and usually belongs on a different
  surface.