---
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.

<HARD-GATE>
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.
</HARD-GATE>

## 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** - **<question title>**: <question body, which may run to several paragraphs and offer
multiple choices>

➡️ <your recommended answer>

---

❓ **Q2** - **<question title>**: <body>

➡️ <your recommended answer>
```

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-<topic>.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 `<path>`. 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.
