Grill For Unknowns

Docs + Unknowns Grill

Overview

The core idea is:

• The map = the prompt, plan, assumptions, skills, prior context, docs excerpts, and the agent's current mental model.
• The territory = the real codebase, product constraints, APIs, docs, user taste, deployment environment, and failure modes.
• Unknowns = the gap between the map and the territory.

This skill combines docs-grounded grilling, one-question-at-a-time interviewing, domain modeling, and a four-quadrant unknowns pass.

Grilling here means few, evidence-priced questions — not relentless interrogation; not asking about a non-material topic is correct behavior. The goal is to discover the few answers that would materially change the plan (see the Material criterion below) — and to write down the shared understanding as it forms.

When to Use

Use when:

• The user says not to rush implementation, asks for a stronger plan, or wants a rigorous planning pass before orchestrating implementation work.
• The task depends on unfamiliar docs, APIs, libraries, platform behavior, or source conventions.
• The user has a vague product/design desire and likely has unknown knowns: they will know good/bad when they see it, but cannot fully specify it upfront.
• The agent is about to spawn subagents or a long-running coding agent and needs a better launch packet.
• A previous attempt failed or is stuck because the agent made assumptions, overfit to generic best practices, or missed real codebase constraints.
• Reviewing a plan/spec/PR where you need to pressure-test hidden assumptions before merge.

Do not use when:

• The task is trivial, mechanical, or already has unambiguous acceptance criteria.
• The user explicitly wants immediate execution and the risk of wrong assumptions is low.
• You can verify the right answer directly with a single tool call and no interview is needed.

Operating Mode

Stay in Explore or Plan mode until the unknowns that could change the implementation are resolved or explicitly accepted as assumptions.

The grill has a defined end: it is over when the unknowns ledger is empty — every material unknown resolved, defaulted, or explicitly accepted. Announce the remaining count as it shrinks (e.g., "2 material unknowns left") so the user can see the end approaching.

Default sequence:

1. Restate the map — summarize the user's request, the intended outcome, and what is already known.
2. Read the territory — inspect the relevant docs/source/tests/config before grilling. Do not rely on vibes if docs or code are available.
3. Open a grill session ledger — use templates/grill-session.md when the session is complex enough to need a durable working doc.
4. Build the unknowns ledger — classify per the Unknowns Taxonomy below.
5. Build the domain ledger — identify fuzzy terms, overloaded concepts, vocabulary conflicts, and context boundaries. Use references/domain-modeling-add-on.md for CONTEXT.md / ADR rules.
6. Grill one decision at a time — follow the grill procedure below.
7. Propose defaults — for low-risk unknowns, choose a sensible default and label it as an assumption instead of blocking.
8. Persist shared understanding — update CONTEXT.md for crystallized domain terms and offer ADRs when the Domain Modeling criteria are met.
9. Create or revise the plan — see Implementation Plan Requirements below.
10. Ask for confirmation before build — do not enact the plan until the user confirms shared understanding, unless they explicitly authorize proceeding with labeled assumptions.
11. During implementation — keep implementation notes for deviations and newly discovered unknowns.
12. Post-implementation — produce an explainer and quiz/review checklist so the user understands what changed.

Unknowns Taxonomy

Use this table explicitly in the output when the task is ambiguous enough to justify it.

Docs-Grounded Grill Procedure

1. Gather evidence first

Before asking the user to decide, inspect available ground truth:

• Official docs for libraries/platforms/APIs.
• Local source files, routes, models, schemas, migrations, tests, and config.
• Existing project conventions and similar implementations.
• Error logs, CI failures, issue comments, PR diffs, or previous implementation notes.
• Reference implementations the user points to, even if in another language.

Fetch missing-but-retrievable docs; if docs cannot be accessed, say so and mark the claim as unverified.

2. Convert evidence into pressure-test questions

Good grill questions have all three properties:

• Material — the answer could change architecture, scope, UX, data model, security, permissions, or acceptance criteria.
• Grounded — the question points to docs/source behavior or a concrete uncertainty, not generic preference fishing.
• Answerable — the user can choose from options, approve a default, or supply a reference.

Bad grill questions:

• Obvious preferences that a competent agent can default.
• Exhaustive questionnaires before any research.
• Asking the user to answer things the code/docs can answer.
• Asking the user to verbalize taste they can only recognize when shown ("what does modern mean to you?") — route those to prototypes and references instead.
• Open-ended "anything else?" questions with no context.

3. Ask one material question at a time when blocked

If an answer is required to proceed, ask one question, explain why it matters, and give a recommended default. Walk the design tree branch-by-branch — do not dump the whole tree on the user at once.

Template:

Blocking question: <question>
Why it matters: <what changes if answer A vs B>
Evidence: <doc/source/test/reference citation>
Recommended answer: <default + rationale>
If you don't care: I'll proceed with <default>.

If multiple questions are useful but not blocking, keep them in the grill queue and ask the next unresolved material decision first.

Budget and exit rules:

• Default budget: ~5 blocking questions per session. Going beyond it requires asking the user whether to continue.
• Fatigue valve: if the user's answers turn short or impatient (one-word replies, "just pick"), stop interviewing — convert the remaining unknowns to labeled defaults and present them as one batch for veto.
• Once no blocking questions remain, do not keep asking one at a time: present the residual low-risk unknowns as a single assumptions list for veto.

Domain Modeling: Shared Language and ADRs

Grilling must also maintain shared language. During the grill, challenge fuzzy or overloaded terms immediately, compare the user's terms against existing CONTEXT.md, code identifiers, docs, and product copy, and update CONTEXT.md when a term crystallizes (glossary only — no plans, scratchpads, or ADR content).

Offer an ADR only when the decision is (1) hard to reverse, (2) surprising without context, and (3) the result of a real trade-off; otherwise record it in the session/implementation notes. See references/domain-modeling-add-on.md for file layout, formats, and examples.