grill-decisions git:20261017.5b1062dA

Immutable. This exact content never changes and is served at /api/v1/blob/41f7c288456b6d34.

---
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.

Pass settled scope, acceptance/UAT, and execution/PR authority to `to-design` for the approved
contract. Distinguish approved decisions from missing authority; implementation requests and
available credentials do not silently approve a contract. Later new scope, authority, or criteria
decisions return here with evidence and a recommendation; settled decisions need no repeat approval.

## 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.