Planning, Decomposition & Task Graphs

“Migrate the reporting pipeline off the deprecated warehouse connector before the end of the quarter.” This goal has an unknown number of steps, unknown dependencies, at least three human decisions, and no explicit completion criterion.

Asking the model for a numbered list and executing it blindly fails when later observations invalidate earlier assumptions.

6.1Why planning is not a prompt#

Ask a capable model to plan the migration above and you will get a plausible seven-step list. Execute it blindly and you will discover, at step four, that the connector has a second caller nobody mentioned; that step two’s output does not have the shape step five assumed; and that step six requires a permission the agent does not hold. The plan was not wrong when it was written. It was written before any of the information that determines the plan had been gathered.

This is the structural argument against plan-then-execute, and it has been the empirical finding too. The research literature on LLM planning has been consistently sobering: on classical planning benchmarks, models produce plans that read well and validate poorly, and — importantly — asking a model to critique and repair its own plan does not reliably fix it.¹² The broader result generalises beyond planning: models are unreliable at self-correcting reasoning errors without external feedback, and self-correction loops that lack a ground-truth signal can make outputs worse rather than better.³

The conclusion is not “do not plan.” It is that a plan’s value is as a structure for gathering information, not as a script for executing it. Which reframes the design question from “how do I get a good plan” to “how do I keep a plan honest as evidence arrives.”

6.2Four planning postures#

Four planning architectures offer different tradeoffs:

Implicit planning keeps no plan artefact; the model reasons about what to do next inside its own turn. This is the correct posture for short tasks, and it is what the bare loop in Chapter 4 does. It avoids explicit plan-maintenance cost, while still consuming reasoning and execution resources. An event log can provide progress, interruption and resumption without a separate plan artifact.

Plan-then-act produces a full plan and executes it. Its narrow legitimate use is a procedure that is genuinely known in advance and must be auditable before execution — a compliance-controlled deployment, a documented remediation runbook. If you can write the plan as code, write it as code (Chapter 7). If the plan genuinely depends on what you find, this posture is wrong.

Interleaved with an explicit plan artefact is the default and the recommendation. The agent maintains a plan in state, works the next open item, and revises the plan when observations contradict it. The critical word is artefact: the plan lives in the harness’s state, not only in the model’s context, which is what makes it inspectable, resumable, and interruptible.

Hierarchical decomposition breaks the goal into subtasks and delegates each to a sub-agent with its own context. It buys context isolation, which is genuinely valuable (Chapter 9), and costs coordination overhead and token multiplication (Chapter 28). The precondition people skip: subtask results must be cheaply verifiable by the parent, or delegation just moves the uncertainty somewhere you can no longer see it.

6.3What current long-running harnesses add#

Anthropic’s November 2025 report uses an initializer, explicit feature requirements, incremental implementation and progress artifacts between sessions. Its March 2026 follow-up separates planner, generator and evaluator, with a testable agreement for each work increment. These are workload-specific engineering reports, not proof that three agents are always better. Their useful common principle is to carry requirements and evidence across sessions and verify behavior in the running application. 2025 harness report, March 2026 follow-up, checked 8 September 2026.

A durable plan must also accept authorized user changes without losing history. Keep the original request and each subsequent amendment as versioned inputs; the agent may refine implementation steps but must not silently narrow acceptance criteria. On resumption, recheck the current artifact or external job before trusting a progress note.

6.4The plan as a first-class artefact#

Store the plan as structured state rather than only prose in the context window.

class StepState(str, Enum):
    PENDING   = "pending"
    ACTIVE    = "active"
    BLOCKED   = "blocked"      # waiting on a human, or on another step
    DONE      = "done"
    ABANDONED = "abandoned"    # deliberately dropped; keeps the reason


@dataclass
class Step:
    id: str
    description: str
    state: StepState = StepState.PENDING
    depends_on: tuple[str, ...] = ()
    # How we will know this step actually worked. A step without one is a
    # step whose completion is the model's opinion.
    verification: str = ""
    evidence: str = ""             # filled in when verification passes
    note: str = ""                 # why blocked, why abandoned


@dataclass
class Plan:
    goal: str
    steps: list[Step] = field(default_factory=list)
    revisions: int = 0

    def ready(self) -> list[Step]:
        """Steps whose dependencies are all satisfied — the frontier."""
        done = {s.id for s in self.steps if s.state is StepState.DONE}
        return [s for s in self.steps
                if s.state is StepState.PENDING
                and all(d in done for d in s.depends_on)]

