Agents → Task decomposition ("define down")

AI Agent Task Decomposition Explained: Define Down, Validate the Plan

What it is

"Define down" means turning a vague goal into a set of subtasks each of which is precisely specified enough that a subagent (or a function, or a person) could execute it without further clarification. The unit of decomposition is a contract, not a sentence:

Goal: "Review these 40 vendor contracts for auto-renewal risk"

Bad decomposition:  ["look at the contracts", "find risks", "write a summary"]

Good decomposition:
  subtask: review_contract
    input:   {doc_id, version, checklist_version}
    output:  {doc_id, has_auto_renewal: bool, notice_days: int|null,
              renewal_term: string|null, evidence: [{claim, chunk_ids}], status}
    success: every field either populated with a citation or explicitly null with a reason
    tools:   [search_doc(doc_id)]        budget: 25k tokens, 10 steps
    tier:    fast
  subtask: aggregate_risk
    input:   [review_contract outputs]
    output:  {ranked_risks: [...], summary: string, coverage: {reviewed, failed}}
    success: every input doc appears in either ranked_risks or coverage.failed

Three properties distinguish a good subtask contract: independently verifiable (you can check the output without redoing the work), narrow enough for a small model, and composable (the orchestrator can combine outputs mechanically).

The source file's warning is the operative point: decomposition errors are unrecoverable downstream. A subagent that perfectly executes the wrong subtask produces a confidently wrong result.

How to implement

  1. Prefer static decomposition. If the subtask structure is knowable at design time (per document, per section, per checklist item), write it in code. Reserve LLM-generated decomposition for genuinely variable goals.
  2. Define contracts as typed schemas (Pydantic/JSON Schema) with descriptions — these serve as both validation and the subagent's instructions (structured outputs & tool use).
  3. Specify success criteria explicitly, machine-checkable where possible: required fields, citation coverage, "every input accounted for".
  4. Attach resources to each subtask: tool allow-list, model tier, token/step/time budget (cost & step budgets, context isolation).
  5. Validate the decomposition itself before dispatch: does the union of subtask outputs actually answer the goal? Are there gaps or overlaps? A cheap LLM critique of the plan is far cheaper than executing a bad one.
  6. Cap the fan-out and the depth (usually 1 level; 2 rarely; 3 almost never).
  7. Make the plan visible and revisable — persist it (state & durability) so a resumed or corrected run doesn't re-plan from scratch.

Small example

from pydantic import BaseModel, Field

class SubtaskContract(BaseModel):
    name: str
    input_schema: dict
    output_schema: dict
    success_criteria: list[str]
    tools: list[str]
    model_tier: str = "fast"
    max_steps: int = 10
    max_tokens: int = 25_000

class Plan(BaseModel):
    goal: str
    subtasks: list[dict]                 # [{contract_name, input}]
    aggregation: str
    covers_goal: bool = Field(description="Set false if the subtasks do not fully address the goal")
    gaps: list[str] = []

PLAN_SYS = """Decompose the goal into subtasks using ONLY the available contracts.
Rules:
- Every subtask must use one of the listed contracts and supply valid input for it.
- The union of subtask outputs must fully answer the goal; if it cannot, set covers_goal=false and list gaps.
- Prefer the fewest subtasks that cover the goal. Maximum 50.
Available contracts: {contracts}
Output JSON matching the Plan schema."""

def plan_and_validate(goal: str, contracts: dict[str, SubtaskContract], max_fanout=50) -> Plan:
    raw = llm("plan", PLAN_SYS.format(contracts=json.dumps({k: v.model_dump(exclude={"tools"}) for k, v in contracts.items()})),
              [{"role": "user", "content": goal}], max_tokens=1500)
    plan = Plan.model_validate_json(raw.text)

    # structural validation — cheap, catches most bad plans
    assert len(plan.subtasks) <= max_fanout, "fan-out too large"
    for st in plan.subtasks:
        c = contracts[st["contract_name"]]                                  # KeyError = invented contract
        jsonschema.validate(st["input"], c.input_schema)                    # invalid input = bad plan
    if not plan.covers_goal:
        raise PlanIncomplete(plan.gaps)

    # semantic validation — a second opinion before spending money on execution
    critique = json.loads(llm("plan_critique", CRITIQUE_SYS, [{"role": "user", "content":
                f"<goal>{goal}</goal><plan>{plan.model_dump_json()}</plan>"}]).text)
    if not critique["sufficient"]:
        log_plan_rejected(goal, critique["reason"])
        raise PlanInsufficient(critique["reason"])
    persist_plan(plan)                                                       # resumable (state & durability)
    return plan

