grill-with-docs

/grill-with-docs — Grill the plan AND update the docs as decisions land

Ported in behavior from mattpocock/skills engineering/grill-with-docs (MIT, © 2026 Matt Pocock). Cold-storage snapshot of the three upstream files (SKILL.md, CONTEXT-FORMAT.md, ADR-FORMAT.md) at third-party/mattpocock-skills/skills/engineering/grill-with-docs/; SHA pin in third-party/MANIFEST.md.

The two format specs (CONTEXT.md format, ADR format) are inlined as appendices in this file so the bundled skill is self-contained — see Appendix A: CONTEXT.md format and Appendix B: ADR format.

What this skill does

Interview the user relentlessly about every aspect of this plan until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide a recommended answer.

Ask questions one at a time, waiting for feedback on each before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead.

Domain awareness

During codebase exploration, also look for existing documentation:

File structure

Most repos have a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts. The map points to where each one lives:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

Create files lazily — only when you have something to write. If no CONTEXT.md exists, create one when the first term is resolved. If no docs/adr/ exists, create it when the first ADR is needed.