--- name: grilling description: Use before any creative work, meaning a new feature, component, or change in behaviour, and whenever a plan, design, or decision needs stress-testing before code exists. Triggers on "grill me", "think this through", and on any request to build something not yet designed. --- # Grilling Interview the user relentlessly until you reach a shared understanding, then stop. The output is an agreed design, never code. Write no code, scaffold nothing, invoke no implementation skill, and change no file until you have stated what you intend to do and the user has said yes. The **ceremony** scales with the task. The **gate** never does. ## Classify the path first Say the classification out loud before the first question, so it can be overridden: > "This looks bounded, so I'll ask a couple of questions and present a short design here rather than > write anything up." | Path | What it is | Output | |---|---|---| | **Spike** | A feasibility question: "can we", "is it possible", "quick and dirty is fine" | An answer, not code you keep. Present the question and probe in 2-3 sentences, get a nod, find out as cheaply as correctness allows. Anything built stays labelled throwaway. | | **Bounded** | A well-scoped change to a flow that **already exists in this repo**: a flag, a small endpoint, a one-file fix | A short design in chat, then stop. No document. | | **Architectural** | New projects, new subsystems, changes that restructure how things fit together or alter an interface others depend on | Full rounds, approaches, a sectioned design, and a written spec. | Bounded measures **the repo, not your familiarity**. Knowing the kind of app is not enough: if the flow being changed is not already there to read, the task is not bounded. **The ratchet is one-way.** In doubt between two paths, take the heavier one. Hidden complexity found mid-task upgrades the path: stop, say so, step up. Nothing ever downgrades mid-task. ## The interview Model the problem as a **design tree**: every decision branches into the decisions hanging off it. The **frontier** is every decision whose prerequisites are already settled, meaning the questions you can ask *now* without guessing at answers you have not heard yet. Work the tree in **rounds**. Ask the whole frontier in one round, numbered, each carrying your recommended answer. Then wait. ``` ❓ **Q1** - ****: ➡️ --- ❓ **Q2** - ****: ➡️ ``` Each round's answers reshape the tree: settled decisions push the frontier outward and unblock what depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a **later** round, not this one. Where a round is four questions or fewer and every answer is a discrete choice, ask it through `AskUserQuestion` instead, one option list per question, your recommendation first and marked. The markdown format above is the default, because it scales past four and carries reasoning the tool's option labels cannot. **The session is done when the frontier is empty**: every branch visited, nothing left silently assumed. ## Facts are yours, decisions are theirs Finding **facts** is your job, never the user's. When a frontier question needs a fact from the environment (what a file contains, whether a package is installed, how an endpoint currently behaves), dispatch a subagent and find out. Never ask the user something you could look up. Do not block on it. A running exploration is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now. The **decisions** are the user's. Put each one to them and wait. ## Per-path checklists Announce the path, then create a todo per item and work them in order. **Spike** 1. Explore enough project context to frame the probe 2. Present the question and probe plan, 2-3 sentences 3. Get approval, a nod is enough 4. Investigate as cheaply as correctness allows 5. Report a recommendation, labelling anything built as throwaway **Bounded** 1. Explore project context: files, docs, recent commits 2. Run one round of the frontier, usually a short one 3. Present a short design in chat: approach, files touched, testing 4. **Stop and wait for an explicit yes.** Presenting the design and starting in the same breath is skipping the gate 5. Implement through the normal workflow. No plan document **Architectural** 1. Explore project context: files, docs, recent commits 2. Work the frontier in rounds until it is empty 3. Propose 2-3 approaches with trade-offs, leading with your recommendation and why 4. Present the design in sections scaled to their complexity, confirming after each 5. Write the spec (see below), self-review it, and hand it to the user to review 6. On approval, hand off: `/ticket` where the work is a Jira story, otherwise implement directly ## Design principles - **YAGNI ruthlessly.** Strip unnecessary features from every approach before presenting it. - **Shape the modules deliberately.** When the design turns on where a seam goes, how deep a module should be, or what its interface exposes, call the Skill tool with "codebase-design" and use that vocabulary rather than inventing terms here. - **Name things in the project's language.** When a term proves fuzzy or overloaded mid-interview, call the Skill tool with "domain-modeling" and settle it rather than working around it. - **In an existing codebase, follow the existing patterns.** Where code in the way of the work has a real problem (a file grown too large, tangled responsibilities), fold a targeted improvement into the design, the way a good developer improves code they are working in. Propose no unrelated refactoring. - **Decompose before refining.** If the request spans several independent subsystems, flag it immediately rather than spending a round on the details of something that needs splitting first. Each sub-project earns its own design cycle. - **Visual questions get mocks, not prose.** Where the open question is what something should look like, stop describing it: build several distinct static mocks, serve them, report the URL, and wait for a pick. Never edit a real component to answer a layout question. ## The written spec (architectural only) Write it to `.claude/docs/specs/YYYY-MM-DD-.md`, unless the work is a Jira story, in which case the `ticket` skill owns the artifacts and their location. Then review it with fresh eyes and fix inline, no second pass: 1. **Placeholders**: any TBD, TODO, or vague requirement left in it? 2. **Internal consistency**: do any two sections contradict, and does the architecture match the feature descriptions? 3. **Scope**: focused enough to implement in one go, or does it still need decomposition? 4. **Ambiguity**: could any requirement be read two ways? Pick one and make it explicit. Then hand it over and wait: > "Spec written to ``. Have a read and tell me what you want changed before we build anything." ## Red flags | Thought | Reality | |---|---| | "This is too simple to need a design" | Simple means a *short* design, not none. Two sentences, then approval. | | "I'll call it bounded and skip the write-up" | Reaching for a label to skip work **is** the doubt. Take the heavier path. | | "The design is obvious, I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop. | | "I know this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. No existing flow means architectural. | | "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request: classify it. | | "It grew, but I'm nearly done, no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. | | "They approved the spike, so the follow-up is approved" | Every task gets its own classification and its own approval. | | "I'll ask them what the config file says" | Facts are your job. Dispatch a subagent and find out. | ## Done when - The path was classified out loud, and upgraded if complexity appeared. - The frontier is empty: no branch of the design tree left unvisited, nothing silently assumed. - Every question asked was a decision, and every fact was looked up rather than asked. - The user has explicitly approved the design. Nothing was built before that.