This is a design sketch; the reference harness does not implement this graph scheduler. Before accepting a plan, validate unique step IDs, existing dependencies, acyclicity and legal state transitions. A missing dependency or a cycle otherwise looks like an empty frontier forever.

BLOCKED is a distinct state from PENDING. A step waiting on a human approval is not merely un-started; it is un-startable, and the difference determines whether the agent should keep working other branches or stop. Collapsing them produces agents that either spin uselessly or halt when they could have made progress elsewhere.

ABANDONED keeps its reason. Steps get dropped legitimately — the migration turns out not to need a backfill. Deleting them loses the fact that the question was considered and answered, which is exactly what a reviewer will ask about.

verification is a required field in spirit if not in the type. A step that says “update the connector config” with no verification criterion completes when the model decides it has completed. A step that says “…verified by: pytest tests/reporting/ -k connector exits zero” completes when the world agrees. The second is worth roughly ten of the first, and Chapter 24’s trajectory evaluations depend on it existing.

Dependencies make it a graph, not a list. A list forces a total order that the work does not have, which serialises steps that could run concurrently and — worse — hides the real constraint structure. ready() returning a frontier rather than a next-step is what makes parallel execution and sensible replanning possible.

Why the artefact pays for itself#

Re-serialising a dozen-step plan costs a few hundred tokens per turn, which accumulates over long runs. Structured plans provide:

A progress signal. “Step 4 of 9, verifying” is information a user can act on. A spinner is not. This alone justifies the cost for any run longer than a minute (Chapter 4).

An interruption point. A human who can see the plan can redirect before the wrong step runs. Chapter 19 makes this the foundation of approval design: the cheapest approval is the one on a plan, not on twelve individual actions.

A resumption anchor. After a crash, “which steps are DONE with evidence” is a far better starting point than replaying two hundred turns of transcript and hoping the model re-derives its position.

A grip on drift. The most insidious long-run failure is not error but drift: the agent ends up doing something adjacent to what was asked. An explicit goal and an explicit step list, re-read every turn, is the cheapest available anchor against it.

6.5Decomposition that survives contact#

Four rules govern decomposition:

Each step must be independently verifiable. This is the dominant rule. “Refactor the connector layer” is not a step; “extract the retry logic into retry.py and confirm the existing tests still pass” is. The test is whether you can state, before starting, what observation would prove the step done.

Steps should be sized to a handful of turns. A step that takes fifty turns is a task in disguise and should be decomposed further. A one-turn step can still be valuable when it is a critical check. A handful of turns is a starting heuristic, not a universal productive band, and the reason is failure isolation: when a step fails, you want to retry the step, not the plan.

Dependencies must be real. Agents over-serialise, declaring dependencies that do not exist because sequential prose reads naturally. Every false dependency is lost parallelism and an unnecessary blocking point. The question to ask of each edge: does step B genuinely require an output of step A, or does it merely come after it in the narrative?

Information-gathering steps come first and are cheap. The first two or three steps of almost any good plan are reads: find the callers, check the schema, read the runbook. They are cheap, they are safe, and they are what makes steps four onward correct. An agent that starts by mutating something has skipped the part where it learned what to mutate.

6.6A worked migration graph#

The difference between a list and a graph becomes concrete when you price the trajectory. Take the reporting migration and give each step an illustrative duration in execution slots — one slot is the time Reference Agent needs to complete a bounded unit of work and record its evidence. The number is not a promise about elapsed minutes. It is a common unit that lets you compare two schedules without pretending you know how fast a model call, test suite and approval will be in production.

The initial evidence-grounded plan has nine steps:

A list spends 30 slots because it imposes a total order. The arithmetic is direct:

2 + 2 + 1 + 6 + 8 + 5 + 1 + 2 + 3 = 30.

That schedule makes the runbook wait for the caller search, even though neither produces an input for the other. It then makes the ETL patch wait for the reporting patch, and the dashboard patch wait for both. The prose order has become a resource constraint by accident.

The graph exposes a critical path of 18 slots. F and R can start together, so the first stage costs max(2, 1) = 2. S then costs 2. The three patches can start after F, S and R are complete, so their stage costs max(6, 8, 5) = 8. Approval, deployment and verification remain serial and cost 1 + 2 + 3 = 6. The critical path is therefore:

max(F, R) + S + max(P, E, D) + A + Y + V

= 2 + 2 + 8 + 1 + 2 + 3 = 18.

That does not mean the graph makes the work 40% cheaper. The same 30 units of domain work still happen. It means an executor with capacity for three independent branches can shorten the ideal wall-clock schedule from 30 slots to 18 — a reduction of (30 - 18) ÷ 30 = 40% — before coordination overhead.

