Grill

grill — sharpen idea into PRD

Stateful wrapper around the grilling discipline. Runs the interview (frontier rounds, recommended answers, facts as the agent's job) and lands every decision in PRD.md or CONTEXT.md. Never guess a requirement into existence.

Plan-then-execute guesses the fuzzy parts and builds the wrong thing. Grill drags the fuzz into PRD.md before a single task exists. A bad assumption caught here costs one question; caught in LESSONS.md it costs a bug.

OWNERSHIP

Owns: the plan folder + PRD.md + CONTEXT.md glossary updates (may invoke the domain-modeling discipline for the active glossary work). Runs: the grilling discipline for the interview itself. Hands off to: design (→ ARD.md), or spec (→ SPEC.md) for right-sized work. MUST NOT write ARD.md, SPEC.md, PLAN.md, or LESSONS.md.

WHEN (user-invoked)

• Idea is one sentence and you can feel the holes.
• Multiple readings of the goal exist and you are about to pick one silently.
• Before design / spec on anything non-trivial.
• User asks to be challenged / stress-tested / grilled.

Skip for a typo or a one-line fix. Grill scales to uncertainty, not ego (§11).

STEP 0 — READ EXISTING STATE

Before the first question:

1. Read CONTEXT.md at repo root if it exists — use its canonical terms.
2. Resolve the active plan per §6 (user names it, context matches slug, most-recently-modified, then ask). If none active, you will create one.
3. Read any existing PRD.md in the active plan to avoid re-asking settled points.

STEP 1 — CREATE THE PLAN FOLDER

If no active plan, create one:

docs/plans/<yyyy-mm-dd>-<type>-<slug>/

• yyyy-mm-dd — today's date.
• type — fix, feature, spike, refactor, chore, docs, test.
• slug — short hyphenated description, from the user's own words.

Ask the user to confirm type + slug if ambiguous. Create the folder + an empty PRD.md (written in step 4).

STEP 2 — CALIBRATE FIRST

One opening read, not a quiz. Match the grilling to it:

1. How well does the user know this domain? (sets question depth)
2. How locked is the idea? (exploring vs committed)
3. Pressure wanted: light / normal / brutal.

Brutal grilling on a half-formed idea just demoralizes. Light grilling on a committed plan misses the load-bearing flaw.

STEP 3 — RUN THE INTERVIEW (grilling discipline)

Run the grilling discipline for the interview mechanics: design tree, frontier, rounds (whole frontier in one round, numbered, recommended answers), facts as the agent's job with non-blocking helper dispatch.

Seed the frontier with the question ladder below — climb in order of dependency, not by reflex. Stop the moment the PRD would be unambiguous.

1. Goal — what must the code do, in one line? (→ PRD.md § Goal)
2. Done — how do we know it works? name the observable. (→ PRD.md § Done)
3. Boundary — what is explicitly out of scope? (→ PRD.md § Out of scope)
4. Lock — what tech/lib/pattern is non-negotiable? what is forbidden? (→ PRD.md § Constraints)
5. Surface — what does the outside world touch — cmd, api, file, env? (→ PRD.md § Interfaces sketch)
6. Edge — the one input that breaks the happy path? (→ park as future invariant)
7. Unknown — what do we not know yet? (→ park as ? in PRD.md § Open questions)

If a question can be answered by exploring the codebase, explore the codebase instead of asking the user — grilling rule: facts are your job.

Terminology

When a term is fuzzy or overloaded mid-interview, coin a canonical term and write it to CONTEXT.md immediately (or invoke the domain-modeling discipline for the active sharpening). Every name in the PRD MUST align with the glossary.

STEP 4 — WRITE PRD.md

Write PRD.md in the plan folder using caveman compression. Template:

# PRD — <slug>

## §G GOAL
<one line, what the code must do>

## §C CONSTRAINTS
- <non-negotiable boundary>
- <tech/lang/lib locked>
- <explicitly forbidden>

## §O OUT OF SCOPE
- <boundary>

## §I INTERFACES (sketch)
- <external surface: cmd / api / file / env>

## §D DONE
- <observable that proves it works>

## §V INVARIANTS (proposed, for ARD/SPEC)
- <rule that must hold>

## §Q OPEN QUESTIONS
- ? <blocking unknown>

Right-size: a one-line fix gets a minimal PRD (§G + §D only). A small feature gets §G + §C + §D. Only genuinely uncertain or high-blast-radius work runs the full set.

WHEN TO STOP

Done when ALL hold (grilling's frontier is empty AND):

• §G is one line, one reading, zero "or maybe".
• §C covers every non-negotiable the user stated or implied.
• Every blocking unknown is either answered or parked as an explicit ?.
• Every new term is in CONTEXT.md.

Unresolved blocking unknown that needs the outside world → recommend the research loop, not a guess.

HANDOFF

Emit a compact block — goal line, constraint bullets, surfaced unknowns as ? — and tell the user the next step:

• High-blast-radius or structurally uncertain → design (produces ARD.md).
• Straightforward but detailed → spec (produces SPEC.md).
• Already clear and small → plan (produces PLAN.md).

BOUNDARIES

• MUST NOT make product decisions for the user. Recommend, never decide.
• MUST NOT write ARD.md, SPEC.md, PLAN.md, or LESSONS.md. Hand off.
• MUST NOT re-implement the interview — run the grilling discipline.
• MUST NOT grill a trivial change. Right-size or skip (§11).
• MUST read CONTEXT.md and use canonical terms throughout.