Grilling

Attack the premise before it becomes code

A wrong fix costs one cycle. A wrong frame costs every cycle until someone questions it, and nothing in the normal workflow questions it: review checks the diff against the plan, tests check the code against the spec, and both pass happily while the spec answers the wrong question.

Adapted from Matt Pocock's grilling skill (github.com/mattpocock/skills, MIT). The tree-and-frontier mechanic is his. What is added here is the fact-finding rule made mandatory, the interaction shape this harness actually has, and an explicit list of what not to grill.

The tree and the frontier

Map the plan as a tree of decisions. Each decision branches into the decisions that hang off it: choosing a queue implies choosing a delivery guarantee, which implies choosing what a duplicate costs.

The frontier is every decision whose prerequisites are already settled — the questions that can be answered right now, without waiting on another open one. Work in rounds:

1. Compute the frontier.
2. Ask the whole frontier in ONE round. Not one question at a time: a plan interrogated serially takes twenty turns and the user stops answering.
3. Each answer settles a decision and expands the frontier with whatever it unblocked.
4. Repeat until the frontier is empty.

A question whose answer depends on an unresolved decision belongs to a later round. Asking it early produces an answer the user will retract.

Finding facts is YOUR job

Never ask the user something the repo, the filesystem, or the network can answer. Which database is in use, whether an endpoint exists, what the current schema is, whether a library is already a dependency, what the last migration did — go and read it. Every fact you ask for is a question the user has to look up on your behalf, and it buys nothing that a grep would not.

Ask only about intent, priority, and tradeoff: what this is for, who it is for, what must not break, what you are willing to give up, what happens if it is wrong. Those are not in the repo.

This is the same discipline as the options protocol's vet-before-you-offer: do the lookups first, then write the questions out of what you learned.

How to ask, in this harness

Every question carries your recommendation, and the reason lives in the first clause. A question without one pushes the ranking work back onto the person you are supposed to be helping.

• Frontier of 4 or fewer — use AskUserQuestion. It is clickable and the answers come back structured.
• Frontier larger than 4 — use numbered prose instead. AskUserQuestion caps at four questions of four options, so a wider frontier would have to be truncated, and silently dropping a decision from a design tree is far worse than a less clickable turn. Number them so the user can answer 1b, 2a, 3 — own everything:

Q1 — <the decision, as a question>
     a) <option>   b) <option>   c) <option>
  -> recommend (b): <reason, first clause>

Keep the recommendation honest. It is what you would do if the user said nothing at all, not the safest option and not the one that flatters the plan you have already half-built.

What NOT to grill

Grilling everything is a failure mode of its own — it reads as diligence and produces a backlog of answered questions nobody needed.

• Reversible, in scope, obvious. Decide it and say you did.
• Anything already decided and written down. Read DECISIONS.md and the project rules first; re-litigating a settled call wastes the user's time and suggests you did not look.
• Preferences with a conventional default. Pick the convention.
• The same question in three costumes. Two questions that collapse into one action are one question.

Finish by stating the understanding

When the frontier empties, write the shared understanding back in a short block: what is being built, for whom, what it explicitly will NOT do, and the decisions that were settled with their answers. That block is the artifact — it goes into DECISIONS.md or the spec, because a decision that lives only in this conversation is invisible to the next session and will be re-made differently.

Then say what you are going to do first.