95 lines
5.9 KiB
Markdown
95 lines
5.9 KiB
Markdown
---
|
|
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.
|
|
While the interview is active, every assistant turn must end with exactly one of: the next numbered question, the final decision summary, or a plain statement that grill is paused because the user explicitly changed tasks.
|
|
If the turn includes a correction, file edit, apology, or explanation, follow it with the next numbered question unless the user explicitly paused grill or changed tasks.
|
|
Do not use dangling transition phrases such as “continuing” unless the continuation is actually present in the same message.
|
|
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
|
|
|
|
Resolve the artifact destination before looking for or creating artifacts.
|
|
Default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
|
|
If that vault is unavailable, fall back to `./docs` in the current project.
|
|
Create the destination directory only when a write requires it.
|
|
Read the destination's `AGENTS.md` before any artifact write.
|
|
Inspect the destination directly for its context artifact, using the destination naming convention instead of assuming a filename.
|
|
|
|
- **Domain Modeling Mode** — exactly one context artifact 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 artifact was found, and the plan raises no project-specific vocabulary worth pinning down.
|
|
Run the interview with no document side effects.
|
|
- **Clarification** — no context artifact was found, 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, choose the context artifact filename from the destination's `AGENTS.md` and nearby artifact convention, allocate any required identifier, and continue in Domain Modeling Mode.
|
|
If no, continue in Free Mode.
|
|
|
|
Stop and report the conflicting paths if more than one matching context artifact exists.
|
|
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 artifact 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 artifact 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 directly in the resolved artifact destination.
|
|
Choose its filename from the destination's `AGENTS.md` and nearby artifact convention, allocating an identifier only when that convention requires one.
|
|
It can be a single paragraph:
|
|
|
|
> # {Short title of the decision}
|
|
>
|
|
> {1-3 sentences: the context, what was decided, and why.}
|