Grill With Docs

Use this before implementation, when a change turns on a load-bearing assumption that one line can't settle — a rough idea, an ambiguous change, or a "before we code" direction that's still open. It's the deep-dive the assumption gate routes into when surfacing the assumption with a recommended reading isn't enough on its own.

Boundary With Plan With Docs

grill-with-docs is for deciding what the work should be. plan-with-docs is for writing the agreed implementation plan after the important decisions are settled.

Stay in grill-with-docs when any meaningful boundary is still unresolved:

• product behavior, user workflow, or success criteria
• architecture, migration, compatibility, or data-shape tradeoffs
• scope, non-goals, rollout, or reversibility
• affected callers or dependencies whose treatment requires an unapproved behavior or architecture choice
• verification strategy or acceptance criteria
• the right durable doc home for the decision

If the user asks to "plan" but these decisions are still open, say so in a line. Ask one sharp decision question, lead with your recommended answer and the one reason that decides it, then wait for the user's decision before turning it into a plan.

Workflow

1. Load the smallest relevant context:
   • AGENTS.md or the active agent instruction file
   • docs/overview.md
   • one codument context --paths <paths...> query for known scoped paths, or --feature <slug> for the relevant feature/concept docs; reuse it through planning and refresh only when discoveries or routing changes require it
   • docs/.registry.json when editing or assessing the whole map, or when the CLI is unavailable
   • relevant ADRs under docs/architecture/decisions/
2. Inspect code when docs can answer only part of the question.
3. Ask one sharp question at a time when a real product or architecture decision remains.
4. Lead with your recommended answer and the one reason that decides it.
5. Stress-test the answer against concrete scenarios, failure modes, and edge cases — in your head, before you write. Surface only a finding that would change the user's decision; the rest is yours to act on, not theirs to read.
6. Update the narrowest durable doc only after decisions settle, unless the user is explicitly brainstorming without file edits.

What To Challenge

• Fuzzy nouns: ask what object, actor, state, or workflow the user means.
• Scope drift: separate current scope, future scope, and explicit non-goals.
• Hidden interface changes: ask what callers, docs, tests, and dependents will be affected.
• Reversibility: identify choices that would be expensive to change later.
• Verification: ask what feedback loop will prove the change works.
• Costly infrastructure or a broad build: identify an early representative end-to-end user or integration experience. Name the observable milestone each infrastructure task unblocks, the effort it commits, and the cheapest useful experiment that could invalidate the approach. Reuse available evidence; ask only for an unresolved, load-bearing choice.
• Evidence: identify the observable user or integration boundary the outcome depends on. A local stand-in can test a contract, but it cannot establish an external effect or checks beyond that stand-in.
• Documentation fit: decide whether the decision belongs in a feature doc, concept doc, overview, ADR, or nowhere durable.

Rules

• Do not dump a questionnaire, and do not dump the analysis either. A comparison table plus a numbered rationale plus a "before you answer" section, all to ask one question, is the same failure as five questions at once — it just looks more diligent. One recommendation, one question, then stop.
• Do not start implementation during grilling.
• Do not write a delivery plan while the key boundary is still unsettled.
• Do not treat "use Codument" or "plan the work" as permission to skip grilling when product or architecture decisions remain.
• Do not create generic CONTEXT.md files when Codument docs already provide the project memory.
• Prefer updating existing docs over creating new ones.
• Keep docs compact: capture settled decisions, not the whole conversation.
• Scale the challenge to the uncertainty and cost. A small reversible fix or an already-settled choice needs no extra questionnaire or experiment gate; retain the existing approval workflow.
• After outcome approval, new implementation files and routine failed checks are discoveries to repair, not reasons to reopen grilling. Return here only when repair exposes an unapproved behavior or constraint decision; legacy file-bound plans retain their existing scope gate.