Coordination is real work, so put it into the comparison. Suppose Reference Agent spends one additional slot materialising the graph, one dispatching branch inputs, one reconciling branch results and one checking that the merged evidence satisfies the deployment gate. The graph now consumes 34 active slots of work and 22 wall-clock slots: 30 + 4 = 34 units of work, and 18 + 4 = 22 along the schedule. Relative to the serial list, active work rises by 4 ÷ 30 = 13.3%, while wall-clock time falls by 8 ÷ 30 = 26.7%. The adjusted speed-up is 30 ÷ 22 = 1.36×.

This is the economic test for decomposition. Parallelism is valuable only when the critical-path reduction exceeds the coordination tax. If dispatch, context packing, result review and conflict resolution cost twelve slots instead of four, the adjusted graph takes 18 + 12 = 30 slots and produces no wall-clock gain. If the three patch branches touch the same configuration file and repeatedly conflict, their independence was fictional; model them as one step or introduce a real merge boundary.

You can calculate the useful concurrency before you spawn anything. At the patch frontier, total branch work is 6 + 8 + 5 = 19 slots and the longest branch is 8. With unlimited capacity, that frontier cannot finish in fewer than 8 slots. Its maximum useful average concurrency is therefore 19 ÷ 8 = 2.375. Giving the executor ten workers cannot improve the frontier beyond the three available branches, and even three workers sit partly idle because the branch lengths differ. The graph tells the scheduler both what may run and when more capacity has stopped helping.

There is a second bound: the critical path itself. The ETL branch contributes 8 of the graph’s 18 slots, so optimising the five-slot dashboard branch by 40% saves two slots only if it still finishes after the ETL branch. It does not — 3 is still below 8 — so the overall schedule does not move. Cutting the ETL branch from 8 to 6 reduces the graph to 16 slots because that branch is on the critical path. Optimising work off the critical path may reduce spend or free capacity, but it does not reduce completion time.

Measure step durations from traces (Chapter 23). Replace coarse estimates with medians and high percentiles by step class, then compare the predicted critical path with the observed one.

Do not confuse runnable with safe to run concurrently. ready() proves only that declared dependencies are satisfied. It says nothing about two steps writing the same file, consuming the same quota, locking the same tenant record or requiring the same human. Add resource keys alongside dependency edges — for example repo:reporting, warehouse:staging and approver:data-platform — and let the scheduler admit only a conflict-free subset of the frontier. The task graph answers logical precedence; the scheduler still owns operational exclusion.

The worked plan therefore produces three numbers, not one: 34 active work slots, 22 adjusted wall-clock slots and an 18-slot ideal critical path. Cost, latency and theoretical headroom are different quantities. Reporting only the 18 makes the architecture look better than it is. Reporting only the 34 makes useful parallelism look wasteful. Keep all three.

If a tenant lock permits only one mutating branch at a time, the graph still earns a place but the speed-up disappears. P, E and D remain logically independent while the scheduler serialises their 19 slots on the shared resource key. The ideal schedule becomes 2 + 2 + 19 + 1 + 2 + 3 = 29 slots; four coordination slots make it 33, slower than the 30-slot list. The graph still preserves verification, resumption and honest dependencies; it simply does not justify delegation. This counterexample separates two claims people routinely merge: task graphs improve control structure, while parallel execution improves latency only when the environment supplies real concurrency.

6.7Replanning: the part that decides whether it works#

When should the plan be revised? Four triggers are worth encoding explicitly, because “the model will notice” is not a mechanism:

How much should be revised? Prefer the smallest coherent revision. A model asked “the plan is failing, write a new plan” will write a different plan, discarding correct work and re-deriving conclusions it already had. A model asked “step 4 failed with this error; propose a minimal amendment to steps 4 through 7” produces something reviewable. The narrower prompt is not just cheaper; it is more accurate.

How often is too often? Replanning has a pathology: a plan revised every turn is not a plan, and an agent that thrashes its plan is one that will consume its budget on planning. Count revisions in state, and treat a high revision rate as a signal to stop rather than a state to continue in. Repeated full replans without new evidence are a stall signal. Three is an illustrative alert threshold, not proof of infeasibility. Continue useful independent work, distinguish a live external wait from a blocker, and escalate only when evidence shows that the current path cannot proceed.

6.8The migration that became less complete#

In this illustrative scenario, at 16:20 Reference Agent reports that the migration is 83% complete. Five of six original steps are DONE: inventory the callers, patch two services, run the shared tests and deploy. Only production verification remains. The progress display is arithmetically correct — 5 ÷ 6 = 83.3% — and operationally misleading.

