grilling

Grilling & Brainstorming (Unified)

Two traditions, one pipeline. This skill merges collaborative brainstorming (focused exploration, one question at a time, visual companion, design concept) with relentless grilling (design tree, frontier rounds, assertive questions, a recommendation alongside every question, sub-agents for facts). The output is a shared design concept — the conversation itself becomes a reusable asset.

Intent capture

Before exploring or asking questions, capture the intent:

1. Objective: what the user wants to achieve.
2. Where it lands: which project, module, or feature.
3. User impact: how the change affects the user or the product.

If intent is unclear, ask for it before proceeding. The captured intent feeds into planning (Spec mode) as the PRD's Intent section.

Modes

Mode	Trigger	What changes
Default	"grill this", "stress-test", "brainstorm"	Full pipeline below
Stateless	"grill me" without a working directory	Skip file/context exploration (Step 1); work purely from the conversation. Use frontier rounds: ask all currently-unblocked questions at once, never one at a time. If there are more than 4, split into multiple ask_user_question calls in the same round, each with at most 4 questions and 4 options. Every question includes a recommended answer.
With-docs	"grill and document" / "sharpen plan + ADRs"	Run full pipeline + invoke knowledge-modeling in Phase 3 to produce ADRs and glossary alongside the spec

Decision logic: which mode when

Situation	Use	Why
Idea is fuzzy, early-stage, need to explore possibilities	Brainstorm mode	Assertive, batched independent questions. Propose 2-3 approaches with trade-offs. Visual companion for UI/layout questions.
Have a plan/decision that needs stress-testing	Grill mode	Relentless, assertive interview. Design tree with frontier rounds. Every question includes a recommended answer. Every branch visited, nothing silently assumed.
New feature from scratch	Both, in sequence	Brainstorm to explore the idea → Grill to stress-test the resulting design → Write spec → planning (Tickets mode) or planning.
Modifying existing behavior	Brainstorm mode	Understand current behavior, propose changes, get approval.
User says "grill me" or "stress-test this"	Grill mode	Explicit trigger for relentless questioning.
User says "brainstorm" or "I have an idea"	Brainstorm mode	Explicit trigger for collaborative exploration.
Design is done, need to write it up	Brainstorm mode (final phase)	Write design concept, spec self-review, user review gate, transition to planning (Tickets mode) or planning.

<HARD-GATE> Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. </HARD-GATE>

Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short, but you MUST present it and get approval.

---

Phase 1: Explore (Brainstorm Mode)

1. Explore project context

Check files, docs, recent commits. Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.

If the project is too large for a single spec, help the user decompose into sub-projects. Each sub-project gets its own spec → plan → implementation cycle.

2. Offer the visual companion just-in-time

NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens. If no visual question ever arises, never offer it. See visual-companion.md for details.

This offer MUST be its own message. Only the offer — no clarifying question, summary, or other content.

3. Ask clarifying questions

• Ask assertively: frame each question as a concrete proposal with your recommendation, then let the user confirm or override.
• Ask one at a time only when the next question depends on the previous answer.
• When questions are independent, batch them in one round so the user can answer all at once.
• Respect the ask_user_question tool limit: 1-4 questions per call and 2-4 options per multiple-choice question. If more than 4 questions are unblocked, ask up to 4, wait for the answers, incorporate them, recompute the frontier, then continue.
• Every question MUST include a recommended answer or default stance. The user can accept, amend, or reject it in one line.
• Prefer multiple choice when possible, but open-ended is fine.
• Focus on understanding: purpose, constraints, success criteria.
• For appropriately-scoped projects, refine the idea through dialogue.

4. Propose 2-3 approaches

• Present options conversationally with your recommendation and reasoning
• Lead with your recommended option and explain why
• YAGNI ruthlessly — remove unnecessary features from every approach

5. Present design

• Scale each section to its complexity
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, testing
• Design for isolation and clarity: break into smaller units with one clear purpose, well-defined interfaces, independently testable

---

Phase 2: Stress-test (Grill Mode)

The design tree

Map the design as a design tree: every decision branches into the decisions that hang off it.

Work the tree in rounds. The frontier is every decision whose prerequisites are already settled — the questions you can ask now without guessing at answers you haven't heard yet. Ask up to 4 frontier questions per ask_user_question call, each with 2-4 options when multiple choice. Wait for the answers, incorporate them, and recompute the frontier before the next call. A conceptual frontier may therefore require multiple user interactions.

Question format

Q1 - <question title>: <assertive question body; state your recommendation inside the question when possible>
> <your recommended answer>

Frontier rules

• Every answer reshapes the tree — settled decisions push the frontier outward and unblock questions that depended on them.
• After each ask_user_question call, incorporate all answers and recompute the frontier before selecting the next call.
• Never include a question in the same call as an unanswered prerequisite.
• Use 1-4 questions per call and 2-4 options per multiple-choice question.

