Grill with docs
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.From its SKILL.md
npx -y skills add wayne930242/grillboard --skill grill-with-docsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.0 KB, as published. Nobody here has run it
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.mdis 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.