Production verification queries the deprecated connector and finds a read every hour. The first assumption is propagation delay: the deployment must not have reached every worker. Reference Agent checks the rollout, sees the new version on every service instance, waits for another read, and sees it again. The scheduler’s request carries a client identifier that does not belong to either patched service.

The actual mechanism is an omitted node, not a failed node. A monthly export job lives in scheduler configuration outside the two application directories searched by the inventory step. Its next-run timestamp was changed to hourly for a quarter-end rehearsal, so a supposedly dormant caller is now active. The initial inventory verification — “repository search returns two callers” — proved only what the repository contained. It did not prove the statement the plan depended on: “these are all production callers.”

This distinction changes the repair. Retrying the deploy cannot help because the deployed artefacts were correct. Re-running the same repository search cannot help because its search space excludes the scheduler. Rewriting the whole plan would discard five pieces of valid evidence. The smallest coherent amendment adds three nodes: inventory external scheduler definitions, patch the export job, and redeploy the expanded patch set. The existing connector-zero verification node reopens as PENDING after the new deployment. The original inventory step remains DONE with its narrow evidence; the new inventory node records that the evidence was insufficient for the broader claim. History stays honest.

The denominator now changes from six steps to nine. Five completed steps out of nine is 55.6%, so the visible progress falls from 83.3% to 55.6% even though no completed work vanished. A user may read that fall as regression. It is actually the plan becoming more truthful. A progress interface that forbids backwards movement pressures the planner to hide discovered work, bundle it into an existing step, or mark the goal complete early. All three choices protect the percentage at the expense of the result.

Progress is not DONE ÷ total unless the denominator is stable. For an evidence-driven plan it rarely is. Show the revision explicitly: “5 of 6 original steps complete; 3 steps added after production evidence; 5 of 9 current steps complete.” Better still, separate accomplished work from remaining forecast. The event log can state that five steps reached verified completion. The current graph can state that four remain. Neither number needs to erase the other.

The fix has two layers. First, strengthen the local inventory criterion: search source repositories, deployment manifests, scheduler definitions and the connector’s own recent client identifiers. Second, add a plan-level invariant that no individual patch can satisfy: production reads through the deprecated connector must remain zero for the defined observation window. Step checks prove that local work happened. Goal checks prove that the composition produced the requested outcome. Chapter 24’s distinction between trajectory and outcome evaluation is the same distinction at evaluation scale.

The incident also exposes why a completion percentage should not drive scheduling. An 83%-complete plan with one high-uncertainty verification step may be farther from completion than a 40%-complete plan whose remaining critical path is measured and unblocked. Schedule from the frontier, resource constraints and predicted critical path. Display percentages only as a summary of recorded state, with revision context attached.

The general lesson is precise: a plan fails when one of its dependencies is false, even if every listed step succeeds. Verification must test both the node and the edge. Did the patch pass its tests? Did the evidence produced by inventory actually justify treating the patch set as complete? Node-level evidence without edge-level assumptions gives you a graph that is internally tidy and externally wrong.

When you revise, preserve four facts in the event stream: the observation that contradicted the plan, the assumption it invalidated, the nodes added or superseded, and the effect on the predicted critical path. That record lets an evaluator distinguish discovery from thrashing. “Plan revised” is not enough; the same event label can describe disciplined evidence uptake or a model changing its mind for no reason.

6.9Measure planning as a control system#

A planner is not successful because it emits plausible steps. It is successful when those steps keep execution pointed at the original goal while the world supplies contradictory evidence. Measure that control loop at three seams: whether steps are verifiable, whether the graph predicts execution, and whether revisions improve the plan rather than merely changing it.

Start with a small instrumentation contract. Every plan revision needs an immutable plan version, a reason code, the triggering observation and a diff of nodes and edges. Every step transition needs the step id, previous and next state, evidence reference and verification result. Every scheduling decision needs the ready frontier, the admitted subset, resource exclusions and the predicted remaining critical path. Without those records, you can count model calls but cannot tell whether planning helped.

Some rows are invariants; others are diagnostics. Evidence coverage and goal-drift rate have clear targets of 100% and 0% because they describe properties the harness controls. Structural repair rate has no universal target. A planner that repairs 40% of research plans may be learning exactly as intended, while one that repairs 40% of a fixed payroll runbook is failing to encode a stable procedure. Segment before you judge.

