agent_task_decomposition v1.0.0

name: agent_task_decomposition description: Break a complex job into tool-sized subtasks — scope, sequence, and verify each one, and decide whether to do it inline, delegate to a subagent, or wire a fixed workflow. Triggers whenever a task needs more than a few tool calls, the plan is unclear, or a big job should be split across agents.

Agent Task Decomposition

Purpose

Turn "do this big thing" into a set of tool-sized subtasks: each one scoped to a single action, ordered by dependency, assigned an execution mode (inline, subagent, or fixed workflow step), and paired with a concrete way to verify it worked. The point is not more process — it is fewer dead ends: Anthropic's standing guidance is to use the simplest approach that works and add complexity only when it demonstrably improves outcomes.

Workflow

1. Size the job before touching it

Read the task and pick the smallest execution mode that fits:

| Mode | Use when | Shape | |---|---|---| | Inline | A handful of tool calls, all in one context, sequential | Just do it yourself, step by step | | Fixed workflow | Steps are knowable up front and repeatable | Code or written procedure: chaining, routing, parallel batches | | Orchestrator-workers | Subtasks can't be predicted until you start (e.g. coding across unknown files, research across unknown sources) | You decompose dynamically, dispatch subagents, synthesize | | Autonomous loop | Open-ended; can't even name the steps; needs ground-truth feedback each turn | One agent looping on tools until done, with a stop condition |

