grill-with-docs

name	grill-with-docs
description	Use when starting project code-improvement work — refactoring, architecture improvement, cleanup of an existing codebase — or when a grilling session should leave docs behind. Runs the interview and records decisions as ADRs and domain terms in CONTEXT.md as they crystallise.

Grill With Docs

Run a /grilling session. As the interview resolves terms and decisions, capture them the moment they crystallise — docs are written during the session, never batched to the end.

During the session

• Challenge against the glossary. When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately.
• Sharpen fuzzy language. When a term is vague or overloaded, propose a precise canonical term.
• Discuss concrete scenarios. Stress-test domain relationships with edge-case scenarios that force precise boundaries between concepts.
• Cross-reference with code. When the user states how something works, check whether the code agrees; surface contradictions.
• Update CONTEXT.md inline. When a term is resolved, record it right away using CONTEXT-FORMAT.md. CONTEXT.md is a glossary and nothing else — keep it devoid of implementation details.
• Offer ADRs sparingly. Offer one only when the decision is hard to reverse, surprising without context, AND the result of a real trade-off. Use ADR-FORMAT.md.

Create files lazily — CONTEXT.md when the first term is resolved, docs/adr/ when the first ADR is needed.

Handoff

When shared understanding is reached and the work heads to implementation, synthesise it into an OpenSpec change (opsx:propose) rather than re-interviewing.

---

Ported and adapted from mattpocock/skills grill-with-docs + domain-modeling (MIT License, Copyright (c) 2026 Matt Pocock). Adaptation: domain-modeling duties folded in; handoff targets OpenSpec.