Work through an illustrative weekly slice. Reference Agent completes 20 planned migrations. Across them, 184 steps transition to DONE; 181 transitions carry durable evidence. Evidence coverage is 181 ÷ 184 = 98.4%. That sounds high and fails the invariant: three completions cannot be audited or safely resumed. Seven runs amend at least one node or edge, so structural repair rate is 7 ÷ 20 = 35%. Eleven completed nodes are later superseded because their evidence was too narrow, giving an invalidation ratio of 11 ÷ 184 = 6.0%.

The same runs consume 410 model turns, of which 62 draft, inspect or revise plans. Planning tax is 62 ÷ 410 = 15.1%. Their predicted critical paths sum to 520 minutes at approval; observed completion spans sum to 690 minutes. Critical-path stretch is 690 ÷ 520 = 1.33. Finally, the scheduler records 160 minutes during which at least one node was ready, and 48 of those minutes had no active work. Ready-but-idle rate is 48 ÷ 160 = 30%.

These numbers tell a coherent story. Three missing evidence references are a correctness defect and should be fixed first. The 6.0% invalidation ratio points to criteria that are locally passing but too narrow, as in the scheduler omission. A 1.33 path stretch alongside 30% ready-but-idle time suggests the delay is not only poor duration estimates; the scheduler is also leaving runnable work untouched. The 15.1% planning tax becomes worth investigating only after you compare outcome success and wall-clock reduction with a simpler posture. Cost without benefit is waste; cost that buys safer, shorter runs is the product doing work.

Do not optimise the repair rate downward. If you reward fewer revisions, the easiest strategy is to ignore contradictory evidence. Pair structural repair with trigger quality: sample revisions and classify whether each cites a concrete observation, changes the smallest coherent subgraph and preserves completed evidence. A high repair rate with strong triggers describes an uncertain environment. A high rate without triggers describes thrashing. A low rate with frequent verification failures describes denial.

Measure predictions at the time they could influence a decision. Recomputing the critical path after completion and comparing it with the same observed durations produces perfect estimates and no learning. Store the prediction when the plan is approved, then store a new prediction at each revision. You can now ask whether amendments reduce forecast error, whether particular step classes are systematically underestimated, and whether approval or resource waits dominate the stretch.

Treat plan quality as a trajectory property, not a single score. Two plans can reach the same result with different risk: one discovers the hidden caller before mutation, the other discovers it in production; one records the reason for an abandoned backfill, the other deletes the step; one escalates an empty frontier, the other loops. Outcome success cannot distinguish them. The plan events can.

The operational response should follow the symptom rather than a blended “planner quality” number:

Planning measurement earns its keep when it changes a control. Reject evidence-free completion. Recalibrate duration estimates. Widen a discovery search. Reduce false resource conflicts. Escalate an infeasible frontier. A dashboard that cannot point to one of those actions is recording the planner’s activity, not measuring its quality.

6.10Todo state in shipped systems#

Documented products expose explicit task state in different forms. Hermes intercepts todo as harness state before general tool dispatch.⁴ Cline provides /deep-planning and separate Plan and Act modes.⁶ Its subagent guide also describes Plan-mode shell commands that can write files.⁷

Devin’s older Playbooks separate Procedure, Specifications, Advice and Forbidden Actions.⁹ Its guide directs new work to Skills. New accounts start with Skills and no Playbooks from 24 October 2026.

That last detail deserves a moment. A plan template with an explicit Forbidden Actions section encodes something the research on self-critique supports: explicit prohibited actions can complement positive acceptance criteria. Neither is automatically reliable: enforce authorization in the harness and validate that revisions preserve both. If your plan format has no place for them, add one.

6.11Delegation, and when to reach for it#

A planning structure warrants delegation only when subtasks can run independently under explicit contracts (Chapter 28).

Delegate when all four hold:

1. The subtask is genuinely independent. It does not need the parent’s working context to make its decisions.
2. Its result is compact. A sub-agent that returns forty thousand tokens has moved the context problem, not solved it.
3. The parent can verify the result cheaply. Without this you have added an unverifiable dependency and lost visibility into it.
4. The subtask would otherwise pollute the parent’s context. This is the actual benefit: exploratory search that reads two hundred files and needs to report three, where the parent should see the three.

Delegation limits differ by product. Hermes children start with fresh conversations and default to leaf mode. Its documented defaults cap child iterations at 50 and prevent nested delegation unless spawn depth is raised.⁵ Cline’s CLI and Desktop children inherit mode-specific tools, lack MCP tools and can start children. Act children can edit and run commands.⁷ Goose subrecipes use separate sessions without shared conversation history, memory or state, and prohibit nesting.⁸

The products differ in tool access and recursion. Their shared benefit is a separate context. Set explicit tool permissions, depth limits and a shared budget before enabling nested delegation.