grill-with-docs · diff
v1.0 to v1.0
28 added, 88 removed. Audit A to A.
---
name: grill-with-docs
- description: >-
- Stress-test plans against project domain model, sharpen terminology, update CONTEXT.md and ADRs
- inline
- allowed-tools: Read Grep Glob Bash Write Edit
+ description: >
+ A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary)
+ as we go. Use when the grilling session should also leave ADRs and glossary entries behind.
+ Triggers on: grill with docs, grill and document, grill this and write the ADR.
+ allowed-tools: Read Grep Glob Bash Write Edit Task
compatibility: >
- Works best in codebases with CONTEXT.md and docs/adr/ documentation. Creates
- these files lazily if absent. Pairs with improve-codebase-architecture for
- architectural work and triage for issue preparation.
+ Thin user-invoked entry point that pairs grilling with domain-modeling so ADRs and glossary
+ entries land during the session.
metadata:
- tags: design-review, architecture, domain-model, documentation, adr, context-map
+ tags: plan-review, adr, glossary, grilling-entrypoint, domain-modeling
platforms: Claude, ChatGPT, Gemini, Codex
version: "1.0"
source: mattpocock/skills
+ upstream_commit: 3cca18b368ae95cdbdebbff572ccafa662551015
+ invocation: user-invoked
---
- # Grill With Docs
-
- A grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.
-
- ## When to use this skill
-
- - Validating architectural plans against a project's domain language
- - Stress-testing designs before implementation
- - Updating CONTEXT.md terminology as new concepts emerge
- - Preparing issues for implementation (pairs with `triage`)
-
- ## When not to use this skill
-
- - Finding refactoring opportunities → use `improve-codebase-architecture`
- - Writing implementation tickets → use `to-issues`
- - General code review → use `code-review`
-
- ## Session process
-
- ### 1. Explore domain context
-
- Before grilling, read:
- - `CONTEXT.md` — existing domain terminology
- - `docs/adr/` — prior architectural decisions
- - Relevant source files to understand current state
-
- ### 2. Run the grilling loop
-
- Interview relentlessly about every decision point. For each question:
- - Provide a recommended answer
- - Ask one question at a time, waiting for feedback before continuing
- - Explore the codebase instead of asking when the answer is findable there
-
- ### 3. Three stress-test mechanisms
-
- **Glossary alignment** — When the user uses a term that conflicts with CONTEXT.md, call it out:
- > "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
- **Precision sharpening** — When terms are vague or overloaded, propose canonical names:
- > "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
- **Scenario-based edge-case testing** — When domain relationships are discussed, stress-test with concrete scenarios that probe boundaries between concepts.
-
- ### 4. Update docs inline
-
- **CONTEXT.md** — When a term is resolved, update it immediately. Don't batch updates.
-
- File structure for single-context repos:
- ```
- /
- ├── CONTEXT.md
- ├── docs/
- │ └── adr/
- │ └── 0001-decision-name.md
- ```
-
- For monorepos with `CONTEXT-MAP.md` at root, each context has its own `CONTEXT.md` and `docs/adr/`.
-
- Create files lazily — only when you have something to write.
-
- **ADRs** — Only create when all three are true:
- 1. Hard to reverse (meaningful cost to change later)
- 2. Surprising without context (future reader would wonder "why?")
- 3. Result of a real trade-off (genuine alternatives existed)
-
- If any condition is missing, skip the ADR.
+ # Grill with Docs
- ## Cross-reference with code
+ A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. Use when the grilling session should also leave ADRs and glossary entries behind. Triggers on: grill with docs, grill and document, grill this and write the ADR.
- When the user states how something works, verify the code agrees. Surface contradictions:
- > "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+ This skill is imported from `mattpocock/skills` (MIT) and is **user-invoked** upstream.
- ## File formats
+ ## When to use this skill
- - CONTEXT.md: domain terminology meaningful to domain experts (no implementation details)
- - ADR format: title, status, context, decision, consequences
+ - A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+ - Use when the grilling session should also leave ADRs and glossary entries behind.
+ - Triggers on: grill with docs, grill and document, grill this and write the ADR.
## Instructions
- 1. Identify the task trigger and expected output.
- 2. Follow the workflow steps in this skill from top to bottom.
- 3. Validate outputs before moving to the next step.
- 4. Capture blockers and fallback path if any step fails.
+ Call the Skill tool twice, for "grilling" and "domain-modeling".
+
## Examples
- - Example: Apply this skill to a small scope first, then scale to full scope after validation passes.
+ - Apply this skill to one narrow scope first, confirm the output matches the shape described above, then widen to the full task.
+ - When a step needs a fact from the repository or the environment, look it up instead of asking the user for it.
+
## Best practices
- - Keep outputs deterministic and auditable.
- - Prefer small reversible changes over broad risky edits.
- - Record assumptions explicitly.
+ - Keep the upstream procedure intact; record deviations explicitly instead of silently improvising.
+ - Stop and hand control back to the user at every decision point this skill marks as theirs.
+ - Prefer small reversible changes, and state assumptions rather than burying them.
+
## References
+
+ - Upstream skill: `mattpocock/skills` `skills/engineering/grill-with-docs/SKILL.md` (commit `3cca18b`, MIT)
- Project standards: `.agent-skills/skill-standardization/SKILL.md`
- Validator script: `.agent-skills/skill-standardization/scripts/validate_skill.sh`