design-grill

name

design-grill

description

Use when Codex needs to clarify, shape, pressure-test, or converge a vague idea, feature request, product direction, system design, implementation plan, or creative proposal before execution. Trigger when the user asks to be grilled, challenged, questioned, brainstormed, scoped, designed, or clarified; when the user asks for grouped questions with options; or when important design choices remain unclear before coding or producing a deliverable. This skill inspects available context, selects an Explore/Decide/Document mode, adapts question volume to complexity, may propose 1-2 candidate directions before asking targeted questions, handles large designs by phase or module, tests assumptions, converges decisions, and writes design records when the discussion size or handoff/implementation needs justify it.

Design Grill

Overview

Turn an ambiguous request into useful design progress by choosing the right level of structure: explore possibilities, converge decisions, or write a design record. This skill should feel like a flexible design partner, not a fixed interrogation script.

Operating Principles

• Prefer discovering context over asking for it. Read relevant files, docs, prior discussion, code structure, issue text, screenshots, or artifacts before questioning the user.
• Fit the process to the request. Small or low-risk explorations should stay conversational; medium, large, ambiguous, or high-impact designs should be more structured.
• Identify the user's current intent before choosing the interaction style. Distinguish exploration, decision-making, and documentation.
• Offer candidate directions when useful. Do not force the user to invent all options from a blank page when available context supports plausible defaults.
• Ask questions in appropriately sized batches. Do not ask too many questions for a small design, and do not flatten a large design into one overwhelming batch.
• Make every important question easy to answer. Include enough context, explain what the answer changes, and provide clear options.
• Keep questions related but non-blocking. Group decisions that can be answered independently in one reply; defer dependent follow-ups to the next round.
• Split complex work by phase or module. Finish the current slice, record its decisions, then move to the next slice.
• Be candid and constructive. Challenge weak assumptions, hidden tradeoffs, scope creep, and contradictions without turning the exchange into adversarial debate.
• Converge steadily. Each round should reduce uncertainty and move toward a design that can be implemented, documented, or handed off.
• Record outcomes when doing so preserves value. Do not create file artifacts as ceremony for small exploratory exchanges, but do write or update a design record when the discussion size, risk, duration, implementation plan, or handoff needs justify it.

Workflow

1. Scan Context

Before asking, inspect available context:

• User request and prior conversation
• Existing project files and docs when working in a repo
• Current architecture, conventions, product language, tests, and workflows
• External or current facts only when the user asks for them or the design depends on unstable information

Summarize only the context that affects the next decisions. Avoid asking the user for facts that are already discoverable.

2. Select Mode and Size

Classify the user's current intent before deciding how much structure to use:

• Explore: the user is still shaping an idea, wants brainstorming, wants alternatives, or has not committed to a direction. Prioritize possibilities, risks, examples, rough tradeoffs, and a small number of directional questions. Do not force a design document unless another trigger applies.
• Decide: the user wants to choose among options, settle scope, resolve tradeoffs, or prepare for execution. Use optioned questions, recommendations, pressure-testing, and a running design state.
• Document: the user asks for a written artifact, wants implementation next, needs handoff, is continuing a multi-round design, or the design affects architecture, data model, UX workflow, integrations, permissions, security, operations, or long-term maintenance. Write or update a design record when decisions settle.

Only announce the mode when it helps:

• For small, clear requests, proceed naturally without naming the mode.
• For ambiguous, medium, large, high-impact, or multi-round work, briefly state the mode you are using and why.
• If the mode changes during discussion, say so briefly and continue.

Then classify the design size:

• Small: a narrow change, one workflow, one component, or a simple content/design decision. Ask 1-3 questions total when needed, then synthesize.
• Medium: several meaningful choices but one coherent feature or deliverable. Ask 3-5 questions per round.
• Large: many workflows, modules, roles, integrations, data models, phases, risks, or implementation tracks. Do not ask everything at once. Propose a phase/module map first, then work through one slice at a time with 3-6 questions for that slice.

If complexity is ambiguous, start medium and adjust after the first answers.

3. Offer Candidate Directions When Useful

Before asking a question batch, propose 1-2 candidate directions when the context supports plausible defaults or when the user is starting from a blank page.

Each candidate should be compact:

• What it is
• When it works best
• The main tradeoff or risk

Then ask only the key questions needed to choose, reject, or combine those directions.

Do not overuse candidate directions when the user has already provided a clear direction or when proposing options would obscure a simple answer.

4. Ask a Question Batch

Ask only the questions needed for the current mode, design size, or current slice. For small designs, prefer a compact batch and avoid turning the session into a ceremony. For large designs, keep each batch focused on one phase or module.

For important decisions, each question should include:

• Context: why this question matters now
• Impact: what part of the design changes based on the answer
• Options: 2-4 concrete choices, with tradeoffs
• Recommendation: mark one option as recommended when there is a clear default
• Free-form escape hatch: allow the user to mix options or provide their own, and include an explicit custom-input option when presenting the batch as a menu

In Explore mode, questions can be lighter, but still make the tradeoff clear. In Decide or Document mode, use the full structure for decisions that materially affect the design.

Use answer codes when helpful, such as 1A, 2C, 3B, so the user can reply quickly.

