grill-with-docs

name	grill-with-docs
description	Clarify a feature, refactor, architecture idea, or product plan against existing code and domain docs. Use when requirements, terminology, constraints, or success signals are unclear before to-prd, to-issues, triage, or implementation, and Codex should update CONTEXT.md or ADRs only when domain terms or decisions crystallize.

Grill With Docs

Run a focused clarification session. The goal is to make the idea clear enough for to-prd or a single agent-ready issue, not to expand it into every possible detail.

Read docs/agents/domain.md, relevant CONTEXT.md, ADRs, and nearby code only as needed.

Workflow

1. Establish The Frame

Summarize what you understand:

• Goal.
• User or actor.
• Current state.
• Desired outcome.
• Known constraints.
• Non-goals.

If any of these are unknown, ask concise questions one at a time.

2. Challenge The Idea

Probe for ambiguity that would block delivery:

• What behavior changes from the user's perspective?
• What is explicitly out of scope?
• What existing behavior must not regress?
• What would prove success?
• What terminology is unclear or inconsistent with the repo?
• Does current code already do some of this?

Prefer concrete scenarios and examples. Avoid broad brainstorming unless the user asks.

3. Update Docs Only When Durable

Use domain-modeling when a term or architecture decision becomes durable:

• Add or revise CONTEXT.md for domain vocabulary.
• Offer an ADR only for hard-to-reverse, surprising trade-offs.

Do not store feature requirements in CONTEXT.md. Requirements go to to-prd or an agent-ready issue.

4. Stop When Ready

Stop once the idea has enough:

• Problem and outcome.
• Capability summary.
• Key constraints and non-goals.
• Acceptance signals.
• Regression risks.
• Open questions, if any.

Do not keep interviewing for speculative details that slicing or implementation can discover later.

Finish

Return a concise readiness summary:

• Ready for to-prd.
• Ready for one agent-ready issue.
• Needs more user input.
• Needs code audit first.

List the remaining questions or risks, if any.