Compare commits

...

1 Commits

Author SHA1 Message Date
ea8e2c50bc 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.
2026-07-25 16:10:40 -04:00
2 changed files with 115 additions and 0 deletions

View File

@@ -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.

85
skills/grill/SKILL.md Normal file
View File

@@ -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.}