Clarify a design through an interview while capturing project terminology and important decisions for later development.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill grill-with-docs --skill grilling --skill domain-modeling --skill setup-matt-pocock-skills --agent claude-code
For Codex, replace claude-code with codex in the command and /grill-with-docs with $grill-with-docs in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:grill-with-docs instead; avoid installing the same skills twice.
This entry point combines grilling and domain-modeling, so install all three with the file-based method. Open the repository and existing glossary and ADRs. Run setup-matt-pocock-skills for initial engineering workflow configuration.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/grill-with-docs
I want team purchases for a paid course. Start with buyers, learners, seats and refunds. Ask the decisions that constrain later choices first and record terminology as we settle it.
Work through the task
Start with consequential choices
Team purchasing involves more than a quantity field. Decide who pays, who occupies a seat and whether seats transfer before discussing invitation emails. Answer numbered questions in order. Where you are unsure, explain your constraints and ask for a recommendation with consequences.
Capture vocabulary as it settles
When buyer and learner are established as different roles, capture both definitions in CONTEXT.md. If later discussion uses the ambiguous word user, identify which role it means. A shared vocabulary gives specifications, variable names and test scenarios the same reference point.
Record decisions that need a rationale
Refund behavior may involve a lasting trade-off between billing, learner progress and support operations. Such a choice can justify an ADR. Colors and temporary deadlines generally do not. Capturing a decision should support the continuing interview rather than end it prematurely.
Check the result
Finish by reviewing settled rules, unresolved questions and changed documents. Confirm that the important purchasing branches are explained, then use to-spec in the same conversation if you want a specification.
Common questions
It cannot find a supporting skill. Check that grilling and domain-modeling were installed too.
How does it differ from grill-me? This workflow maintains domain vocabulary and decision documents during the interview.
Will it implement the feature? Request implementation separately after the design is settled.
Choose the right size of conversation
If there is no repository and you just want to explore an idea, grill-me is lighter. Grill-with-docs fits a change in an existing repo that can be settled in one session. A project spanning many sessions needs its questions mapped first; one interview should not be expected to settle its entire scope. Point the Skill at the current code, existing vocabulary, and decisions that really need a human. Questions the code can answer should be answered by reading it, not repeatedly sent back to you.
Files are created lazily. The first resolved term creates or updates CONTEXT.md; only a durable tradeoff earns an ADR, so a session with no ADR may be perfectly normal. But if new terms were settled and CONTEXT.md did not change, check whether the companion domain-modeling step actually ran and where it wrote. At the end, inspect the new terms, unresolved questions, and changed files. A fluent conversation summary alone is not enough for the next development session.
Try an interview that writes down return rules
For an existing shop adding partial returns, ask: “Use grill-with-docs to discuss returning one of two items in an order. Inspect current order status and refund code first. Ask me to decide stock restoration, shipping, and discount allocation. Update CONTEXT.md when return request and refund completed are defined; create an ADR only for a hard-to-reverse rule.” Unlike brainstorming a blank product, the agent should answer code-verifiable questions by reading the project.
At the end, look for the new definitions in the vocabulary file and a separate list of unresolved amount or status rules. If you only have a chat summary, check whether the accompanying domain-modeling work ran. An ADR for a button label is unnecessary; a choice that affects accounting and customer support later may deserve one.
Keep documents in step with the interview
An engineer uses grill-with-docs when an ADR or spec already exists but a decision still needs interrogation: settle a disagreement, then update the relevant file during the session. Another user reports that the skill caught conflicts between a plan and repository code in OpenCode while updating CONTEXT.md and ADRs. After a few answers, inspect the diff to ensure it records resolved terms and consequential choices; leave unresolved questions on an open-questions list.