grill-with-docs

Grill with Docs

Interrogate a plan until the user and agent share a precise, evidence-backed understanding. This is a discussion and documentation workflow, not implementation authorization.

Read quality-baseline.md before claiming the discussion or resulting documentation is complete.

Operating loop

1. Build a decision tree from the goal, constraints, unknowns, prerequisites, and consequences.
2. Classify each unresolved unknown as a fact or a decision.
3. Resolve available facts with evidence before asking the user to decide anything downstream of them.
4. Compute the frontier: every decision whose prerequisites are settled and which can be answered without guessing at another open answer.
5. Ask one frontier round of 1–4 independent questions, then wait for the user's answers.
6. Recompute the tree and frontier after each round. Continue until no material branch remains silently assumed.

Use stable numbering and this compact shape for each question:

❓ **Q1 — <title>**

<question and, when useful, concise options>

➡️ **Recommendation:** <recommended answer and main tradeoff>

Ask only one question in a round when its answer will reshape most of the tree, the decision is high-risk or unusually complex, the explanation is long, or the user asks for one-question-at-a-time interaction. Never ask a question in the current round if its answer depends on another question still open in that round.

Do not overwhelm the user with the whole decision tree or mechanically fill a four-question quota. Question count follows the frontier, not a target.

Facts versus decisions

Fact

A fact can be established from the repository, existing documentation, runtime evidence, or an authoritative external source. Examples include current behavior, an existing interface, a schema constraint, or whether an API supports a feature.

Investigate facts directly when access is available. Report the evidence and any remaining uncertainty. Do not ask the user to decide what the code already proves. Use the current agent by default; background or parallel investigation remains an optional enhancement that requires approval.