Grill With Docs

Grill With Docs

Interview the user relentlessly about their plan while maintaining domain documentation inline. Walk down each branch of the design tree, resolving dependencies between decisions one by one.

Workflow

1. Read the artifact — Read the plan, spec, or design. Understand the full scope before asking anything.

2. Explore the codebase — Before asking questions, look for existing documentation:

   • docs/context/GLOSSARY.md — domain language
   • docs/context/CODEBASE.md — context boundaries
   • docs/adr/ — existing architectural decisions
   • Code patterns related to the plan's domain

3. Interview one question at a time — Ask exactly ONE question per message. Never combine multiple questions in a single response, even if they seem related. For each question, state YOUR recommended answer first. Wait for the user's response before asking the next question. If a question can be answered by exploring the codebase, explore instead of asking.

4. Challenge against the glossary — When the user uses a term that conflicts with GLOSSARY.md, call it out: "Your glossary defines 'X' as Y, but you seem to mean Z — which is it?"

5. Sharpen fuzzy language — When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User?"

6. Discuss concrete scenarios — Stress-test domain relationships with specific scenarios that probe edge cases and force precision about boundaries.

7. Cross-reference with code — When the user states how something works, check whether the code agrees. Surface contradictions: "Your code does X, but you just said Y — which is right?"

8. Update GLOSSARY.md inline — When a term is resolved, update docs/context/GLOSSARY.md immediately. Do not batch. Create the file lazily if it doesn't exist. See glossary-format.md.

9. Update CODEBASE.md if needed — When context boundaries or relationships are clarified, update docs/context/CODEBASE.md. Create lazily. See codebase-format.md.

10. Offer ADRs sparingly — Only when all three criteria in adr-criteria.md are met. When warranted, explicitly state "Delegating to create-adr" and activate the create-adr skill to handle format, numbering, and file placement. Do not write ADR files directly.

11. Continue until covered — Keep going until all branches are resolved. Do not stop early.

12. Summarize and offer to apply — Summarize decisions made, then ask: "Want me to apply these changes to [artifact name]?"

Boundaries

DOES:

• Interview relentlessly about a plan or design
• Update GLOSSARY.md inline as terms are resolved
• Update CODEBASE.md when boundaries are clarified
• Delegate to create-adr when ADR criteria are met
• Cross-reference claims against code

Does NOT:

• Implement code changes
• Create ADRs directly (delegates to create-adr)
• Replace grill-me for quick artifact reviews
• Modify files without resolving terms first

Common Failures

• Batching glossary updates — write terms as they're resolved, not at the end. Users forget context.
• Creating ADRs too eagerly — most decisions don't need one. Apply the three-gate test strictly.
• Accepting vague terms — "the service handles it" is not precise. Push until the term has a one-sentence definition and an Avoid list.
• Bundling multiple questions — NEVER ask two questions in one message. If you have a follow-up, wait for the answer first. One message = one question. Always.
• Writing ADRs directly — When an ADR is warranted, you MUST say "Delegating to create-adr" and hand off. Do not write the ADR file yourself. The create-adr skill owns the format, numbering, and lifecycle.