Rule of thumb: most tasks need one agent, often zero. Multi-agent delegation costs roughly 3–10× the tokens of an equivalent single-agent approach (duplicated context, coordination messages, handoff summaries — Anthropic's own measurement). Pay that only when a specific constraint demands it.

2. Scope each subtask to tool-size

A subtask is tool-sized when it passes all three tests:

1. One verb, one target. "Search the Playbook API docs for the ratings endpoint" — not "research the API."
2. A small, bounded tool budget. You can name the 1–5 tool calls it will take. If you can't, the subtask is still two subtasks.
3. A checkable outcome. You can say exactly what you'll look at to know it worked (a file exists, a value matches, a test passes).

Split by context boundary, not by phase. "Research → Write → Edit" is a phase split — each handoff loses context. "Auth module (design + tests + edges)" vs "API layer (contracts + validation)" is a domain split — each chunk is self-contained in one head. Phase splits create handoff failures; domain splits survive them.

3. Sequence by dependency, not by habit

Map the subtasks onto a dependency order:

• Independent → parallel. Research topics, separate modules, parallel tool calls in one block.
• Dependent → sequential. Design before implementation, facts before synthesis, write before verify.
• Unknown → dynamic. When the shape of later work depends on what you find, don't pre-write a pipeline — plan the first wave, execute, then re-plan from results. This is the orchestrator-workers pattern: decompose, dispatch, synthesize, decide whether to dispatch more.

Cheap trick: write the plan down (a scratch file, a checklist) before executing. Externalizing the plan protects you when context grows — re-read it instead of re-deriving it.

4. Decide inline vs. subagent per subtask

Delegate to a subagent only when one of these three holds:

1. Context pollution. The subtask will generate high context volume (hundreds to thousands of tokens — Anthropic cites >1000 as the effective threshold) that is mostly irrelevant to the rest of the job. A subagent's fresh context absorbs the noise and returns only the distilled answer. Classic case: read a long document, extract one fact.
2. Real parallelism. Subtasks are genuinely independent and running them concurrently covers more ground (research facets, parallel investigations). The payoff is thoroughness, not speed — total token cost goes up.
3. Specialization. The subtask needs a different toolset, persona, or domain focus than the main job — e.g. an agent with 20+ tools where the subtask needs a tight few, or conflicting behavioral modes (empathetic support vs. critical code review) in one head.

If none of the three holds, do it inline. Especially do not delegate when subtasks share the same context, are tightly interdependent, or each need the full picture — coordination costs will exceed any benefit.

How to brief a subagent (this is the part most people skip): give it a self-contained brief — objective, expected output format, which tools to use, explicit boundaries (what NOT to touch), and its done criteria. Vague delegation produces vague work. Ask for a summary back, not a full trace: the distilled findings plus file paths or references, not a play-by-play.

5. Build verification into the plan, not after it

Every subtask gets a done criterion defined before execution — not "looks good," but:

• File check: the artifact exists at the expected path with expected structure.
• Ground-truth check: the claim matches a source, the number matches a readout, the test passes.
• Round-trip check: call the thing you built (API, script, page) and confirm the output.

For work that improves with iteration, use the evaluator-optimizer loop: one pass generates, a separate pass (yours, or a critic prompt) evaluates against explicit criteria, and you iterate. Two signs it fits: human feedback demonstrably improves the output, and the evaluator can articulate useful feedback. Otherwise, one careful pass beats three sloppy ones.

Stop conditions. Any loop gets one: max iterations, a "good enough" threshold, or a time box. A loop without a stop condition is a liability.

Output Contract

When you use this skill on a job, produce a decomposition plan before executing:

GOAL: <one sentence — the finished state>
MODE: <inline | fixed workflow | orchestrator-workers | autonomous loop> (+ why)
SUBTASKS:
  1. <verb + target> — [parallel with: 2,3 | after: —] — mode: inline
     DONE WHEN: <checkable criterion>
  2. <verb + target> — mode: subagent
     BRIEF: <objective, output format, tools, boundaries>
     DONE WHEN: <checkable criterion>
     WHY SUBAGENT: <context pollution | parallelism | specialization>
VERIFY: <how the assembled result gets checked against ground truth>
STOP: <iteration cap / good-enough threshold>

The plan is a working document: re-plan from results after each wave when the shape of the work is unknown.

Operating Rules

1. Simplest first. Add agents, parallelism, or loops only when the simple version demonstrably falls short. Never lead with machinery.
2. No subtask without a done criterion. If you can't say how you'd check it, it's not scoped yet — split it or cut it.
3. Decompose by domain, not by phase. Handoffs between phases leak context; self-contained domain chunks don't.
4. Delegate on the three triggers only — context pollution, genuine parallelism, specialization. "It feels big" is not a trigger.
5. Briefs are complete or the subtask stays inline. Objective, output format, tools, boundaries, done criteria. No partial briefs.
6. Subagents return summaries, not traces. Distilled findings + references. Full transcripts re-pollute the orchestrator's context — the exact failure the delegation was meant to avoid.
7. Verify against ground truth, not vibes. Tool results, file contents, executed output, primary sources. "Seems right" is not verification.
8. Name your stop condition before you loop. Max iterations or a clear threshold — in writing, before the first pass.

Worked example

Job: "Decide whether to add variable stake tiers to the game platform before Friday's demo."

• Size: open-ended research question with a decision at the end → autonomous loop with research waves, one agent (you). No subagents yet.
• Subtasks:

1. Read current staking code paths (list files, note where $1 fixed is enforced) — inline, DONE WHEN: can name the exact functions/lines.
2. Check Render deploy config + what a tier change touches — inline, DONE WHEN: list of changed files named.
3. Estimate testing burden: what must be re-tested before Friday — inline, DONE WHEN: test list exists.
4. Synthesize: go/no-go with reasons — DONE WHEN: recommendation written with the three evidence points above.

• Mode stays inline — why? All four subtasks need the same full picture (tightly interdependent), none generates enough irrelevant context to justify isolation, and there's no real parallelism (2 and 3 depend on 1). Delegating here would pay 3–10× tokens for coordination overhead and context loss at each handoff.
• Verification: the go/no-go cites the actual code lines and deploy config — checkable by anyone re-reading the plan.
• If step 1 instead required reading a 40,000-token codebase dump: then subtask 1 becomes a subagent with a brief ("return the exact functions enforcing the $1 stake, with file paths and line numbers, and nothing else") — context pollution trigger.

Pattern details and the decision rubric live in references/.