grill-with-docs: The Skill That Asks Before It Codes

Last week I wrote a feature that can't exist. My finetwork MCP server would push monthly spending alerts to the user. It looks fine. MCP over stdio has no push channel, so "pushed to the user" is impossible.

No agent would have told me. It would have built it and handed me confident code for the wrong thing.

So I gave the brief to a skill whose whole job is to ask first. grill-with-docs lives in Matt Pocock's 159k-star repo, is six lines of markdown, and refused to plan until it questioned me about my own server.

A skill that interviews you

You hand it a rough feature and instead of coding it interviews you, one question per turn with a recommended answer, until the design is settled. The answers become two files that survive the chat, a CONTEXT.md glossary for your project's vocabulary and Architecture Decision Records for the choices a future reader would trip on.

I started it with one line.

/grill-with-docs I want to add two features to this MCP server: downloading invoice PDFs, and monthly spending alerts pushed to the user

In 63 seconds it read my source and README, opened with "Quick facts I gathered so I don't have to ask you about them", and named the stdio problem before asking me anything. The impossible feature became an external scheduled agent that calls the server. Question one alone paid for the session. Whole run, interview plus code, $8.54.

Then I got impatient on purpose. By turn 6 I broke the glossary, added multi-account support for my flatmate that no question had touched, and closed with "just start coding it now", which every product owner eventually says.

The spec says do not build until the user confirms shared understanding.

It coded everything immediately. So the stop gate is softer than it reads.

The next failure needed a fresh session, which opened with the best thing the skill did all week. It read the earlier CONTEXT.md and ADR on its own and reasoned from them before I asked anything. That was the click. The docs stopped being a file format and became a colleague with memory.

Then I grilled a stdio-to-HTTP migration I said I would build some other month. It wrote the new ADR as accepted and stamped the ADR for the architecture running today as superseded. Anyone reading docs/adr/ now believes the unbuilt design is live. The prose is careful. The machine-readable fields lie.

The skeptic says it's just a prompt you could type yourself. On a clean clone I typed one sentence and got most of the interview for about the same cost. What the sentence can't do is persist. When the chat ends everything is lost, while my second session started already informed, and those persistent docs are exactly where the ugliest failures live.

The top comment on the launch video reads "AI is really just a way to trick engineers into writing good documentation." It's more true than intended. The trick works, and then the docs it tricked you into writing need a code review of their own. I'm keeping it anyway, with that review as a fixed rule.

The day v1.1 patched my review

I published the failures above and the same day Matt shipped v1.1, which fixed two of the exact ones. The stop-gate collapse now has a real confirmation gate, a line that tells the agent not to enact the plan until you confirm you've reached shared understanding, because people on various models saw the interview end and go straight into building.

The self-grilling bug got a facts-versus-decisions split, facts are what the agent finds by reading the codebase and decisions are what you make. Matt says that bug was hitting Fable (one of the Claude models) especially. So the author is folding grill-with-docs into a bigger system, fast, and updating it faster than I can break it.

Here is the v1.1 family, one line each. Five of these sit on the main plan-to-code line; research, prototype, and tdd are helpers you reach into at specific moments.

• wayfinder is the new big one, a planner for a job too large for a single agent session, charting the work as a map of GitHub issues with blocking sub-issues each scoped to one session. Use it when the plan is foggy and spans many sittings.
• to-spec was to-prd, and it turns a finished plan into a specification. Use it once planning is done, to fix the destination.
• to-tickets was to-issues, and it splits that spec into tickets. Use it to spread the build across sessions.
• implement is deliberately tiny, it only builds a ticket and never interviews. Use it as the opposite of grill-with-docs.
• code-review runs two parallel agents, one for your standards and one for spec faithfulness, and now names Martin Fowler's refactoring smells like mysterious name and feature envy. Use it after implementing.
• research spins up a background agent that writes findings to a note while you keep working. Use it for an AFK research task.
• prototype builds a throwaway logic or UI prototype to raise the quality of the discussion before you spec. Use it when "how should it behave" is the real question.
• tdd is now reference-only, red before green, one slice at a time, with refactoring moved out into code-review. Use it inside implement.

The grilling engine itself got sharper, and since grill-with-docs runs on that shared engine, every fix above flows straight into it.

One decision keeps this simple. One feature in one session means grill-with-docs. A big plan across many sessions means wayfinder, which Matt now defaults to because most real work spans more than one session. Everything to the right of the plan, to-spec, to-tickets, implement, and code-review, is shared by both paths, so the only real fork is which planner you start with.

Before you run it

• The interview deserves the stars. It found my architecture's real constraint in 63 seconds, from a one-line brief.
• The stop gate was softer than the spec. "Just start coding it now" broke it, though v1.1 adds the confirmation gate that targets exactly this.
• Never trust an ADR status field it writes. Mine marked unbuilt work accepted and the live architecture superseded.
• A one-sentence prompt gets you most of the interview. The persistent docs are what you're paying for, so review them like code.
• grill-with-docs is now the front of a full lifecycle, not a standalone tool. Reach for wayfinder when the plan is too big for one session.