The Chunking Policy: What to One-Shot

The Tradeoff: Speed vs. Reviewability

Chunk size is the most consequential dial in agentic coding, and most engineers set it by feel. The two poles are easy to see:

• Big chunks buy speed and coherence. One prompt, one generation, one internally consistent design. The agent holds the whole problem in context, names things consistently, and wires the pieces together itself. A working app can exist twenty minutes after the idea does. The cost: the output arrives as a single large diff, and your ability to actually verify it drops fast as the diff grows.
• Small chunks buy control and reviewability.Every generation is small enough to read line by line, test in isolation, and reject cheaply when it is wrong. The cost: orchestration overhead. You are now sequencing prompts, carrying context between them, and re-explaining the architecture every few steps. Chunk too small and you have reinvented typing the code yourself, one dictated paragraph at a time.

Neither pole is right, and the popular tiebreakers are wrong. Some engineers pick chunk size by model capability — "the new model can handle bigger prompts, so go bigger." Others pick by personal comfort — whatever chunk size they used last week. Both miss the actual variable: what happens if this code is wrong, and who has to know it is right?

Disposable code tolerates unreviewed generation. If a prototype has a subtle bug, the demo hiccups and you regenerate — total cost, minutes. Production code cannot outrun your review bandwidth. If a candidate-pipeline write path has a subtle bug, it corrupts records quietly for weeks, and the only defense that exists is a human who actually read and understood every line before it merged. Review bandwidth — how much diff you can genuinely comprehend in one sitting, not skim — is a hard budget. Production chunks must fit inside it. Disposable chunks do not have to.

So the rule that organizes this entire module: chunk size is a function of consequence, not of model capability. The model being able to generate 3,000 good lines in one shot does not mean you can verify 3,000 lines in one sitting — and for code that matters, verification is the bottleneck, not generation. When models get better, the ceiling on what a one-shot can do rises; the ceiling on what you can review does not move at all.

The House Policy

Here is the policy, verbatim. It has two modes, selected by one question: how good does this code need to be?

Notice what the policy does not say. It does not say "one-shot when the task is easy" — plenty of easy tasks are production tasks and get sliced anyway. It does not say "slice when the task is big" — a big POC still gets one-shotted, because regenerating a big POC is cheaper than orchestrating it. The selector is the quality bar, full stop. And notice that even the maximum-speed mode is not zero-process: the one-shot happens after a plan with a diagram, for reasons the next section makes concrete.

Quality is not binary, so here is the policy expanded into the tiers you will actually encounter. Find your row before you write the prompt:

The table has a shape worth internalizing: as consequence rises, chunk size shrinks and process grows — smoothly, not as a cliff. The two named modes of the house policy are the anchor rows (POC and production feature); the other rows are interpolations you should be able to defend in a code review. If a teammate asks "why did you one-shot this?" or "why are these slices so thin?", the answer is a row in this table, not a mood.

Plan-First: Why Even a One-Shot Gets a Diagram

The POC mode says "one-shot the whole thing" — and still demands a plan with a Lucidchart diagram before the prompt goes out. This is not ceremony. The diagram does two jobs, and the first one has nothing to do with the agent.

Job one: it forces you to know what you want.Post-mortem enough failed one-shots and a pattern emerges: most of them are specification failures, not model failures. The agent built a queue when you wanted a scheduler, guessed wrong about where state lives, or invented an entity model you never described — because you never described it. The model filled every gap in your ask with a plausible default, and plausible-but-wrong compounds across an entire one-shot. Drawing the diagram is the cheapest possible test of whether the system exists in your head. If you cannot draw the boxes and arrows — what the components are, what flows between them — you are not ready to prompt, and the one-shot was going to fail in a way you would have misdiagnosed as a model problem.

Job two: it gives the agent an unambiguous target.Prose specs leak ambiguity; a diagram pins down the architecture in a form the agent cannot misread. Boxes name the components, so the agent does not invent its own decomposition. Arrows name the flow, so the agent does not guess the sequence. The diagram converts "build me something like X" into "build exactly this shape," and the delta between those two prompts is most of the difference between a one-shot that lands and one that comes back as somebody else's idea.

This is the CTO board's planning discipline, scaled down. The planning module mandates three artifacts before serious work. A POC does not need all three — the code is disposable, so the plan can be light — but it never drops to zero: for a POC, one diagram is enough, and one diagram is required. The artifact scales with consequence exactly the way chunk size does, and in the same direction: production work gets the full artifact set; a POC gets the single highest-leverage artifact, which is the diagram.

