163 lines
8.5 KiB
Markdown
163 lines
8.5 KiB
Markdown
---
|
|
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, show them in the thread (or serve
|
|
them and report the URL outside T3 Code), 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.
|