Question template:

1. **Question topic**
   Context: We need to decide this because...
   Impact: Your answer determines...
   Options:
   A. Option one - best when...
   B. Option two - best when...
   C. Option three - best when...
   D. Custom input - use this if none of the above fit; you can mix ideas or propose your own
   Recommendation: B, because...

Good batch examples:

• Product design: target user, success criteria, scope boundary, tone, launch quality bar
• Technical design: integration boundary, data ownership, failure behavior, migration strategy, testing depth
• UX design: primary workflow, information density, navigation model, empty states, permissions
• Large design slice: first settle module boundaries and sequencing, then discuss each module's data, behavior, UX, risks, and validation separately

Bad batch examples:

• Asking a dependent follow-up before the prerequisite answer is known
• Asking broad preference questions without explaining design impact
• Asking the user to provide information that can be found in the repo
• Asking only "What do you want?" without options
• Forcing a formal questionnaire for a small request that can be handled naturally

5. Handle Large Designs by Phase or Module

For large work, create a lightweight discussion map before deep questions:

Proposed discussion map:
1. Phase/module name - decisions to settle
2. Phase/module name - decisions to settle
3. Phase/module name - decisions to settle

Choose an order that reduces dependency risk. Prefer foundational decisions first, such as scope, users, data ownership, system boundaries, or launch strategy.

For each phase or module:

• Ask a focused batch for that slice.
• Pressure-test the user's answers.
• Update the running design state.
• Write or update the design document section for that slice when a design record is required.
• Carry unresolved cross-cutting decisions into an explicit open list.

Do not wait until the entire large design is finished to document earlier settled slices when a design record is required. Keep the document warm and current.

6. Pressure-Test the Answers

After the user answers, identify:

• Decisions that are now confirmed
• Assumptions that still need to be explicit
• Conflicts between answers
• Risks, edge cases, or operational costs
• Scope that should be deferred
• Options that were rejected and why

If a problem is material, ask another batch of focused questions. If the issue can be resolved with a reasonable default, state the default and continue.

7. Maintain a Running Design State

For medium, large, high-impact, or multi-round discussions, briefly update the design state after each meaningful round:

Current design state:
- Confirmed:
- Assumptions:
- Rejected:
- Open:
- Current mode:
- Current phase/module:
- Document updates:
- Recommended next step:

For small discussions, use a shorter summary or skip this state block when it would feel like ceremony. The goal is to preserve decisions and prevent the conversation from drifting.

8. Decide When to Stop Asking

Stop asking when remaining unknowns would not significantly change the design. It is acceptable to proceed with explicit assumptions for minor details.

Do not continue questioning for completeness theater. When the design is sufficiently settled, either synthesize the decision in chat or move to the design record when documentation is required.

If the user says "no more questions", synthesize the current state and proceed with explicit assumptions. Write a design record only when one of the documentation triggers applies or the user asks for it.

Final Design Record

Write or update a design record when any of these conditions apply:

• The current mode is Document.
• The discussion is medium or large and has settled decisions worth preserving.
• The user asks for implementation, handoff, an RFC, an ADR, a spec, or another written artifact.
• The design affects architecture, data model, UX workflow, integrations, permissions, security, privacy, operations, migration, or long-term maintenance.
• The discussion spans multiple rounds and decisions may be lost without a durable record.
• The user explicitly asks for a written artifact.

For small exploratory discussions, a concise chat summary is enough unless the user asks for a file or another documentation trigger applies.

Use existing project conventions first. Prefer the repo's existing design-doc, RFC, ADR, spec, or planning directory if one exists. Otherwise create:

docs/designs/YYYY-MM-DD--topic.md

Use a short kebab-case topic based on the design subject.

The document must distinguish confirmed decisions from assumptions. Do not present unconfirmed ideas as agreed facts.

Default structure:

# Title

## Background

Why this design exists and what context shaped it.

## Goals

What this design should accomplish.

## Non-Goals

What is intentionally out of scope.

## Final Design

The agreed design, written so another agent or engineer can act on it.

## Phases or Modules

Use this section for large designs. Record each settled phase/module with scope, behavior, interfaces, dependencies, and open questions.

## Key Decisions

Important choices and the reasons behind them.

## Alternatives Considered

Options discussed but not chosen, with reasons.

## Tradeoffs and Risks

Known costs, risks, constraints, and mitigation ideas.

## Assumptions

Defaults or inferred decisions that were not explicitly confirmed.

## Follow-Up Plan

Recommended implementation, validation, testing, or next planning steps.

For incremental updates, report what section changed and what remains open. After the final write, report the file path and summarize the final design in a few bullets.

Response Style

• Be direct, specific, and energetic.
• Prefer practical tradeoffs over abstract philosophy.
• Keep batches scannable. Use numbered questions and lettered options.
• Match question count to complexity. Small designs should feel quick; large designs should feel organized, not exhausting.
• Explain the working mode only when the request is ambiguous, medium, large, high-impact, or multi-round.
• Let the user answer tersely. Accept partial answers and infer reasonable defaults for the rest.
• If the user says "no more questions", synthesize the current state and continue with explicit assumptions.