The one-shot prompt itself has a standard shape. Four parts, in order:

• Context. What this is, who it is for, what exists already. Two or three sentences — enough that the agent's thousand small defaults (naming, tone, storage choices) land near your intent.
• The diagram. The Lucidchart export, plus a short prose walk-through of it: components, responsibilities, what flows along each arrow. The diagram is the spec's spine; the prose is its annotation.
• Constraints. Stack, libraries, what to fake (auth, payments), what to hardcode, what NOT to build. For a POC the not-list matters most — it is what keeps a twenty-minute one-shot from becoming a two-hour one.
• Definition of done. The demo script, stated as behavior: "I open the dashboard, upload this CSV, and see ranked candidates with scores." A one-shot with a checkable finish line is a task; without one it is a vibe.

Production Mode: Vertical Slices

Production work inverts the priorities: reviewability now dominates speed, so the chunk shrinks until it fits inside one honest review sitting. But it must not shrink in the wrong direction. The house unit is the vertical slice: one new function or behavior, cut through every layer of the stack in a single prompt — the model (the schema or data change), the controller (the API or service logic), the view (the UI that exposes it), and the tests that pin the behavior down. One behavior, all layers, one prompt.

The alternative — horizontal chunking — feels natural and is a trap. Horizontal means slicing by layer: "generate all the models first, then all the controllers, then all the views." It matches how architecture diagrams are drawn, which is exactly why people reach for it. But compare what each strategy leaves behind after every merge:

• A vertical slice is shippable. After the slice merges, the product does one new thing, completely. Horizontal layers ship nothing until the last layer lands — three days of merged code and zero working behavior.
• A vertical slice is testable end to end. You can exercise the real path — request in, row written, UI updated — the moment it exists. A layer in isolation can only be tested against mocks of layers that do not exist yet, and mock-validated integration is where surprises hide until integration week.
• A vertical slice fits one review sitting. One behavior through four layers is typically a few hundred lines — readable, completely, with attention left over. "All the controllers" is a thousand lines of one texture, the kind of diff that trains reviewers to skim.
• A vertical slice contains its failures. If slice three is wrong, slices one and two still work and are still merged; you re-shoot one behavior. If the models layer is wrong, every controller and view built on it inherits the wound, and the fix fans out across every subsequent chunk.
• A vertical slice teaches the agent the codebase.Slice one establishes the house pattern through all four layers. Every later prompt points at it: "follow the shape of the interview-notes slice." Horizontal chunks have no complete example to point at until the very end.

The working rhythm is a loop: slice, review, merge, next slice. Prompt one slice. Review it line by line — it is sized so you actually can. Run the tests, merge it, and only then prompt the next slice, which now builds on reviewed, merged, working code instead of on hope. The codebase is never more than one slice away from its last known-good state, and your review debt is always zero when a new generation starts. This rhythm is also what feeds the Rotating Door from the parallel-agents module: a vertical slice is the perfect agent-sized task — self-contained, independently reviewable, with a crisp definition of done — so a well-sliced feature drops straight into the door as a queue of dispatchable slices, including some that can run in parallel when they touch disjoint files.

A slice prompt is tighter than a POC prompt, because the agent is now operating inside a codebase that must survive it. Four elements:

• The one behavior, stated as behavior: "a recruiter can pin a note to a candidate; pinned notes sort first and survive a stage change." One behavior per prompt — the word "and also" in a slice prompt usually marks the seam where it should have been two slices.
• The files it may touch. An explicit list. This bounds the blast radius, keeps the diff honest, and makes "why did this file change?" a review question with teeth.
• The pattern to follow — pointed at an existing slice: "mirror how interview notes does model/route/component/test." A concrete in-repo example beats any amount of style prose, and it is why the first slice of any feature deserves your most careful review: every later slice will imitate it.
• What NOT to change. Shared utilities, migrations, unrelated cleanup, drive-by refactors. Agents love to "improve" adjacent code; in a production slice, an unrequested improvement is review surface you did not budget for and risk you did not price.

When One-Shots Fail: Re-Shoot, Don't Patch

A one-shot comes back wrong. The instinctive next move is a follow-up prompt: "actually, make the scoring async" — then another — "no, the queue should live in the worker" — and twenty minutes later you are negotiating with a codebase that was misconceived at birth. This is the wrong move, and it is worth understanding why it fails rather than just that it fails.

