Grill-with-docs Skill: Design Interview Leaving AI Questions as CONTEXT.md and ADRs

Grill-with-docs literally means “grilling thoroughly with documents.” AI doesn’t just persistently question gaps in a plan; it records confirmed terms during the conversation in CONTEXT.md and design decisions that are difficult to revert in ADRs (Architecture Decision Records).

The reason this difference is important is simple. When a long design conversation ends, people remember the conclusions, but the next AI session doesn’t know that conversation. While the code shows “what was built,” “why this term was chosen,” or “why other options were discarded” are not easily visible. This can lead to repeating the same questions in the next session or accidentally reverting intentionally chosen structures.

Matt Pocock’s grill-with-docs is a small orchestration skill that aims to solve this disconnect. This article examines the two skills called with the actual SKILL.md, what makes them different from the previously covered Grill-me, what documents are created and when, and how much they can be trusted and used in practice.

Persistent design questions organized into shared terms and architecture decision documents

Surprisingly, the core is only 7 lines

The SKILL.md for grill-with-docs, published on Skills.sh, is 7 lines long, including explanations. The core instruction is one sentence:

Call the grilling and domain-modeling skills respectively.

In other words, this skill does not redefine questioning methods and documentation methods at length. It is a user-callable orchestrator that activates two already separated capabilities at once.

grilling: Transforms a plan into a decision tree and asks currently answerable questions round by round.
domain-modeling: Compares conversational terms with the project’s shared language and reflects confirmed terms and important decisions in documents.

The original text also includes disable-model-invocation: true. This setting is intended for a flow where the user explicitly calls this skill rather than the model automatically selecting it based on the situation. In contrast, the internal grilling and domain-modeling are sub-rules that can be reused by multiple higher-level workflows.

This structure also sends an interesting message about skill design itself. If all actions are copied into one giant SKILL.md, rules can easily diverge. By combining small skills, if the questioning method improves, only grilling needs to be fixed, and if the term management method changes, only domain-modeling needs to be fixed.

Structure where grill-with-docs executes grilling and domain-modeling together

Figure: A 7-line orchestrator combines the two rules of questioning and documentation. Reconstructed based on grill-with-docs in the official repository.

First Engine: Transforms a plan into a decision tree

Grilling views a plan not as a flat list of questions but as a decision tree. It connects sub-questions that only gain meaning once a higher-level decision is made, and only brings out questions whose prerequisites have been resolved into the current round’s Frontier.

For example, let’s say there’s a plan to “create an order cancellation feature.” If we immediately decide on API paths or database fields, we might skip important premises. First, the following higher-level decisions need to be confirmed:

Can only the entire order be canceled, or can partial items also be canceled?
Will cancellation before payment approval and cancellation after refund be treated as the same status?
If shipping has started, is it a cancellation or a return?
How do the permissions and audit records differ between forced cancellations by customer service and regular cancellations by customers?

Once the user’s answer is provided, the next Frontier opens. Only then can state transitions, event names, API boundaries, and test scenarios be concretized. Sub-questions that still depend on open higher-level questions are deferred to the next round.

This process also separates fact-finding from decision-making. Whether existing code supports partial cancellations or what the current event name is are facts the agent should investigate in the repository. Whether to allow partial cancellations as a product policy is a decision the user must make. The skill does not make the user search for files, nor does AI quietly make organizational value judgments on its behalf.

Second Engine: Compares the conversation with the project’s shared language

Domain-modeling is not a tool for generating many questions, but a rule for sharpening the words in questions. If a user uses broad or ambiguous terms like “account,” “cancellation,” or “customer,” it compares them with the existing CONTEXT.md.

For example, if the project glossary defines Cancellation as “withdrawing an order before payment approval,” but in the conversation, refunds after shipping are also called cancellation, it immediately reveals the conflict. It might ask, “The ‘Cancellation’ in the existing glossary differs from the action you just described; which concept does the latter refer to: Return or Refund?”

Here, CONTEXT.md is not an implementation specification. The original emphasizes using it only as a glossary for the project domain, not for implementation details. Good entries are short.

## Language

**Order**:
고객이 구매 의사를 확정해 생성한 거래 단위.
_Avoid_: Purchase, transaction

**Cancellation**:
결제 승인 전에 Order를 철회하는 행위.
_Avoid_: Refund, return

If multiple words refer to the same concept, choose one standard term, and list synonyms to avoid under Avoid. It should only contain terms necessary to understand the project’s business, not general programming terms.

A single domain repository usually suffices with one CONTEXT.md at the root. If there are multiple distinct contexts like order, payment, and delivery, a CONTEXT-MAP.md at the root is used to point to the document locations and relationships of each context. Files are not created as empty shells in advance but are generated only when there is actual confirmed content to record.

Not all decisions are recorded as ADRs

ADR stands for Architecture Decision Record, a document that records design decisions that someone looking at the code later might ask, “Why was this done?” Grill-with-docs does not accumulate all conclusions from a conversation as ADRs. It only proposes them when all three of the following conditions are met:


Condition	Question to check	Examples not requiring recording

—	—	—
Difficult to revert	Is the cost of changing it later high?	Choosing a small, easily replaceable utility
Surprising without context	Will future developers wonder why?	Obvious default settings of the ecosystem
Actual trade-offs	Was one reasonable alternative chosen for a good reason?	Cases where there is virtually only one option

For example, the decision to “connect orders and payments via domain events rather than synchronous HTTP” involves trade-offs like fault isolation and eventual consistency, and the cost of change is high. Future developers might want to switch to direct calls, making it an ADR candidate.