Finding facts is your job, never the user's

When a frontier question needs a fact from the environment (filesystem, tools, docs), dispatch a sub-agent to find it — don't ask the user for anything you could look up yourself. Don't 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 to them and wait.

Anti-Pattern: "Yes-tail" (one question at a time near the end)

A common failure mode is to reach the end of a grilling session and ask a series of independent yes/no confirmations one at a time. Batch up to 4 currently-unblocked questions per call. After each response, recompute dependencies before selecting the next call.

When grilling is done

The session is done when the frontier is empty and you have a shared design concept: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms the design concept.

---

Phase 3: Write it up (Brainstorm Mode, final phase)

Checklist

You MUST complete these in order:

1. Explore project context — check files, docs, recent commits
2. Offer visual companion just-in-time — only when a visual question arises
3. Ask clarifying questions — assertively, with a recommendation; one at a time only when dependent; otherwise batch independent questions in one round (brainstorm mode), splitting into multiple ask_user_question calls as needed to stay within the 4-question/4-option limit.
4. Propose 2-3 approaches — with trade-offs and recommendation
5. Present design — in sections, get user approval after each
6. Grill the design — design tree, frontier rounds, stress-test every branch (grill mode)
7. Write design concept — save to .devin/specs/YYYY-MM-DD-<topic>-design.md as the conversation asset and commit
8. Spec self-review — quick inline check (see below)
9. User reviews written spec — ask user to review before proceeding
10. Transition to implementation — the spec is done. Pick the execution path:
    • planning (Tickets mode) — split into tracer-bullet vertical-slice tickets with blocking edges, then execution per ticket (canonical flow, matches ask-bundle router)
    • planning — turn the spec into a single detailed task-by-task implementation plan, then execution

The terminal state is leaving grilling for one of the two execution paths. Do NOT start implementing inside grilling — the spec is the deliverable here; execution happens in the next skill.

Design concept

Write the validated design — the conversation asset — to .devin/specs/YYYY-MM-DD-<topic>-design.md (user preferences for spec location override this default). Treat this as a design concept, not a transcript dump: it distills the grilled decisions into a reusable handoff for planning or planning.

Use this PRD structure:

• Problem Statement
• Solution
• User Stories (numbered, in "As a <actor>, I want <feature>, so that <benefit>")
• Implementation Decisions (modules, interfaces, schema, contracts)
• Testing Decisions (what makes a good test, which modules to test)
• Out of Scope

Commit the design concept to git.

Spec Self-Review

After writing the spec, look at it with fresh eyes:

1. Placeholder scan: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. Internal consistency: Do any sections contradict each other? Does the architecture match the feature descriptions?
3. Scope check: Is this focused enough for a single implementation plan, or does it need decomposition?
4. Ambiguity check: Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

Fix any issues inline.

User Review Gate

After the spec review loop passes, ask the user to review the written spec:

"Spec written and committed to <path>. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.

---

Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options. Available as a tool — not a mode.

Per-question decision: Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: would the user understand this better by seeing it than reading it?

• Use the browser for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams
• Use the terminal for content that is text — requirements questions, conceptual choices, tradeoff lists, scope decisions

A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is conceptual — use the terminal. "Which wizard layout works better?" is visual — use the browser.

If they agree to the companion, read visual-companion.md before proceeding.

---

Working in existing codebases

• Explore the current structure before proposing changes. Follow existing patterns.
• Where existing code has problems that affect the work, include targeted improvements as part of the design — the way a good developer improves code they're working in.
• Don't propose unrelated refactoring. Stay focused on what serves the current goal.

Process Flow

Explore context
  -> Ask clarifying questions (assertive, with recommendation; batch if >4 questions)
  -> Propose 2-3 approaches with trade-offs
  -> Present design sections, get approval per section
  -> Grill the design (design tree, frontier rounds, every question with recommendation)
  -> User confirms shared design concept?
     -> no: revise, re-grill
     -> yes: write design concept
        -> spec self-review (fix inline)
        -> user reviews spec?
           -> changes: revise, re-review
           -> approved: pick execution path
              -> planning (Tickets mode) -> implement (canonical)
              -> planning -> execution (detailed single plan)

Cross-skills

• If the topic depends on a library or framework the user just named, invoke context7 before the first round so you can ask informed questions.
• If the topic needs primary-source investigation (current docs, a spec, a paper), invoke research first and bring the findings into the grilling session.
• If the request might be too small for a full grilling session, invoke execution before entering grill mode.
• If the user uses AI-coding jargon loosely, invoke ai-coding-dictionary to align terms before the first round.
• learn-mode is the pedagogical counterpart: there the learner proposes first and the agent teaches; here the agent proposes and stress-tests. Keep them distinct, never blend mid-session.