sw-grill-me: settle every decision before building

No one knows exactly what they want. The gap between the user and the agent is where wrong builds come from, and a model never closes it alone: it fills the gaps with guesses. This skill walks the plan's decision tree with the user until nothing is left silently assumed. Use it at a project's start, before a change whose shape is unclear, or whenever the user asks to be grilled. A clear, small request does not need it.

How it runs

1. Read first. The code the plan touches, .specweave/config.json, the open increment's spec.md (specweave task list) and GLOSSARY.md if it exists. Draft the problem, the scope and the approach yourself.
2. Map the tree. List every open decision and what it depends on. Probe the things users forget: scope and non-goals; users and flows; the data and the words for it; integrations, installs, accounts and keys; failures and edge cases; security and privacy; performance and scale; rollout and migration; how a machine will check that it works.
3. Facts are yours. Anything the code, docs, config or a quick command can answer, look up (in a subagent if your tool has them). Never ask the user what you could find. A lookup still running blocks only the questions that depend on it.
4. Ask in rounds. Each round asks the whole frontier: every decision whose prerequisites are already settled. Number the questions; give each one clause on why it matters and your recommended answer, worded so "yes" accepts it. A question that depends on another one in the same round waits for the next round.
5. Recompute after every answer: settled decisions unlock new ones, and some answers make others moot. Then ask the next round.
6. Stop when the frontier is empty and the user confirms you share one picture. "Enough" or "your call" stops early: every decision left gets your recommendation as a stated default.

Plain text, one round per message:

Q1 Auth provider: who signs users in? Changes the data model and pricing.
   Recommended: Clerk, since the app already uses its React components.
Q2 Rate limits: per API key or per IP? NAT users share IPs.
   Recommended: per API key.

If your tool has a structured question tool (as Claude Code and Codex do), ask the round through it so apps such as SpecWithCode show a card: up to 4 questions per card, header Q1 Auth, your recommendation first, free answers allowed, multi-select only for "which of these services or installs". Split a larger frontier over several cards. Never ask for a secret in a question: name the env var or use the app's secret request.

The words (when GLOSSARY.md exists)

• When the user uses a term that conflicts with the glossary, say so at once: "The glossary says an Order is one checkout; you mean one shipment. Which is it?"
• When a word is fuzzy ("account" for both the login and the billing account), propose one precise term each.
• Test a boundary with a concrete scenario: "A customer pays for 3 items and one ships late: one Order or two?"
• When the user states how something works, check the code agrees and surface any contradiction.
• Write each settled term into GLOSSARY.md as sw-glossary describes, when it settles.

Record

In the increment's spec.md, under ## Decisions (before spec.md exists, hold them until sw-increment creates it with specweave create-increment):

## Decisions
### Asked
- D-01 Auth provider? → Clerk (user). Changes the data model and pricing.
### Defaulted (change any before sw-do)
- D-04 Rate-limit store → in-memory, Redis later (reversible).
### Open
- none

Apply every answer to Scope, the acceptance criteria and Approach, replacing any text it contradicts. Keep a Decision line only when a later change could contradict it: hard to reverse, surprising without context, or a real trade-off. Everything else is just applied. Do not build until the user confirms; sw-do refuses to run unattended while ### Open has entries.

Configuration

specweave skills enable grill-me installs this skill; planning.deepInterview: deep in .specweave/config.json installs it too and makes sw-increment run it for every new increment. critical (the default) keeps sw-increment to at most 5 questions.

Manual path (no CLI)

Nothing here needs the CLI: read the files by hand, ask in rounds, and write the decisions into spec.md yourself.

Adapted from mattpocock/skills grilling and domain-modeling (MIT, Copyright (c) 2026 Matt Pocock); see references/credits.md.