--- 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: MODE: (+ why) SUBTASKS: 1. — [parallel with: 2,3 | after: —] — mode: inline DONE WHEN: 2. — mode: subagent BRIEF: DONE WHEN: WHY SUBAGENT: VERIFY: STOP: ``` 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/`.