grill-with-docs

mattpocock/skills

Relentless interview to sharpen a plan or design while generating ADRs and a glossary as you go.

What is grill-with-docs?

grill-with-docs runs a structured grilling session that combines adversarial questioning with live documentation output. As you answer questions about your plan or design, it produces Architecture Decision Records (ADRs) and a glossary incrementally, so you leave the session with both a sharpened design and ready-made docs.

Runs a /grilling interview session to stress-test a plan or design
Uses the /domain-modeling skill as its foundation
Generates Architecture Decision Records (ADRs) during the session
Builds a glossary of terms as the conversation progresses
Produces documentation artifacts alongside the interview itself

How to install grill-with-docs

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

Prerequisites

The /domain-modeling skill must be available (used internally by this skill)
A plan, design, or architectural idea to bring to the session

Claude Code

Cursor

Windsurf

Cline

How to use grill-with-docs

1.Install the skill: npx skills add https://github.com/mattpocock/skills --skill grill-with-docs
2.Open your coding agent (e.g. Claude Code or Cursor)
3.Invoke the session with the /grilling command
4.Present your plan or design when prompted
5.Answer the adversarial questions the agent poses
6.Review ADRs and glossary entries generated during the session
7.Iterate on your design based on the interview findings
8.Save or commit the generated documentation artifacts

Use cases

Good for

Stress-testing a software architecture before committing to it
Clarifying domain terminology and producing a shared glossary
Generating ADRs for decisions made during a design discussion
Sharpening a technical plan before writing implementation code
Documenting design rationale in real time during a planning session

Who it's for

Software architects reviewing a system design
Developers who want to pressure-test a technical plan
Teams that need ADRs produced as part of their design process
Engineers who want to formalize domain language before building
Anyone using Claude Code or Cursor who wants structured design critique

grill-with-docs FAQ

What is a 'grilling session'?

A structured, adversarial interview where the agent asks probing questions to expose weaknesses or ambiguities in your plan or design.

What documentation does this skill produce?

It produces Architecture Decision Records (ADRs) and a glossary of domain terms, built incrementally as the session progresses.

Does this skill call an AI model on its own?

No. The skill has model invocation disabled (disable-model-invocation: true), so it relies on the host agent's model rather than making independent calls.

What is the /domain-modeling skill and is it required?

The /domain-modeling skill is a dependency used internally by grill-with-docs. It must be available in your environment for the session to work correctly.

Can I use this for non-software design decisions?

The skill is framed around plans and designs generally, but the documentation outputs (ADRs, glossary) are most naturally suited to software architecture and domain modeling contexts.

Full instructions (SKILL.md)

Source of truth, from mattpocock/skills.