Compare commits
1 Commits
main
...
685909d237
| Author | SHA1 | Date | |
|---|---|---|---|
| 685909d237 |
30
skills/grill/CONTEXT-FORMAT.md
Normal file
30
skills/grill/CONTEXT-FORMAT.md
Normal 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.
|
||||||
87
skills/grill/SKILL.md
Normal file
87
skills/grill/SKILL.md
Normal file
@@ -0,0 +1,87 @@
|
|||||||
|
---
|
||||||
|
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.
|
||||||
|
Walk down each branch of the decision tree, resolving the dependencies between decisions one at a time.
|
||||||
|
Keep going not until it feels like you understand each other, but until every branch carries an explicit decision and no dependency between decisions is left open.
|
||||||
|
|
||||||
|
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, record each term the moment it settles.
|
||||||
|
|
||||||
|
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.
|
||||||
|
It keeps the project's domain model sharp as the interview surfaces and settles terms, and never touches implementation detail.
|
||||||
|
|
||||||
|
### 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.}
|
||||||
Reference in New Issue
Block a user