grill-then-plan

Run a domain-aware design session, then hand off to the superpowers planning pipeline. Do NOT write code, scaffold, or invoke any implementation skill until the design spec is approved and you have invoked .

(Step 6's hand-off) is a sibling of this skill and ships with it, so it cannot be missing — the gate that used to guard it passes by construction. What CAN still be absent is the upstream

superpowers

plugin, two hops further downstream: ' own execution skills — , — reach and directly. This step is a one-line courtesy notice about that gap, never a gate — it does not stop or wait for anything, and grilling never invokes superpowers itself.

Detect by skill availability (harness-agnostic, plugin-agnostic): check whether the superpowers skills (, ) appear in your surfaced skill list or can be loaded.

If not detected, say one line before the first grilling question: the spec and the plan will be written normally, but and won't be available when the plan reaches execution — install the plugin before then if the plan will need them. Then continue to Step 1 regardless of the answer — this is a warning, not a wait.

Read the codebase, recent commits, and existing docs: / at the repo root, and . If a exists, the repo has multiple contexts — infer which one the topic relates to (ask if unclear).

If the plan exists to fix something that currently misbehaves — a bug, a failure, wrong output, "it keeps breaking" — and the root cause is not yet verified, do not start grilling. Grilling a fix design on top of an unverified guess about why it breaks plans on sand. Hand off to debug-mantra to establish the confirmed cause first, then return here and grill the fix design against that verified truth.

Skip this guard — proceed straight to Step 2 — when either holds:

This is the symmetric partner to the forward debug chain (ADR 0003): grill-then-plan verifies the cause first when planning a fix (ADR 0011). Either way the invariant holds — never plan a fix on an unverified cause.

Interview the user about every aspect of the plan until you reach shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time and wait for feedback before continuing. If a question can be answered by exploring the codebase, explore the codebase instead of asking.

The person answering knows the product, not necessarily the schema. Pose every question in what they can see and do -- which screen, what they press, what happens next -- and only then give the model-level backing. When two or more paths are in play, a small table beats prose:

The table is the SHAPE, not the scope. The same framing fits a queue, a schema, a CLI flag or a cron job: name the surface the user would actually observe, whatever that surface is.

Then make the stake observable with one concrete walk-through: "you save an item while working inside project X; three months later you delete project X; today the item disappears from your library too." A user who cannot picture the consequence cannot choose between the options.

Two tells that the FRAMING was wrong rather than the explanation: the answer comes back as a question ("what do you mean?", "which step of the app is this?"), or you needed entity names and ADR numbers just to state the options. Re-pose it - do not re-explain it at greater length.

Put trade-off reasoning in the message body where it can actually be read; keep option labels to a few words.

Some grilling questions are about a UI surface — layout, where an element sits, what's on screen, the flow between states. Words agree falsely here: you and the user both think you understand each other and picture different screens, because neither saw it. When a question can only be resolved by looking, make the mockup the question — render it from the UI decisions resolved so far, in the project's own design language, and ask the user to confirm or correct, then loop. If the project has no design system, first have the user establish a minimal design baseline (you propose the starter) — never wireframe ad-hoc, or the mockups and the build drift apart. Skip this entirely for designs with no visual surface. Put the mockup in the project's Claude Design design-system project via (PREFERRED). A rendered Artifact, then a self-contained , are fallbacks used ONLY when DesignSync/Artifact are unavailable; never default to a local even if a prior mockup already exists in the repo. Full mechanism (when to render vs not, how, and carrying it to the spec) is in -- read it before the first render.

When grilling converges, before writing the spec, play the design back as a terminal recap so the user can confirm it is captured correctly. Render it as a terminal diagram per the Terminal diagrams family in (Unicode box-drawing, vertical, ≲ 50 columns, inside a fenced block — never Mermaid, which does not render live in a terminal):

Then ask: "Does this capture the design?"

This is a cheap checkpoint on the decision set before the spec exists; it is distinct from Step 5's gate, which approves the written spec. Do not write the spec until the recap is confirmed.

Once understanding is shared, write the design to ( is a lowercase-kebab slug). The spec is a Markdown document — follow the diagram convention in (one overview Mermaid diagram at the top; type-matched diagrams per section). If a UI mockup was produced in Step 3.5, reference its final artifact URL / path in the spec, so the plan and the implementer work from the same screen you confirmed — one source of truth. Run a self-review for placeholders, internal consistency, scope, and ambiguity; fix inline. Ask the user to review the spec and approve before proceeding. If they do NOT approve, return to Step 2 and grill on the disputed points, then revise the spec — do not proceed to handoff until approved.

If the spec's plan rests on claims about how EXISTING code or a live system behaves (coupling, dependencies, "X already does Y", "path Z is ungated"), verify those load-bearing claims against the actual code / live system BEFORE asking for spec approval - a prose self-review cannot catch a false premise. Correct the spec with what you find. A wrong assumption about the current system silently breaks the plan built on it.

After the user approves the spec, invoke to produce the implementation plan. This is the terminal state — do NOT invoke any other implementation skill.