Conversely, if every variable name, small library, or easily reversible formatting setting were made into an ADR, important decisions would be buried in a pile of documents. The original template is surprisingly short, considering that a title and 1-3 sentences explaining “what was decided and why” are sufficient. Alternatives considered, outcomes, and status are optionally added only when they provide actual value.

Decision flow where confirmed content during conversation is split into glossary and ADRs

Figure: Terms go into CONTEXT.md, and only decisions that are difficult to revert, surprising without context, and involve actual trade-offs are recorded as ADRs. Reconstructed based on the original domain-modeling text.

What’s different from Grill-me

The two skills are not in competition. Grill-with-docs calls grilling internally, so the root of the questioning method is the same. The difference lies in what remains after the conversation ends.


Category	Grill-me	Grill-with-docs

—	—	—
Main target	General plans, ideas, decisions	Design and domain models of an actual codebase
Questioning method	Decision tree and Frontier	Same grilling method
Code comparison	Necessary fact-finding	Actively checks for conflicts between current code and term definitions
Shared language	Agreement within the conversation	Immediately reflects confirmed terms in CONTEXT.md
Decision recording	No separate documentation rules	Proposes only decisions meeting conditions as ADRs
Suitable situations	Product ideas, purchases, operational plans, etc.	Design changes for a long-maintained codebase

If it’s about validating a one-time plan or an idea without an existing repository, Grill-me might be sufficient. Conversely, if terms and design reasons need to persist for future sessions in a codebase managed by multiple people over a long period, Grill-with-docs’ documentation rules are meaningful.

How a session actually flows

Taking the order cancellation feature as an example, the overall flow can be summarized as follows:

The agent reads existing code, CONTEXT.md, CONTEXT-MAP.md, and ADRs from the repository.
It creates a decision tree from the plan and groups questions with resolved prerequisites into one round.
If ambiguous terms like “cancellation” conflict with the existing glossary, it immediately asks for precise boundaries.
It pressures the model’s boundaries with concrete exception scenarios like partial cancellations, refunds, and returns.
Once a term is confirmed, it updates the corresponding CONTEXT.md on the spot.
It proposes recording only decisions that are difficult to revert, surprising without context, and involve actual comparison of alternatives as ADRs.
Even if the Frontier of the question tree is empty and shared understanding is reached, implementation does not begin until the user confirms.

The important point is that documents are not created all at once like meeting minutes at the end. Terms are reflected in the glossary the moment they are confirmed, and the decision to record an ADR is made the moment its conditions are met. This ensures that questions in later rounds also use the language just defined.

Installation and Calling

The Skills.sh page provides the following installation command:

npx skills add https://github.com/mattpocock/skills --skill grill-with-docs

The repository README also guides the following form for Codex and other agents:

npx skills@latest add mattpocock/skills

The second method is a flow for selecting the skill to install and the target agent. The repository instructs to run setup-matt-pocock-skills once initially to set project configurations like document locations and issue trackers.

When calling, it’s good to provide the plan and document scope together.

이 주문 취소 설계를 grill-with-docs로 검토해줘.
현재 코드와 CONTEXT.md를 먼저 확인하고,
용어가 확정되면 glossary에 반영해줘.
ADR은 세 가지 조건을 모두 만족할 때만 제안하고,
합의 전에는 구현하지 마.

Installation commands involve bringing code from an external repository into your project. Before execution, it is safer to check the current SKILL.md, any sub-skills called with it, and their licenses, and to treat changes in an organizational repository as subjects for code review. While this repository is open under the MIT License, the license itself does not imply security validation.

Advantages and Limitations

The biggest advantage is that design conversations remain as input for the next session. Standardized terms increase the likelihood of using the same language in variables, functions, files, and descriptions. ADRs reduce the chance of future developers misunderstanding intentionally chosen structures as “unnecessary complexity” and reverting them.

Furthermore, because it’s a small, composite skill, its reuse boundaries are clear. Questioning rules and documentation rules can be improved separately, and other workflows can also call the same grilling or domain-modeling.

However, it does not automatically guarantee a good domain model. If a user confirms a wrong premise, incorrect concepts might remain in a short, consistent glossary. If existing code already conflicts with business rules, the fact that “code and conversation differ” alone cannot determine which is correct. In such cases, domain experts, operational data, and actual policies need to be further consulted.

The authority to update documents also requires caution. Simply changing CONTEXT.md in a shared repository during an idea exploration phase can solidify unagreed-upon terms as official language. In a team environment, it’s better to review changes via diffs and clearly define approval boundaries for ADR proposals and actual implementation.

Finally, this method is not an international standard or a built-in feature of all agents. Grill-with-docs, the CONTEXT.md format, and the three ADR gates are project rules chosen by the Matt Pocock repository. While a useful pattern, if an organization has existing ADR templates, domain document locations, and approval procedures, it should be adjusted to fit that system.

Conclusion

The core of Grill-with-docs is not about creating many documents. It’s about narrowing down ambiguous designs through questioning and retaining only valuable knowledge in the smallest possible documents.

The structure to remember is three-fold: grilling finds gaps in the decision tree, domain-modeling reveals conflicts between code and terms, and confirmed results lead to a glossary or ADRs that have passed strict gates. And even after all questions are answered, implementation does not begin until the user confirms shared understanding.

If the previous Grill-me was “how to thoroughly question gaps in thought,” Grill-with-docs goes a step further. It transforms today’s agreements into project-readable memories so that the next session doesn’t repeat the same questions.