Planning: from idea to agent-executable spec

Most bad agent sessions aren't bad execution. They're bad specs. You start a build from a one-line prompt, the agent guesses at every decision you left unstated, and you pay for those guesses three files deep when the shape is already wrong. A better prompt won't save you. What works is a funnel that turns a vague idea into a plan detailed enough that the agent never has to guess.

This chapter is that funnel: a wide product conversation, a narrow grilling, then a locked spec cut into slices. By the time an agent touches code, every branch of the decision tree is already resolved.

Start wide, away from the repo#

The first pass doesn't happen in the repo. It happens in a plain Claude conversation on the web, with no code context, no tools, no CLAUDE.md, where the only subject is the product. What is this thing, who is it for, what are its dimensions, what stack does it want, what's explicitly out of scope. You argue about direction here, throw away three ideas, change your mind about the storage layer twice.

Two reasons this comes before any code. Iteration is cheap: there's no repo to break, no tests to keep green, no half-built module anchoring you to a decision you've outgrown. And it keeps your eventual coding session clean. A build session that also had to carry the entire "what are we even making" debate is drowning in context that no longer matters. Settle the product away from the code, then walk into the repo already knowing what you're building.

Bring it back and get grilled#

Now you take that rough spec into the repo and get interviewed about it. This is /grill-me, a skill written by Matt Pocock and published through AI Hero. Its whole instruction is short: interview me relentlessly about every aspect of this plan until we reach a shared understanding, walking down each branch of the design tree and resolving dependencies between decisions one by one. Three rules make it work. Ask one question at a time. Provide a recommended answer with each question. And if a question can be answered by exploring the codebase, explore the codebase instead of asking.

That last rule separates a grilling from a survey. The agent doesn't ask you what your data layer looks like. It goes and reads it, then asks the question that actually needs your judgment.

/grill-with-docs is the heavier variant, for when the project already has a domain model worth protecting. On top of everything /grill-me does, it challenges your language against the project's glossary ("your CONTEXT.md defines cancellation as X, but you seem to mean Y. Which is it?"), cross-references your claims against the code and surfaces contradictions, and updates documentation inline as decisions crystallize. Resolving a term writes it straight into CONTEXT.md. A decision gets an ADR only when it's hard to reverse, surprising without context, and the result of a real trade-off. Missing any of the three, the skill skips the ceremony.

Lock it: PRD, then slices#

Once the grilling converges, two more AI Hero skills turn the shared understanding into an executable artifact. /to-prd synthesizes the conversation into a product requirements document: problem, solution, an exhaustive list of user stories, the implementation and testing decisions, and what's out of scope. It deliberately does not re-interview you, because the interview already happened. It uses your project's own vocabulary and respects the ADRs in the area you're touching.

/to-issues then breaks that PRD into vertical tracer-bullet slices. This idea carries into the next chapter, so here it is precisely: a slice is a thin cut that runs through every layer end to end (schema, API, UI, tests), not a horizontal layer you finish before starting the next. A vertical slice is demoable on its own. A horizontal one is a pile of scaffolding that does nothing until the layer above it lands. Prefer many thin slices over few thick ones. Each slice becomes an independently grabbable issue with explicit acceptance criteria and its "blocked by" dependencies named, so a fresh agent can pick one up cold.

The proof: plans that don't get re-litigated#

You can see this on disk in this repo. docs/plans/ask-my-portfolio.md is a real, grilled spec: locked decisions in a table you're told not to re-litigate, an architecture diagram, and a dozen slices (A1 through A9), each with its tests-first list and dependencies. docs/plans/_orchestration.md is the companion dispatch graph for building it. The payoff is a single line from the bottom of that orchestration doc, describing when a sub-agent should stop and ask versus just ship:

Otherwise: ship the slices. The grilling has already happened — that's why this doc exists.

The plan doc is a record of every decision already made, so the build phase spends zero energy re-deciding. An agent picking up slice A6 weeks later doesn't reopen the storage-layer debate. It reads the locked table and executes.

Why the interview works: Pocock's argument#

The grill isn't a productivity hack someone stumbled into. Pocock has laid out a specific argument for it, in his workshops and in the skill writeups, and knowing the argument tells you when the process matters and when you can skip it.

The first piece is a constraint he calls the smart zone and the dumb zone. A model is at its sharpest early in a context window and degrades as the window fills. His whole workflow is shaped around that: resolve the ambiguity in one dedicated session, write the result down, and let every later phase start fresh at full intelligence, reading a small artifact instead of inheriting a long conversation. The PRD exists for the agent, not for you. Pocock is blunt that he doesn't tend to read his own PRDs. Their value is as input to the next fresh context.

The second piece is what planning is actually for. His words: "I needed to reach a shared understanding with Claude. I didn't need a plan. I needed to be on the same wavelength." An agent will always produce a plan if you ask for one, and the plan will be eager, plausible, and misaligned wherever your unstated assumptions differ from its guesses. The failure mode isn't a missing plan. It's the unshared assumptions underneath a confident one, and only an interview forces those out. That's also my answer to "why not plan mode": Claude Code's built-in plan mode proposes and asks you to approve the whole thing at once, while grilling extracts, one decision at a time, before anything can be guessed wrong. Plain plan mode is still enough when the change is small and well understood, like a contained refactor or a bug with an obvious fix, where there's nothing to interview about.

Third, the interview has to stand alone. Pocock observed that when a single prompt says "ask clarifying questions, then write the plan," agents rush the questions to get to the plan, because the plan feels like the deliverable. So the grill is solely the questioning phase, and turning the result into a PRD is a separate, manually invoked skill. He's equally clear that this phase is human-in-the-loop by nature. Everything else in the chain can run unattended; the alignment step can't, because the whole point is extracting what only you know.

Last, the paper trail, which is his stated reason for preferring the docs variant: "a plain interview sharpens your thinking and then evaporates when the session ends." /grill-with-docs writes each resolved term into CONTEXT.md and each hard-to-reverse decision into an ADR as it happens, so the alignment survives the conversation. Pocock himself has moved on from plain /grill-me for real builds and now starts with the docs-writing variant. Same here, on any project with a domain worth protecting.

For what it's worth, my own usage data agrees: running /insights over a month of session history flagged the grill → PRD → TDD chain as the thing my best sessions share. That's corroboration, though, not the argument.

The grilling has happened, the PRD is locked, the slices are cut. The next chapter turns that spec into merged, tested code across parallel agents.