Grill with Docs —— Adversarial Design Review with Automatic ADR and Glossary Generation

Skill Overview

Grill with Docs is a “question while documenting” design review skill: it conducts a continuous, unrelenting examination of a plan or design, forcing out ambiguous assumptions and conceptual inconsistencies while simultaneously producing Architecture Decision Records (ADRs) and a domain glossary throughout the conversation.

Its purpose is neither to write code for you nor to make decisions on your behalf, but to help you think things through while being questioned and directly preserve the conclusions as searchable, version-controlled documents. This skill is configured for manual invocation (disable-model-invocation: true) and starts only when you want to be challenged.

Use Cases

1. Self-examination before a technical design review

   The design document is finished, but you know there are a few places where you have merely written “we’ll do it this way for now.” Start the skill before submitting it for review or beginning implementation. A round of intensive questioning will expose boundary conditions, failure modes, and rejected alternatives one by one, helping you avoid being caught off guard in the meeting.

2. Domain modeling for a new project or module

   Requirements may mix similar concepts such as “order,” “work order,” and “task,” while team members understand them differently. The skill identifies terminology ambiguities during questioning, standardizes the naming, and produces a glossary, giving subsequent code, documentation, and communication a shared vocabulary.

3. Clarifying decisions before refactoring or taking over a legacy system

   The reasons an existing architecture evolved the way it did are often scattered across chat logs, PR comments, and the memories of former colleagues. Through questioning, the skill reconstructs those historical decisions and records them as ADRs, so newcomers no longer have to infer design intent from the code.

Core Functions

1. Relentless Interview

   Rather than presenting a list of questions all at once, it follows up on your answers and digs deeper: Under what conditions does this assumption fail? What happens when it fails? Why not choose the alternative? The questioning continues until key points of disagreement have been made explicit and trade-offs have been decided.

2. Synchronized Architecture Decision Records (ADR) Generation

   Whenever you make a genuine trade-off, the skill organizes the “context—options—decision—consequences” into an ADR. The document is a by-product of the interview and does not need to be reconstructed from memory afterward, so it stays closer to the actual decision-making process.

3. Domain Glossary / Domain Model Generation

   When the conversation reveals that the same word is being used with two meanings, or that one concept has multiple names, the skill asks about it immediately and requires the terminology to converge. The result is a glossary with unified definitions that serves as the baseline for subsequent project communication.

In implementation terms, the skill itself is lightweight: it invokes the grilling and domain-modeling sub-skills once each, leaving the detailed questioning and modeling work to them.

Frequently Asked Questions

Does grill-with-docs run automatically?

No. It is configured with disable-model-invocation: true, so it can only be triggered manually and will not start on its own during normal coding or conversation. This is intentional—the adversarial review experience is not easy, and you should actively choose when to undergo it.

Will it directly modify my code or design?

No. The skill produces questions and documents: you modify the code and design yourself, while it surfaces implicit assumptions and records conclusions. It is therefore best used before finalizing a design, rather than as an automated refactoring tool.

Where are the generated ADRs and glossary stored?

They are saved in your project repository and version-controlled alongside the code, rather than remaining in the chat history. The specific directory is usually determined by your project conventions; a common practice is to place them under docs/. As a result, team members can use Git history to see the context in which each decision was made.

How does it differ from the brainstorming skill?

Brainstorming focuses on divergence—starting from a vague idea, exploring possibilities, and expanding the solution space. Grill with Docs focuses on convergence and validation—assuming you already have a plan and working to identify its flaws and force trade-offs. In practice, the two can be used together: brainstorm first to produce candidate directions, then use questioning to solidify the selected direction.

Is it worthwhile for a small personal project?

That depends on how much of a record of your decisions you want to preserve. In personal projects, “I’ll remember it myself” often makes ADRs less valuable. But if you frequently return to a project months later and cannot remember why you designed it that way, the glossary and ADRs begin to show their value. It is equally useful for testing whether you have genuinely thought an issue through.

What materials should I prepare in advance?

At minimum, you need a plan or design description that can be discussed, even if it is only a few paragraphs. The more specific the material, the more targeted the questioning will be. If all you have is “I want to build an X,” the skill will spend many rounds first helping you define the problem itself.