Getting started
Introduction
/grill-me interviews you about a loose idea in rounds until every branch of the design tree is settled. No repo or files are needed.
- Grilling docs (aihero.dev)
- SKILL.md (github.com)
- Agent skills format (devhints.io)
- Matt Pocock skills (devhints.io)
What it does
- Input A loose idea, not a plan
- Output Decisions you can commit to
- Constraint No repo; nothing written to disk
/grill-me runs the grilling primitive under another name. You type /grill-me; the agent never invokes it on its own. The session is stateless, so the result stays in the conversation.
See: grill-me docs
Front doors
| Command | Situation |
|---|---|
/grill-me | Idea is fuzzy, no repo |
/grill-with-docs | Fuzzy, in a repo |
/wayfinder | Fog spans sessions |
/prototype | A question you must see or feel |
/grilling | A bare interview |
/grill-me and /grill-with-docs are the two user-invoked front doors; both run the same interview. /wayfinder and /prototype are separate routes. /grilling is the bare primitive underneath both.
See: Front doors
The round
❓ **Q1** - **<question title>**: <question body>
➡️ <your recommended answer>
---
❓ **Q2** - **<question title>**: <question body>
➡️ <your recommended answer>
The whole frontier arrives at once. Each question is numbered, titled, and followed by a recommendation on its own ➡️ line. Word questions so "yes" accepts the recommendation.
See: grilling SKILL.md
A worked round
❓ **Q1** - **Identity provider**: Okta, or Google Workspace?
➡️ Google Workspace: staff already have accounts.
You: 1 yes
---
❓ **Q2** - **Existing passwords**: keep local login during rollout?
➡️ Keep it for one release, then remove it.
You: 2 keep it for one release
The next round contains only questions those two answers unblocked. Later rounds build on earlier ones instead of restating them.
See: grill-me docs
One at a time
# add to your global CLAUDE.md
When grilling, ask one question at a time.
The round-based default is a supported setting, not the only mode. Readers who prefer a slower cadence use this opt-out.
Plan mode off
- Plan mode on The agent hurries to produce a plan
- Plan mode off Rounds continue until the frontier is empty
The session ends when every branch is visited. The agent then asks you to confirm shared understanding before it acts; it does not start building on its own.
How it runs
Tree and frontier
storage
├── where: Postgres or SQLite?
│ └── migrations: which tool?
└── retention: how long?
└── delete: hard or soft?
A decision branches into the decisions hanging off it. The frontier is every branch whose prerequisites are settled; a round asks all of it. Questions depending on another open question wait for a later round.
Facts vs decisions
| Concern | Owner | Move |
|---|---|---|
| Fact | Agent | Dispatch a sub-agent with fresh context |
| Decision | You | Put it to you, then wait |
| Async mode | Nobody | No consolidated memo in your absence |
A running exploration is an unsettled prerequisite. Only the questions downstream of it wait; the rest of the frontier still gets asked. An agent answering its own decisions has broken the skill.
See: Facts vs decisions
Dependencies
| Skill | Needs |
|---|---|
/grill-me | grilling |
/grill-with-docs | grilling and domain-modeling |
A one-line wrapper delegates with a Skill tool call. Selective installs miss the primitives; ask the agent which skills it loaded if the round has no recommendations.
See: Invocation rules
Running one well
Answering a round
1 yesAccept the recommendation for Q11 noReject it2 the second optionPick a listed alternative- "answer the recommendation" Use when the recommendation argues against its own question
Numbered answers work because the format is fixed. Add a reason when it changes what the agent asks next.
See: The round
Steering
- Push back on a vague question Scope belongs to you
- Say "I don't know" A real answer; often a prototype signal
- Count rounds, not questions Forty-six questions over four rounds is ordinary
- Around 200 questions Scope signal, not a cap: split the work
- No question cap A cap is out of scope on purpose
Long sessions drift into the dumb zone, where questions get worse. Ask it to wrap up, or accept the plan where it stands.
Passivity
- "Agreed, agreed, agreed" Push back or ask for more detail
- Scope drifting Say so in the round
- End with no disagreement You did not need the session
The quality of your answers decides the result. A long interview is not evidence that you decided anything.
Ungrillable
- "How should this interaction feel?" Stop asking, build a throwaway
- "One long form or three pages?" Use
/prototype, look, then answer in one line
Talking cannot settle a question that needs something to react to. Building the throwaway is faster than rephrasing the same question.
Paper trail
What lands where
| Resolved | Lands in |
|---|---|
| A project term | GLOSSARY.md, inline, the moment it resolves |
| Hard to reverse, surprising, a real trade-off | An ADR under docs/adr/NNNN-slug.md |
| Everything else | The conversation, and nowhere else |
Only grill-with-docs writes these files. /grill-me leaves no workspace behind, so feed its conversation straight to /to-spec if you want a durable record.
See: The paper trail
Glossary shape
**Order**:
A request for goods from a customer.
_Avoid_: Purchase, transaction
One or two sentences define what a term is. Keep project-specific terms only; implementation detail and specs do not belong in the glossary.
See: GLOSSARY-FORMAT.md
ADR shape
# Short title of the decision
Context, decision, and reason in one to three sentences.
Files are numbered docs/adr/NNNN-slug.md. All three gates must pass, so most sessions produce none; a sharper glossary with zero ADRs is normal.
See: ADR-FORMAT.md
0 Comments for this cheatsheet. Write yours!