git:20261009.1da8791 to git:20261017.5b1062d

---

name: grill-decisions

description: Challenges a plan against the project's existing domain model, sharpens its terminology, and writes what settles into CONTEXT.md and ADRs as it settles. Use to stress-test a plan against the project's language and documented decisions, or when arriving from find-unknowns with open questions to resolve.

---

# Grill Decisions

Interview the user relentlessly about a plan until every branch of the decision tree is resolved.

Challenge it against the project's existing domain language and recorded decisions, and write what

settles into canon as it settles.

## Stop before you start

This skill spends the user's attention, so it only runs with a human in the loop.

- No human present — an autonomous run cannot grill anyone. Stop and report what needs deciding.

- Nothing named to resolve — there is no plan or open question yet. Run `find-unknowns` first.

- The question is answerable from the codebase — read it instead of asking.

Investigate observable questions using code, configuration, tests, and available observations before

escalating them. For historical rationale, research recorded decisions and history; do not infer

intent from current code. Distinguish evidence, inference, and unresolved gaps. Small targeted

experiments must fit existing scope, permissions, and limits; this skill does not authorize

additional pilots, budgets, or outward actions.

Choose reversible implementation defaults within scope. Reserve the interview for preferences,

authority, acceptance changes, consequential tradeoffs, and questions the evidence cannot settle.

Bring evidence and a recommendation; explicitly defer irrelevant uncertainty with a reason.

## Process

### 1. Read the map

Read `.brain/CONTEXT.md`, the ADRs bearing on the area, and the nearest `AGENTS.md`. Absent or empty

canon is a legitimate state: note the gap and grill anyway.

Completion: every concept the plan touches is paired with the project's existing term or flagged as

unnamed, and every ADR the plan interacts with is listed.

### 2. Lay out the decision tree

Before asking anything, present the branches you intend to walk, in the order you intend to walk

them. Order by dependency: a branch whose answer constrains other branches goes first.

Showing the tree is what makes the session finishable. It gives the user a progress signal, lets

them add a branch you missed, and lets them cut one they consider settled.

Completion: the user has seen the branch list and agreed it is the right shape.

### 3. Walk the branches

Ask one question at a time and wait for the answer before the next one. For each question, give

your recommended answer, so agreeing is cheap and disagreeing is specific.

If a question can be answered by reading the codebase, read the codebase instead of asking. The

user's attention is the scarce resource in this skill.

For each unresolved branch, state the cheapest next action and whether it blocks the current

decision. Initiative uncertainty belongs in the active design; Beads owns execution state.

Four moves carry the grilling:

- **Challenge against the glossary.** When a term conflicts with `CONTEXT.md`, say so immediately:

"Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"

- **Sharpen fuzzy language.** When a term is vague or overloaded, propose a precise canonical one:

"You're saying 'account'. Do you mean the Customer or the User? Those are different things."

- **Discuss concrete scenarios.** Invent scenarios that probe edge cases and force precision about

where one concept ends and the next begins.

- **Cross-reference with code.** When the user states how something works, check whether the code

agrees, and surface contradictions: "Your code cancels entire Orders, but you just said partial

cancellation is possible. Which is right?"

Answers spawn new branches; add them to the tree rather than following them immediately and losing

your place. A branch the user declines to settle is deferred with a reason, not silently dropped.

Completion: every branch on the tree is resolved or explicitly deferred with a reason, and the tree

has no branch you added but never returned to.

### 4. Hand off

Report what the session produced: branches resolved, branches deferred and why, terms added or

sharpened in `CONTEXT.md`, and ADRs written. Recommend `to-design` when the resolved shape is a

multi-step initiative.

## Inline canon updates

Canon is written during the walk, not batched at the end. A term resolved in question three is

written before question four, because a session that ends early still leaves the project better off.

- **Terminology** goes into `CONTEXT.md` the moment it resolves, using

[context format](references/context-format.md). Keep it to terms meaningful to a domain expert; leave

implementation detail out.

- **Decisions** become ADRs only when they pass the three-part test in

[ADR format](references/adr-format.md), which also owns the format and numbering. That test is the

single source for when any skill offers an ADR.