🥮 skills.mooncakes.ioexperimental

grill-with-docs

// Relentlessly interview the user to sharpen a plan, design, decision, proposal, or idea while updating the project's domain glossary and recording only durable architectural decisions. Use when the user asks to be grilled with documentation, wants terminology resolved during planning, or wants CONTEXT.md and appropriate ADRs maintained as decisions crystallize.

moon runwasm

moon runwasm Yoorkin/grill-with-docs@0.1.0

$ files

SKILL.md

readonly

Grill With Docs

Run one integrated workflow: a dependency-aware grilling interview plus active domain modeling. Do not treat documentation as a final batch. Update the glossary and offer durable decision records at the moment each answer crystallizes.

Do not implement the plan during this session. Continue until the user confirms shared understanding or explicitly stops early.

Orient to the repository

Before asking design questions:

Inspect the relevant code, existing CONTEXT.md files, CONTEXT-MAP.md, and ADRs.
If CONTEXT-MAP.md exists, use it to select the relevant bounded context. Ask only when the correct context remains ambiguous after inspection.
Treat code and existing documents as evidence, not unquestionable truth. Surface contradictions between them and the user's statements.
Create documentation lazily. Do not create CONTEXT.md or docs/adr/ until a real term or ADR-worthy decision exists.

Build the design tree

Model the subject as a design tree: each decision branches into the decisions that depend on it.

Identify the root goal or decision. If the user has not supplied one, ask for it.
Decompose it into decisions and explicit prerequisite relationships.
Turn unresolved assumptions, terminology conflicts, and boundary ambiguities into nodes.
Track settled, open, and blocked nodes. Reshape the tree whenever an answer reveals a dependency, contradiction, risk, or new branch.

The frontier is the set of open decisions whose prerequisites are settled. Ask only frontier questions; never guess an unresolved prerequisite.

Interview in rounds

For each round:

Recompute the frontier.
Ask the whole frontier, numbered. If it contains one decision, ask one question.
Give a concrete recommended answer and brief rationale for every question.
Wait for the user's answers before beginning another round.
Apply the answers to the tree, update domain documentation immediately where warranted, then recompute the frontier.

Use this format:

❓ **Q1** - **<question title>**: <question body, with choices or a concrete scenario when useful>

➡️ <recommended answer and brief rationale>

---

❓ **Q2** - **<question title>**: <question body>

➡️ <recommended answer and brief rationale>

Omit the separator after the final question.

Find facts; ask for decisions

Investigate facts available from the filesystem, codebase, documentation, tools, APIs, and other accessible sources instead of asking the user.
When supported, delegate independent factual investigations without blocking unrelated frontier questions.
Treat an unfinished investigation as a prerequisite that blocks only its downstream nodes.
Present decisions to the user with recommendations. Never silently decide on the user's behalf.

Maintain the domain model inline

Challenge and sharpen language

Call out conflicts with the existing glossary immediately.
When a term is vague or overloaded, propose one precise canonical term and distinguish nearby concepts.
Stress-test relationships with concrete edge cases.
Check claims about behavior against the code; ask the user to resolve contradictions.

Update the glossary

When a term is resolved, update the correct CONTEXT.md immediately. Keep it a glossary, never a spec, scratchpad, or implementation log.

Use this embedded format:

# <Context Name>

<One or two sentences describing the context and why it exists.>

## Language

**<Canonical Term>**:
<One or two sentences defining what the concept is.>
_Avoid_: <synonym or overloaded alternative>, <another alternative>

Apply these rules:

Pick one canonical word when synonyms compete; list discouraged alternatives under _Avoid_.
Define what a concept is in one or two sentences, not its implementation.
Include only project-specific domain concepts, not general programming vocabulary.
Group terms under subheadings only when natural clusters emerge.
For a single context, use root CONTEXT.md.
For multiple contexts, keep root CONTEXT-MAP.md with links and short relationship descriptions; place each glossary in its context.

Offer ADRs sparingly

Offer an ADR only when all three conditions hold:

Reversing the decision later would be meaningfully expensive.
A future reader would find the choice surprising without its context.
Genuine alternatives existed and the decision resolves a real trade-off.

If any condition is absent, do not create an ADR.

Store ADRs under the relevant docs/adr/ directory. Scan existing names, increment the highest four-digit number, and use <NNNN>-<slug>.md.

Default to this minimal format:

# <Short decision title>

<One to three sentences stating the context, decision, and reason.>

Add status, considered options, or consequences only when they preserve important non-obvious information.

Completion

The interview is complete when the frontier is empty: all reachable branches are settled and nothing material remains silently assumed.

Summarize the shared understanding, glossary changes, ADRs created, explicitly accepted risks, and any remaining factual follow-ups.
Ask the user to confirm shared understanding.
Do not implement the plan before confirmation.
If the user identifies a gap, add it to the tree and resume. If the user stops early, distinguish that from a fully resolved tree.

Origin

This self-contained adaptation combines Matt Pocock's grill-with-docs, grilling, and domain-modeling workflows, including the official glossary and ADR formatting rules.

$ cat moon.mod

Author