grillspec-grill
Use when a change involves decisions the user should make - before writing a spec, plan or code for a feature, module, interface, schema or infrastructure change - and when the user says grill, interview me, let's plan, or asks how to build something. Interviews until nothing is left to guess and keeps a decision log that survives context loss.
- License 许可
- MIT
- 最近更新
- 2026-10-21
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- grillspec-grill
- description
- Use when a change involves decisions the user should make - before writing a spec, plan or code for a feature, module, interface, schema or infrastructure change - and when the user says grill, interview me, let's plan, or asks how to build something. Interviews until nothing is left to guess and keeps a decision log that survives context loss.
03 SKILL.md 正文
Grill the user before building
A design built on a guess costs more than ten extra questions. Interview the user until you could write the spec without guessing anywhere, and write every answer to the decision log as you go: the log, not your memory, is what the spec is written from.
grillspec below means the command on the grillspec CLI: line of your
session-start context (or uvx grillspec).
1. Start
- Read the session-start status line (or run
grillspec status --json).- Phase
grill: you are resuming. Read the log at itslog=path, then go straight to step 3 with its Open items. Do not re-ask Settled ones, and do not re-explore the code you already explored for them. - Another change is active in
grill,spec,planorexecuteand the request is not part of it: name it and its phase and ask — continue it / start the new one here (the old one stays;grillspec use <id>returns to it) / start the new one in a separate worktree (git worktree add ../<repo>-<slug>, then continue there).
- Phase
- Ask the setup question, one message:
- a slug for the change (lowercase kebab-case, proposed from the request);
- the depth — recommend by stakes:
quickfor a small, reversible change;standardfor a feature;deepfor anything hard to reverse (schema, public API, infrastructure, security); - a council, only if a
grillspec-councilskill is installed andcouncil.enabledisaskin the config. Name the members it would use (see that skill) and the cost:≈ <decisions> × <members> calls (standard ≈ 4 decisions, deep ≈ 15); external calls spend your vendor quotas.
- Run
grillspec new <slug> --depth <depth>(add--councilwhen chosen, and--switchwhen the user chose to start it while another change is active). If the depth, council or council members differ from the configured default, offer once to make them the default in the user's config.
2. Build the decision tree
Map every decision the change needs, with the decisions that hang off it. The
frontier is every decision whose prerequisites are settled. Write the whole
frontier under ### Open before asking anything:
- [ ] Q3 Retry policy for failed webhooks (after D2)
Facts are yours, decisions are theirs. Look facts up: files, git history,
config, docs, a --help. A quick lookup you do inline; a broad exploration you
hand to a subagent when the harness has one, and keep asking the questions that
do not depend on it. Never ask the user what you could have checked. A choice
between options is a decision even when one option looks obvious — ask it.
3. Ask
| Depth | How | Budget |
|---|---|---|
| quick | Rounds in plain text: the whole frontier, numbered, each with ➡️ your recommendation, worded so "yes" accepts all of them |
~5 decisions |
| standard | One decision at a time; up to 4 small independent ones together | ~15 decisions |
| deep | One decision at a time | none |
For standard and deep use the harness's multiple-choice tool when it has one
(see using-grillspec/references/), otherwise numbered options in text.
Every decision you put carries: your recommendation first, marked
(Recommended); the real trade-off of each option; whether it is cheap or costly
to reverse. With a council (council=yes in the metadata), follow
grillspec-council — on standard for root and hard-to-reverse decisions, on deep
for every decision.
4. Log every answer — immediately
In the same turn as your next question, move the item from Open to Settled:
- [x] D1 Auth — **JWT + refresh tokens** · user · alternatives: server sessions (simpler revoke) · reversible: costly
> "the mobile client has no cookies"
- Source, exactly one of:
user(they chose),accepted(they said yes to your recommendation),delegated("you decide": take your recommendation, do not ask again),agent's call(only for choices with no effect on the product, such as an internal name),accepted without discussion(see Budget). - "Skip" / "later": leave it Open and append
· deferred. - Quote the user's own words when they answered in their own words.
- Changed mind: never edit a Settled line. Add a new entry and mark the old one
- [~] D1 … superseded by D6. - Write in the project's artifact language; OpenSpec keywords stay English.
- Never write secrets, tokens or passwords into the log: write
<redacted>. - Bump
asked=in the<!-- grillspec: … -->line when you put a decision to the user — not when you add it to Open. - New branches that an answer opens go under Open right away.
5. Budget
The budget counts decisions put to the user, batched or not; follow-up questions
about the same decision and fact lookups do not count. When asked reaches it,
list every remaining Open item with your recommendation and ask: continue, or
accept these? Accepted ones are logged as accepted without discussion.
6. Split
If the tree turns out to hold independent changes, name them and offer to split.
On yes, create each with grillspec new <slug> --switch, move its Open items to
its log, return with grillspec use <id>, and finish one change at a time.
7. Finish
When Open holds nothing but explicitly deferred items:
- Play back the shared understanding in 3–10 lines. List separately every
agent's call,delegatedanddeferreditem. - Ask: "Do we share the same understanding?" Only an explicit yes counts.
- On yes, run
grillspec approve grill. - Name the log file and suggest committing it — never commit it yourself.
- Continue with the
grillspec-specsskill. If it is not installed, say so and stop: the log is complete and the phase is nowspec.
Red flags
| Thought | Reality |
|---|---|
| "This one is obvious." | Obvious is where unchecked assumptions live. Ask it. |
| "They're in a hurry, I'll decide." | Name the decision in one sentence and ask. One question beats one rework. |
| "I'll ask that later." | Later is after the guess is built in. Put it under Open now. |
| "I'll write the log at the end." | The end comes after compaction. Write it now. |
| "That's a fact, not a decision." | If two reasonable people could choose differently, it is a decision. |
| "They said yes earlier, so this is approved too." | Each decision and the final confirmation need their own yes. |
04 同仓库更多 Skills
graders
暂无简介
graders
暂无简介
using-grillspec
Use when starting any conversation, and before acting on any request that involves choosing between options - routes work through grilling, specs, plans and execution so the agent never guesses what the user would decide.
grillspec-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
grillspec-verification
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
grillspec-tdd
Use when implementing any feature or bugfix, before writing implementation code