# Static decomposition — preferred whenever the structure is knowable
def plan_contract_review(doc_ids, checklist_version) -> Plan:
    return Plan(goal="review contracts for auto-renewal risk",
                subtasks=[{"contract_name": "review_contract",
                           "input": {"doc_id": d, "version": current_version(d), "checklist_version": checklist_version}}
                          for d in doc_ids],
                aggregation="aggregate_risk", covers_goal=True)

Pros

  • Contracts make subagents reliable: narrow scope, typed output, checkable success — a fast model can do the work.
  • Parallelism becomes trivial when subtasks are independent (fan-out / fan-in).
  • Failures are localised and attributable to a named subtask.
  • Cost is predictable: budget per subtask × count, known before execution.
  • The plan is a reviewable artifact — a human can approve it before anything expensive happens (human-in-the-loop).

Cons

  • LLM-generated plans are the weakest link: plausible-looking decompositions that miss a requirement or double-count.
  • Upfront design cost — writing contracts is real work.
  • Rigid contracts can't adapt when execution reveals the plan was wrong (needs replanning, loop-back / reflection).
  • Over-decomposition adds coordination overhead for tasks a single call handles.
  • Aggregation logic is often harder than the subtasks.

When to use

  • Fan-out work over a known collection (documents, sections, records, checklist items) — the highest-value case.
  • Multi-stage workflows with distinct phases.
  • Any task where you want to run cheap models on narrow pieces instead of an expensive model on everything.

When NOT to use

  • Simple tasks a single call handles well — decomposition is overhead.
  • Genuinely exploratory work where subtasks can't be known until execution starts (use bounded recursion, recursive / agentic retrieval, or an agentic loop, agentic RAG).
  • When you can't define success criteria for the subtasks — that's a sign the goal itself is underspecified.

Production at scale

Static beats dynamic, overwhelmingly. In production, most decompositions are structural: per document, per section, per row, per checklist item. Write those in code with typed contracts. Reserve LLM planning for the minority of goals whose shape genuinely varies — and even then, constrain it to selecting from a fixed contract catalogue rather than inventing subtasks.

Validate plans before executing them. Structural validation (contracts exist, inputs match schemas, fan-out within limits) is free and catches most bad plans. A cheap LLM critique catches more. Both are far cheaper than executing 40 subtasks based on a flawed plan.

Coverage is a first-class output. The aggregation step must account for every input: reviewed, failed, or skipped, with reasons. A summary of 37 of 40 contracts that doesn't mention the missing 3 is a dangerous artifact.

Contract catalogue as a versioned asset (prompt versioning & evaluation): contracts have versions, evals, and owners. Changing an output schema is a breaking change for the aggregator.

Budget the whole plan. subtasks × per-subtask budget must fit an overall run budget, checked before dispatch. A plan that would cost $40 should be rejected or escalated for approval (human-in-the-loop, cost & step budgets), not discovered mid-execution.

Persist the plan so a crashed run resumes from completed subtasks rather than re-planning and re-executing (state & durability). Plan + per-subtask status is the checkpoint.

Human approval for expensive or irreversible plans: show the plan, the fan-out, and the estimated cost before executing. This is where an approval gate is cheapest and most useful.

Evaluate decomposition separately from execution (component vs end-to-end): given a goal, does the planner produce a plan a human would accept? Low end-to-end quality with high subtask quality means the decomposition is at fault.

Prod checklist

  • Static decomposition in code wherever the structure is knowable
  • Typed contracts: input schema, output schema, success criteria, tools, tier, budget
  • LLM planning constrained to a fixed contract catalogue; no invented subtasks
  • Structural + semantic plan validation before dispatch
  • Whole-plan cost estimated and budget-checked before execution; approval gate above a threshold
  • Fan-out and depth caps
  • Aggregation accounts for every input (reviewed / failed / skipped with reasons)
  • Plan persisted for resumability; contracts versioned with evals
  • Decomposition quality evaluated independently of execution

Metrics to watch

MetricWhy
Plan rejection rate (structural / semantic)Planner quality
Coverage: inputs accounted for in aggregationSilent omissions
Subtask success rate by contractWhere execution fails
Estimated vs actual plan costBudget accuracy
End-to-end quality vs subtask qualityAttribution to decomposition