Patching a misconceived generation compounds confusion. The agent's first output encoded a coherent-but-wrong interpretation of your ask — wrong entity model, wrong state ownership, wrong flow. Every patch prompt now fights that frame: the agent bolts your corrections onto its original architecture, and the code becomes a wrong design wearing patches of the right one. Each round adds contradiction to the context, so later patches land less predictably than earlier ones. You are not converging; you are laminating.

The correct default when a one-shot misses: fix the spec and re-shoot. Diff the output against your diagram and find the gap the agent fell into — in the common case you will find an ambiguity that permitted the wrong reading. Close that gap in the diagram and constraints, then regenerate from scratch with the improved spec. The second shot starts from a clean frame with a better target, and — unlike a patch chain — the improved spec is a durable asset that carries into every future prompt. If the miss reveals the task was bigger or subtler than you thought, the other legitimate move is to drop a tier and slice it: what you learned from the failed shot becomes the plan for the slices.

To keep yourself honest, the house applies a bright line: the two-strikes rule. Two failed one-shots on the same chunk means the problem is not luck — it is that the chunk is too big or the spec is still unclear, and a third identical attempt is a coin flip you have already lost twice. After strike two, you must change something structural: slice the chunk, or take the spec back to the diagram stage and rebuild it. Re-rolling the same prompt a third time is not iteration; it is slot-machine engineering.

What makes all of this psychologically hard is sunk cost. The failed generation is right there — 1,800 lines, 70% correct-looking, surely closer to done than an empty buffer. It is not. The 30% that is wrong is smeared through the 70% that is right, and finding the boundary means auditing all of it — the one activity agents cannot do for you and the most expensive way to spend your attention. Regenerating is cheap; untangling a half-wrong 2,000-line diff is not. The generation cost you two minutes of tokens. Treat it like a bad photograph, not a draft: you do not retouch a bad photo into a good one, you fix the framing and take another shot.

Upgrading POCs: The Trap and the Honest Path

Here is the collision between this module's two modes, and it is not hypothetical — it is a scheduled event. You one-shot a POC, exactly as the policy says. It demos beautifully, because that is what one-shots optimize for. And the room says the thing the room always says: "this looks basically done — can we ship it?"

Everything you know about the code says no. It was generated in one pass and reviewed by skim; nobody owns any line of it. It has no tests, faked auth, hardcoded seams, and error handling that consists of the happy path. The R&D module already gave this the force of law — never ship the prototype — and agent-written POCs make that law more necessary, not less, because agents produce prototypes that look far more finished than their engineering actually is. Polished surface over unreviewed core is precisely the artifact most likely to get shipped by accident.

But "never ship the prototype" does not mean the POC was waste. The honest path treats the two modes as a relay: the POC becomes the specification, and production is rebuilt as vertical slices. The POC bought you the expensive thing — certainty about WHAT to build: the demo proved the concept, exposed which features carry the value, settled UX questions that would have burned weeks of argument, and revealed the real shape of the data. That certainty now feeds the production plan: write the plan and diagram from the working POC (a far better source than imagination), decompose it into one-sentence behaviors, and run the slice-review-merge loop until the product exists — this time with every line reviewed, every slice tested, every pattern deliberate. The slices build it right; the POC is why you know what "it" is.

The critical move is to budget for this openly, at demo time — not after the ship request arrives. The sentence to say in the room, before anyone asks: "This is a one-shot prototype — it proved the concept in two days. Production is a rebuild as reviewed slices; that is N weeks, and here is the slice list." Said at the demo, that sentence is planning and makes you look like you run a process. Said three weeks later — after the POC has quietly accreted users — it sounds like an excuse, and by then the prototype has shipped itself. The rebuild cost was always real; the only choice you control is whether it is priced in up front or discovered in production.

The Policy in One Paragraph

Chunk size is a function of consequence, not model capability: generation is cheap, and your review bandwidth is the fixed budget that production code must fit inside. Disposable POC? One-shot the whole thing with the frontier model — after a plan with a Lucidchart diagram, because most one-shot failures are specification failures and the diagram is how you catch yours before the prompt. Production work? Vertical slices: one behavior through model, controller, view, and tests in one prompt — small enough to review completely, complete enough to work end to end — on a slice-review-merge rhythm that feeds the Rotating Door. When a one-shot misses, fix the spec and re-shoot or drop a tier and slice; two strikes means the chunk or the spec is wrong, and regenerating is always cheaper than untangling a half-wrong diff. And when the one-shot POC demos well and the room wants to ship it: the POC is the specification, production is a rebuild in slices, and you price that rebuild out loud at the demo — not after the prototype ships itself.

Knowledge Check

Five scenarios. For each, pick the call the house policy would make.