Sizing a Task so an Agent Finishes It in One Pass

Treat these as a default budget, not a law. They are calibrated so a single pass can plausibly succeed without context management tricks, and they map onto the intuition behind small vertical slices in ordinary software delivery: a slice is valuable when it is small enough to finish and verify, and slicing horizontally by technical layer tends to produce work that is not independently testable (Humanizing Work on story splitting, vertical versus horizontal slices).

The test row is deliberately strict. An agent without a check it can run inside the same pass has no reliable way to know it is done, and "done" becomes whatever the model said last. Planning guides consistently recommend that completion be verified against observable criteria rather than inferred from the agent declaring success (AI agent planning guide). One command that returns pass or fail is the cheapest version of that.

A worked example. Suppose the ticket reads: "Add rate limiting to the public API and make sure the docs cover it." Count it: the middleware file, the config file, two handler files, and the docs page, so 5 files, right at the ceiling. Branches: limit per key or per IP, and return 429 with or without a Retry-After header, so 2, fine. Tools: the test runner plus the schema generator, so 2, fine. Test: one command, npm test -- ratelimit, fine. Verdict: fits one pass, but only just, and you should name the two branch choices in the prompt so the agent does not invent a third.

Now a task that looks similar but is not: "Add rate limiting to the public API, the webhooks, and the admin endpoints, and update the SDK." That is roughly 14 files, five or six branch decisions, and three test suites. Split it into one pass for the public API, one for webhooks plus SDK, and one for admin. Each gets its own check.

Files are visible on a ticket. Decisions are not, which is why they are the count people skip and then regret. A branch decision is any point where the agent must pick an option and later work depends on that pick. Migration with or without a backfill. Synchronous call or queued job. New table or extend the existing one.

Each decision splits the remaining plan, so three decisions implies up to eight distinct paths the agent must keep straight. That is the practical reason three is a good ceiling: the agent can hold the thread, and you can review the choice in the diff.

Two defenses work well. First, decide the branches yourself and state them in the prompt as constraints, which converts decisions into instructions and drops the count to zero. Second, if a decision genuinely must be made during the work, require the agent to write the choice and a one-line rationale into a file before proceeding, so it becomes an artifact you review rather than a silent inference. Spec-first workflows make the same move at a larger scale, resolving ambiguity and edge cases in the written spec before implementation starts, because prompt-only context leaves no durable source of truth and produces architectural drift (Microsoft on spec-driven development).

There is a useful check here before you split anything. If you cannot write the branch decisions down, you do not yet know what the task is, and no amount of agent capability will fix that. The first pass in that case is not code at all: it is a file listing the decisions with your choice for each, which is a zero-file, zero-tool, one-check task.

An agent that cannot close the loop in one pass is not really doing a one-pass task, whatever the prompt says. The rule: identify the single command whose result tells you the change worked, confirm it runs quickly on your machine, and put the exact command in the prompt.

If no such command exists, the first pass is to create one, and it should not also include the feature. Building the check is itself a task with one file, zero branch decisions, one tool call, and one verification: the test fails for the right reason before the code exists. That failure-first run is the cheapest evidence you will get that the test tests anything.

Long suites are their own trap. If the full suite takes twenty minutes, the agent's loop is not the suite, it is the subset. Pick the narrowest command that covers the change and say which files it must not touch, because a narrow test only stays narrow if the agent leaves adjacent code alone.

Before you count anything, a few signals predict an over-budget task on sight. Use them as fast triage, then count to confirm.

• The goal sentence contains "and" more than twice. Usually two or three tasks glued together.
• You cannot name the command that proves it worked. The verification does not exist yet.
• The work needs a decision you have not made. Branch count is unestimated, not zero.
• The description references more than one service, repo, or deploy target. Files and tool calls both climb.
• You would want to review it in stages rather than as one diff. Your review instinct is a good proxy for the agent's attention budget.

The last one is the most reliable. If you would ask a colleague to do it, show you the plan, and then continue, the task has a natural seam, and the agent should be held to the same seam.

Splitting without a handoff just moves the failure. The split works when pass two starts from a file, not from a conversation. A useful handoff is short and concrete. It names what was done, what was decided and why, what was deliberately left out, and what the next pass must not break. Four headings are enough, and the constraints section is the one that keeps the next pass inside its budget.

The gain is measurable in the second pass. Files touched drops because the agent reads the handoff instead of exploring. Branch decisions drop because they are already recorded. The test loop stays at one because the earlier check still exists. Context folding research describes the same pattern from the model side: an agent branches into a subtask, folds it on completion, and keeps a concise summary rather than the intermediate steps, matching baseline performance with an active context up to ten times smaller (ICML poster on context folding). Your handoff file is that fold, written by hand and therefore reviewable.

A related result explains why the handoff should be written by the agent that did the work rather than reconstructed later. Context management strategies show a fidelity and reliability trade-off: stronger agents benefit from preserving more of the original context, while weaker agents need more aggressive compression to stay reliable (arXiv on agent-compatible context management). If you are running a cheaper model on pass two, give it the compressed handoff, not the transcript.

Apply this at intake. It takes about three minutes for a normal ticket.

1. Write the goal in one sentence with no "and".
2. List the files the agent must edit. If you cannot list them, the first pass is read-only investigation: zero edits, one output file, one check that the file answers three named questions.
3. List the branch decisions. Either make them yourself and put them in the prompt, or accept the count.
4. List the tools and APIs. Anything with credentials or a network side effect counts double, because a failure there forces a retry decision the agent must make alone.
5. Name the exact check command and confirm it runs today.
6. If any count is over budget, write the split and the handoff headings before writing the prompt.

Then check the whole thing against how the agent will actually run it. Coding agents are wrappers around a model plus tools, memory, and environment feedback, and the harness matters as much as the model (Sebastian Raschka on coding agent components). If your harness truncates tool output or summarizes history at a fixed turn count, your effective file budget is lower than five, because the agent will re-read files it already saw and spend its attention on the repeat instead of the change.

One more calibration point for teams. Agents begin to degrade once a task grows past roughly thirty-five minutes of human-equivalent work, and doubling that duration roughly quadruples the failure rate rather than doubling it, which is why the counts above stay deliberately small (long-horizon planning survey). If your ticket would take a competent engineer half a day, the budget is not the constraint, the scope is, and the split is mandatory rather than advisory.

For teams that want this discipline applied across a line of work rather than one ticket, Quanta Experts take a scoped brief, read your context, and return finished deliverables, which pairs naturally with the handoff format above (https://quantaintelligence.ai/agents).