5.1 KiB
name, description
| name | description |
|---|---|
| grill | 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
Resolve the artifact root with $(xdg-user-dir DOCUMENTS)/ai-artifacts.
Use the lowercase basename of the current working directory as <project> and inspect projects/<project>/ directly for its numbered <project>-context.md artifact.
Read the artifact root's AGENTS.md before any artifact write.
Create the project directory only when a write requires it.
- 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).
- 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.mdadmits, not general programming concepts. Before interviewing, ask whether to create a glossary. If yes, allocate the next vault identifier through.counter, create<NNN>-<project>-context.md, 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:
- Output a concise summary of every decision reached — and, in Domain Modeling Mode, every term crystallized.
- 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.
ADRs
Offer to record an architectural decision only when all three hold:
- Hard to reverse — changing your mind later carries real cost.
- Surprising without context — a future reader will wonder why it was done this way.
- 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 project's flat artifact directory.
Allocate its identifier through the vault-root .counter and name it <NNN>-<scope-slug>-<decision-slug>-adr.md according to the vault convention.
It can be a single paragraph:
{Short title of the decision}
{1-3 sentences: the context, what was decided, and why.}