🔍 What is grilling
Grilling is a session where the agent asks questions before coding. It's not you listing requirements. It's the agent, acting as an adversarial interviewer, pulling you toward areas you haven't considered yet: edge cases, decisions you're putting off, assumptions you didn't even know you were making.
Most people use LLMs as glorified autocomplete: they give a vague prompt and accept the first code. The result: 3 rounds of rework. Grilling turns that around. The agent becomes the one who keeps asking, "what if the user has no connection?", "how do you want to handle duplicates?", "is this per tenant or global?"—before a single line is written.
🎯 The core principle
Bad code doesn’t come from a weak model. It comes from weak brief. Grilling forces the brief to become good before of spending tokens on implementation.
- • The agent doesn’t assume—it asks.
- • You don’t write a spec—you answer questions.
- • The alignment is written down, not just in your head.
💡 Why the inversion changes everything
When you writes the spec; you just list what you've already thought through. When the agent question, it explores the decision space you haven't seen yet. The agent has read a thousand similar systems — it knows where the bug lives.
The agent’s question is a map of what you didn’t yet know you needed to decide.
Key concepts
⚖️ /grill-me vs. /grill-with-docs
There are two flavors. Choosing the wrong one won’t break anything — it just wastes context. The /grill-me is lightweight and conversational, great for non-coding decisions. The /grill-with-docs is heavyweight, reads your CONTEXT.md and ADRs, and updates them at the end.
✓ /grill-me
- ✓Product decisions without heavy coding
- ✓Feature brainstorming before the PRD
- ✓Non-engineering: copy, positioning, flow
- ✓Output: decision bullets in the conversation
- ✓Doesn't touch project files
✓ /grill-with-docs
- ✓Engineering: feature, refactor, technical decision
- ✓Reads CONTEXT.md, ADRs, and the domain model
- ✓Updates CONTEXT.md and creates an ADR at the end
- ✓Output: persistent documents
- ✓Uses the project’s terminology, not generic terms
Direct comparison
| Aspect | /grill-me | /grill-with-docs |
|---|---|---|
| Input | Loose idea | Idea + indexed project |
| Reads files? | No | Yes — CONTEXT.md, ADRs, code |
| Does it write files? | No | Yes — update CONTEXT.md, create an ADR |
| Typical duration | 5–10 min | 15–40 min |
| Next step | Document manually | /to-prd directly |
📊 Practical rule
If the decision will become code — /grill-with-docs. If the decision stays only in your head — /grill-me. When in doubt, choose /grill-with-docs: the cost of generating one more ADR is zero; the cost of losing context is high.
Key concepts
🎯 When to use (and when NOT to use)
Grilling isn’t free — it costs 10 to 40 minutes. For trivial changes, that cost is greater than the rework it prevents. For architectural decisions, it’s the cheapest investment there is.
✓ USE grilling
- ✓New feature — first contact with the problem
- ✓Architectural decision — choice of database, queue, pattern
- ✓Confusing bug — you don't even know how to reproduce it
- ✓Refactor — before touching 20 files
- ✓Integration — third party, webhook, contracts
- ✓Migration — schema, framework, version
✗ SKIP grilling
- ✗Typo / trivial fix — one line, clear scope
- ✗Copy change — text that has already been approved
- ✗Version bump — no breaking changes
- ✗Convention already documented — follow the existing ADR
- ✗Bug with an obvious cause — clear stack trace
- ✗Pair programming session — human alignment already done
⚠️ Be careful with “seems trivial”
"Just add one field to the form" turned into a validation refactor, database migration, and API change across three different projects. When you hear "it's just a little thing" and it touches persistence or a contract—spend 10 min grilling it. You'll find out it's not quite "just" that.
Key concepts
💬 Example of a complete session
Realistic dialogue of /grill-with-docs about a common feature: "I want to add authentication." Notice how each question from the agent closes a decision that would become a bug if left implicit.
• Model: B2B multi-tenant, single DB with tenant_id
• Onboarding: Admin invites by email, no self-signup
• Auth: Magic link (phase 1), SSO (phase 2). One email per tenant
• Roles: owner > admin > member; owner only for billing
• Session: httpOnly server-side cookie, 7d, global revocation supported
• Lifecycle: last owner can't leave; soft delete by default
Ready for /to-prd?
💡 Important note
Notice that NONE of these 6 questions were in the original prompt, “I want to add authentication.” Each answer settled a decision that would have turned into a 2-hour meeting or a production bug. That's the ROI of grilling.
Key concepts
🚫 Grilling anti-patterns
Grilling is simple, but it has pitfalls. The common symptom: you finished the grill, but still feel that rework is coming. It’s almost always one of the three anti-patterns below.
✓ Healthy approach
- ✓Reject the agent’s first draft if it feels vague
- ✓Asks you to rephrase generic questions
- ✓Treats a "small" change that scales as a feature
- ✓For the grill when you realize the problem has changed
- ✓Say “I don’t know” when that’s true—and research before drawing a conclusion
✗ Anti-patterns
- ✗Accept the first draft without grilling — "this is good as is"
- ✗Swallowing vague questions like "how do you want to do this?"
- ✗Skipping the grill on a “trivial” change that touches a contract
- ✗Answer “it depends” to avoid making a decision
- ✗Not reviewing the final ADR — signs without reading
🚨 A vague question is a red flag
If the agent asks "how do you want to structure this?" — stop. That’s not grilling; the agent is throwing the decision back to you. Demand specificity:
Correct answer: "Give me 3 options with tradeoffs and ask which criterion matters so I can choose."
Key concepts
🔗 Integration with PRDs
Grilling isn’t a standalone event — it’s the first stage of a pipeline. Decisions become context, context becomes a PRD, the PRD becomes issues, and the issues become code. Everything is connected.
/grill-with-docs
Input: loose idea. Output: finalized decisions.
The agent reads CONTEXT.md, asks 5–10 targeted questions, and synthesizes the answers into named decisions.
CONTEXT.md updated
Decisions become permanent text.
The grill answers are recorded in CONTEXT.md (and, when architectural, in a numbered ADR in docs/adr/).
/to-prd uses the context
The PRD starts aligned, not from the LLM's imagination.
The /to-prd command reads CONTEXT.md + fresh ADRs and generates a PRD that cites the decisions. Without grilling, the PRD becomes fiction.
/to-issues breaks work into vertical slices
The PRD becomes end-to-end executable tasks.
Each issue is a vertical slice: UI + API + persistence + test. Not horizontal by layer. Issues inherit terminology from CONTEXT.md.
Implementation
Code comes out with a strong brief.
When the agent codes the issue, it has the ADR + PRD + issue. Rework drops by 60–80% compared to starting from a vague prompt.
📊 The chain is the product
Grilling alone produces a document. The grill → ADR → PRD → issues pipeline creates predictability. It’s the difference between “I use AI” and “I have a process with AI.”
Key concepts
🛠️ Practical exercise
Pick a feature you want to build today — not two weeks from now. Run /grill-with-docs and answer honestly. Don't game the grill by speeding through it.
I want to add [your feature in one sentence] to the project.
Do grilling before I write a PRD. I want questions specific, justifying why each one changes the implementation. One question at a time. If I give a vague answer, challenge it and ask again. At the end, summarize the decisions and propose the ADR.
📝 Take notes during the exercise
- •How many questions did the agent do before the synthesis?
- •Which 2 questions that you hadn't thought of and that surprised you?
- •Which decision changed direction during the grill? (a sign of a valuable grill)
- •Total time of the grill—compare it with your initial estimate.
- •The final ADR is there a decision you don't remember making? Mark it for review.
🎯 Success criteria
The exercise worked if, by the end, you can answer these without looking:
- • Which 3 irreversible decisions were made;
- • Which 2 decisions were explicitly deferred;
- • What would the next step be (run /to-prd? look for external data?).
Key concepts
✅ Module summary
Next module:
1.3 — From PRD to issues: breaking work into vertical slices