grill-with-docs

What it's for

grill-with-docs sharpens an idea by interviewing you, and writes down what gets settled as it goes. It's two Skills in one: grilling, the interview, and domain-modeling, which keeps the project's words and decisions on disk.

The interview works in rounds. Each round, the agent asks every question it can ask right now, numbered, each with its recommended answer, worded so "yes" accepts it. Your answers open up the next round. Looking up facts in the code is the agent's job; the decisions are yours. It's done when nothing is left unasked or silently assumed, and the agent doesn't act until you agree you've reached a shared understanding.

When to use it

It's the first step of the Main flow: you have an idea, and you're working in a repo. Say you want waitlists in your FastAPI booking backend, or a new tool for your AI agent.

It runs the same interview as grill-me, and also leaves a paper trail in the repo. That makes it the better of the two whenever a repo is there.

When not to use it

• No repo, just a plan or a piece of writing: use grill-me. Same interview, nothing saved.
• An effort too big and foggy for one session, like a whole new product: use wayfinder. grill-with-docs is for an idea you can hold in one session.
• A question talk can't settle, like whether a state model holds up or what a page should look like: detour through prototype, then come back.

What it needs to start

An idea, however rough, and a working directory. setup-matt-pocock-skills should already have run, since it comes before your first engineering Flow. The Glossary and ADR files don't need to exist yet.

What it creates

• A shared understanding of the idea, in the conversation. Keep working in that same session through the Spec and Tickets, so they build on the same thinking.
• Glossary entries in GLOSSARY.md, written the moment a term is settled. When you use one word two ways, say "account" for both the customer and the login, the agent asks which you mean. The Glossary holds words only, never implementation details.
• ADRs, offered sparingly. An ADR (architecture decision record) is a short file recording one decision, and it's offered only when the decision is hard to reverse, surprising without context, and the result of a real trade-off.

Files are created only when there's something to write.