From ea8e2c50bc1c1a0ab8a31f5eb807ef601d531ad6 Mon Sep 17 00:00:00 2001 From: alexion Date: Sat, 25 Jul 2026 15:28:39 -0400 Subject: [PATCH] feat: add grill skill merging domain-modeling Combine the interview-driven grill and the domain-modeling discipline into a single model-invokable grill skill, so other skills can reach it as a backbone. - One question at a time, each with options plus a recommendation and rationale, and a context quote when it turns on existing material. - Agent-agnostic mode selection: discover .agents/CONTEXT.md then .claude/CONTEXT.md, and drive Domain Modeling, Free, or Clarification. - Domain Modeling Mode maintains the glossary inline (CONTEXT-FORMAT.md) and offers ADRs under the three-gate test. - Never begin implementation without an explicit user instruction, even when a caller skill invoked grill. --- skills/grill/CONTEXT-FORMAT.md | 30 ++++++++++++ skills/grill/SKILL.md | 85 ++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 skills/grill/CONTEXT-FORMAT.md create mode 100644 skills/grill/SKILL.md diff --git a/skills/grill/CONTEXT-FORMAT.md b/skills/grill/CONTEXT-FORMAT.md new file mode 100644 index 0000000..f256d20 --- /dev/null +++ b/skills/grill/CONTEXT-FORMAT.md @@ -0,0 +1,30 @@ +# CONTEXT.md Format + +## Structure + +```md +# {Context Name} + +{One or two sentence description of what this context is and why it exists.} + +## Language + +**Order**: +{A one or two sentence description of the term} +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request + +**Customer**: +A person or organization that places orders. +_Avoid_: Client, buyer, account +``` + +## Rules + +- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`. +- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. +- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. +- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. diff --git a/skills/grill/SKILL.md b/skills/grill/SKILL.md new file mode 100644 index 0000000..9ad8401 --- /dev/null +++ b/skills/grill/SKILL.md @@ -0,0 +1,85 @@ +--- +name: grill +description: Interview the user relentlessly to stress-test a plan or design before building — one question at a time, each with options, a recommendation, and its rationale — walking the decision tree until every branch is decided. Folds in domain-model and ADR upkeep when the project has a context file. Model-invokable, including as a step inside other skills. Use when the user wants to pressure-test a plan, or uses any 'grill' trigger phrase. +--- + +# grill + +Interview the user relentlessly about every aspect of a plan or design. +Keep going not until it feels like you understand each other, but until the decision tree is walked to exhaustion. + +Ask one question at a time, in plain text, and wait for the answer before the next. +Never use an interactive question tool. +Every question carries **options** — the concrete choices, each with its trade-offs — followed by your **recommendation**, the option you would pick and why. +When the question turns on an existing document, artifact, or piece of code, open it with a **context quote**: blockquote the exact passage, so the user sees what you mean without hunting for it. + +Before asking, investigate. +When code, docs, or the conversation already settle a question, resolve it yourself instead of spending a question on it. + +**Never begin implementation** — during the interview or after it — without an explicit instruction from the user. +This holds even when another skill invoked grill: grill delivers its summary and stops, and a caller that receives that summary is not itself the instruction to build. + +## 1. Select the mode + +Look for a context file, in order: `.agents/CONTEXT.md`, then `.claude/CONTEXT.md`. +The first that exists wins, and its directory owns the ADRs too (`.agents/adr/` or `.claude/adr/`). +If both files exist, stop and ask which is authoritative rather than guessing. + +- **Domain Modeling Mode** — a context file was found. + Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)). +- **Free Mode** — no context file, and the plan raises no project-specific vocabulary worth pinning down. + Run the interview with no document side effects. +- **Clarification** — no context file, but the plan introduces terms specific to this project that later work will need to use consistently — the kind of terms [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) admits, not general programming concepts. + Before interviewing, ask whether to create a glossary. + If yes, create it and continue in Domain Modeling Mode; if no, continue in Free Mode. + A created file goes in the sole existing agent directory (`.agents/` or `.claude/`), or in `.agents/` when neither exists yet. + +Done when the interview is running in Domain Modeling Mode or Free Mode. + +## 2. Run the interview + +Walk the decision tree one branch at a time, resolving each decision's dependencies before moving to the next. +Alongside the questions, challenge and stress-test: + +- When the user's language is vague or overloaded, propose a precise canonical term in its place. +- Probe edge cases with concrete scenarios that force the boundaries between concepts to be made explicit. +- When a stated behavior contradicts what the code actually does, surface the contradiction with both sides quoted. + +In Domain Modeling Mode, feed the settling terms and decisions into the glossary and ADRs below. + +Done when every branch carries an explicit decision and no dependency between decisions is left open. + +## 3. Close the interview + +Once the interview is done: + +1. Output a concise summary of every decision reached — and, in Domain Modeling Mode, every term crystallized. +2. Stop and wait for the user's next instruction. + +Done when the summary is delivered and grill is waiting. + +## Domain Modeling Mode + +Active only when step 1 selected this mode. + +### Glossary + +As a term crystallizes, update the context file right then — do not batch these to the end. +When a settling term clashes with one already in the glossary, call it out and reconcile to a single canonical word. +Keep the file a glossary and nothing else: vocabulary and ubiquitous language, no implementation detail. +Write it in the format of [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md). + +### ADRs + +Offer to record an architectural decision only when all three hold: + +1. **Hard to reverse** — changing your mind later carries real cost. +2. **Surprising without context** — a future reader will wonder why it was done this way. +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons. + +If any of the three is missing, skip it. +A recorded decision lives in the context file's `adr/` directory, numbered one past the highest already there (`0001-slug.md`), and can be a single paragraph: + +> # {Short title of the decision} +> +> {1-3 sentences: the context, what was decided, and why.}