yokeloop Grill with docs
Interview the user relentlessly about every aspect of this plan until reaching a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
Ask one question at a time through the AskUserQuestion tool, waiting for the answer before continuing. Use a short header (≤12 chars) per question, and present 2–4 options with the recommended answer first, labelled (Recommended) and a one-line rationale; the user can pick "Other" to answer free-form. A later question usually depends on an earlier answer — resolve the branch in order, don't batch unrelated questions.
If a question can be answered by exploring the codebase, explore the codebase instead.
$ARGUMENTS — the plan, design, or topic to grill. If empty, ask via AskUserQuestion what they want to be grilled on.
Domain awareness
During codebase exploration, also read the git memory: the affected files' commit history per ${CLAUDE_PLUGIN_ROOT}/skills/gca/reference/history-reading.md — a past Rejected: or Constraint: trailer is grill material, cite it when challenging the plan.
During codebase exploration, also look for existing documentation:
File structure
A single glossary and a single ADR directory for the whole repo, under .yoke/:
/
├── .yoke/
│ ├── context.md
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
Create files lazily — only when there is something to write. If no .yoke/context.md exists, create it when the first term is resolved. If no .yoke/adr/ exists, create it when the first ADR is needed.
During the session
Challenge against the glossary
When the user uses a term that conflicts with the existing language in .yoke/context.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
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? Those are different things."
Discuss concrete scenarios
When discussing domain relationships, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
Cross-reference with code
When the user states how something works, check whether the code agrees. On finding a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
Update the glossary inline
When a term is resolved, update .yoke/context.md right there. Don't batch these up — capture them as they happen. Use the format in reference/CONTEXT-FORMAT.md.
Keep .yoke/context.md free of implementation details. Do not treat it as a spec, a scratchpad, or a repository for implementation decisions. It is a glossary and nothing else.
Offer ADRs sparingly
Only offer to create an ADR when all three are true:
- Hard to reverse — the cost of reversing it later is meaningful
- Surprising without context — a future reader will wonder "why did they do it this way?"
- The result of a real trade-off — there were genuine alternatives and one was chosen for specific reasons
If any of the three is missing, skip the ADR. Use the format in reference/ADR-FORMAT.md.
Rules
- One AskUserQuestion per question. Wait for the answer before moving on.
- Every question must offer a recommended answer first; the user may answer free-form via "Other".
- Stop when a full pass down the decision tree surfaces no new open decisions. Around 15 questions, check in: ask whether to keep going or wrap up.
- Capture terminology in
.yoke/context.mdand decisions in ADRs inline, lazily — create files only when there is something to write. - End the session by summarising the resolved decisions and confirming what was written to
.yoke/context.mdand.yoke/adr/. - For a plain interview without documentation maintenance, use
/yoke:grill. - Language: match the user's language, or follow the project-level definition in CLAUDE.md / AGENTS.md.