Designing Agent Workflows: From One-Off Conversations to Multi-Step Automation · Lesson 3 of 6

Lesson 3: Decomposing a Complex Task into a Workflow

Learning goals:

Master the three task-decomposition strategies

Identify dependencies between tasks

Turn a decomposition into an executable workflow

Prerequisites: Lesson 2: Workflow Building Blocks: Steps, State, Branches, Loops | Next: Lesson 4 >>

From "I don't know where to start" to clear steps

A task lands on your desk: "Split our monolithic Rails app into a microservices architecture." That's a complex task. You don't know where to begin, how many steps it takes, or what each step does.

Task decomposition is how you take a vague, oversized task and break it into small, clear steps.¹

A good decomposition meets three standards:

Each subtask is small enough to finish in a single agent call or function.
Dependencies between subtasks are explicit — you know which must run in order and which can run in parallel.
Each subtask has clear inputs and outputs — one step's output can feed directly into the next.

Decompose well and writing the workflow feels like snapping Lego together. Decompose badly and you'll discover, mid-execution, that steps are missing, the order is wrong, or data won't flow through.²

Strategy 1: Sequential Decomposition

When to use it: the task has a clear front-to-back order, and each step depends on the result of the one before it.

How: work backward from the end. Ask "what input does this step need? Where does that input come from?"

Example: generating technical docs

Task: generate user-facing docs for an API.

Backward decomposition:

Final output: Markdown docs  ↑ needs what?Step 4: render Markdown (needs: structured doc content)  ↑ comes from?Step 3: organize content (needs: endpoint list + example code + descriptions)  ↑ comes from?Step 2: generate an example per endpoint (needs: endpoint list)  ↑ comes from?Step 1: extract the endpoint list from code (needs: source code)  ↑Start: source directory

Final output: Markdown docs  ↑ needs what?Step 4: render Markdown (needs: structured doc content)  ↑ comes from?Step 3: organize content (needs: endpoint list + example code + descriptions)  ↑ comes from?Step 2: generate an example per endpoint (needs: endpoint list)  ↑ comes from?Step 1: extract the endpoint list from code (needs: source code)  ↑Start: source directory

Turned into a workflow:

JAVASCRIPT

async function generateAPIDocsWorkflow(sourceDir) {
  // Step 1: extract endpoints
  const endpoints = await extractEndpoints(sourceDir);
  
  // Step 2: generate examples (depends on step 1)
  const examples = await Promise.all(
    endpoints.map(ep => generateExample(ep))
  );
  
  // Step 3: organize content (depends on steps 1 and 2)
  const content = await agent({
    task: 'Organize the doc structure',
    prompt: 'Organize the endpoints and examples into a user-friendly doc structure',
    context: { endpoints, examples }
  });
  
  // Step 4: render Markdown (depends on step 3)
  const markdown = await renderMarkdown(content);
  
  return markdown;
}

Dependency chain:

Can step 2 run in parallel with step 1? No — step 2 needs step 1's endpoints.

Can step 3 run in parallel with step 2? No — step 3 needs step 2's examples.

What sequential decomposition is like: a long dependency chain, few chances to parallelize, but the logic is clear.³

Strategy 2: Parallel Decomposition

When to use it: the task splits into several independent subtasks that don't depend on each other.

How: spot the "do Y for every X" pattern — each X can be processed in parallel.

Example: security-auditing a codebase

Task: audit 100 files for security issues.

Parallel decomposition:

JAVASCRIPT

async function securityAuditWorkflow(files) {
  // Phase 1: audit each file in parallel (no dependencies)
  const audits = await Promise.all(
    files.map(file => auditFile(file))
  );
  
  // Phase 2: aggregate results (depends on phase 1)
  const summary = await agent({
    task: 'Summarize the security audit',
    prompt: `Analyze the audit results across ${audits.length} files,
             rank issues by severity, and produce an executive summary`,
    context: audits
  });
  
  return summary;
}

async function auditFile(file) {
  return await agent({
    task: `Audit ${file.path}`,
    prompt: `Check for SQL injection, XSS, hardcoded secrets, and weak crypto.
             Return JSON: { file, issues: [{ type, line, severity }] }`
  });
}

Shape:

          ┌─→ auditFile(1) ─┐          ├─→ auditFile(2) ─┤files ───→├─→ auditFile(3) ─┼─→ summary          ├─→   ...         ─┤          └─→ auditFile(100)─┘

          ┌─→ auditFile(1) ─┐          ├─→ auditFile(2) ─┤files ───→├─→ auditFile(3) ─┼─→ summary          ├─→   ...         ─┤          └─→ auditFile(100)─┘

Fan-out-reduce pattern: this is the most common shape for parallel decomposition.⁴

Fan out: spread the task across many parallel agents.
Reduce: merge every result into a final output.

The power of parallel decomposition: 100 files, 2 minutes to audit each. Sequential execution takes 200 minutes; parallel execution takes 2 (assuming no resource limits).

Strategy 3: Hybrid Decomposition

When to use it: most real tasks. Some parts run in parallel, some must run in order.

How: first find the high-level phases (which must run in order), then find the parallel opportunities inside each phase.

Example: a large-scale refactor

Task: upgrade 50 components from Vue 2 to Vue 3.

Hybrid decomposition:

mermaid

graph TD    A[Phase 1: analyze dependencies] --> B{Parallel?}    B -->|Yes| C1[Analyze components 1-25]    B -->|Yes| C2[Analyze components 26-50]    C1 --> D[Phase 2: build migration plan]    C2 --> D    D --> E{Parallel?}    E -->|Yes| F1[Migrate components 1-25]    E -->|Yes| F2[Migrate components 26-50]    F1 --> G[Phase 3: integration tests]    F2 --> G    G --> H{Tests pass?}    H -->|Yes| I[Done]    H -->|No| J[Phase 4: fix failing components]    J --> G

graph TD    A[Phase 1: analyze dependencies] --> B{Parallel?}    B -->|Yes| C1[Analyze components 1-25]    B -->|Yes| C2[Analyze components 26-50]    C1 --> D[Phase 2: build migration plan]    C2 --> D    D --> E{Parallel?}    E -->|Yes| F1[Migrate components 1-25]    E -->|Yes| F2[Migrate components 26-50]    F1 --> G[Phase 3: integration tests]    F2 --> G    G --> H{Tests pass?}    H -->|Yes| I[Done]    H -->|No| J[Phase 4: fix failing components]    J --> G

Turned into a workflow:

JAVASCRIPT

async function vue2to3MigrationWorkflow(components) {
  // Phase 1: analyze all components in parallel
  const analyses = await Promise.all(
    components.map(c => analyzeComponent(c))
  );
  
  // Phase 2: build the migration plan in order (depends on phase 1)
  const plan = await agent({
    task: 'Build the migration plan',
    prompt: 'Based on the analysis, decide the migration order and flag potential conflicts',
    context: analyses
  });
  
  // Phase 3: migrate components in parallel, following the plan
  const migrated = await Promise.all(
    plan.batches.map(batch => 
      Promise.all(batch.map(c => migrateComponent(c)))
    )
  );
  
  // Phase 4: run integration tests in order
  let testResult = await runIntegrationTests();
  
  // Phase 5: if tests fail, fix and retest (loop)
  let attempts = 0;
  while (!testResult.passed && attempts < 3) {
    const failures = testResult.failures;
    await Promise.all(
      failures.map(f => fixComponent(f))
    );
    testResult = await runIntegrationTests();
    attempts++;
  }
  
  if (!testResult.passed) {
    throw new Error('Migration failed: 3 fix attempts all failed the tests');
  }
  
  return { plan, migrated, testResult };
}

Dependency graph for the hybrid:

Phase 1 (parallel)      Phase 2 (sequential)analyze(1..50) ────→ generatePlan                              ↓Phase 3 (parallel)           ↓migrate(1..50) ←────────────┘       ↓Phase 4 (sequential)runTests ←─────┐   ↓           │   ├─pass→ Done │   └─fail→ Phase 5 (parallel + loop)          fix(failures) ─┘

Phase 1 (parallel)      Phase 2 (sequential)analyze(1..50) ────→ generatePlan                              ↓Phase 3 (parallel)           ↓migrate(1..50) ←────────────┘       ↓Phase 4 (sequential)runTests ←─────┐   ↓           │   ├─pass→ Done │   └─fail→ Phase 5 (parallel + loop)          fix(failures) ─┘

The heart of hybrid decomposition: keep the ordering you truly need while squeezing out every chance to parallelize.³

Using an LLM to help you decompose

You can also hand the decomposition to an LLM. Three ways all work: zero-shot prompting, chain-of-thought prompting, and few-shot (example-guided) prompting.¹

Zero-shot

Task: upgrade a REST API's docs, covering 100 endpoints, from Swagger 2.0 to OpenAPI 3.0
Break this task into 5-8 clear steps. For each step, state:1. What it does2. What input it needs3. What it outputs4. Whether it can run in parallel

Task: upgrade a REST API's docs, covering 100 endpoints, from Swagger 2.0 to OpenAPI 3.0
Break this task into 5-8 clear steps. For each step, state:1. What it does2. What input it needs3. What it outputs4. Whether it can run in parallel

Chain-of-thought

Task: refactor a 5000-line Python class by splitting it into several smaller classes
Let's think step by step about how to decompose this:
What should the first step do, and why?What output of the first step does the second step depend on?Which steps can run in parallel?How do we verify each step finished correctly?
Give a detailed decomposition.

Task: refactor a 5000-line Python class by splitting it into several smaller classes
Let's think step by step about how to decompose this:
What should the first step do, and why?What output of the first step does the second step depend on?Which steps can run in parallel?How do we verify each step finished correctly?
Give a detailed decomposition.

Few-shot

I'll give you a complex task. Follow the example to break it into workflow steps.
Example task: batch-process 50 images (resize, add watermark)Example decomposition:1. Read the image list (input: directory path, output: file list)2. Process each image in parallel:   2a. Resize (input: original image, output: resized image)   2b. Add watermark (input: resized image, output: final image)3. Save the results (input: processed image list, output: saved-path list)
Now decompose this task: generate a contributor-stats report for 20 Git repositories

I'll give you a complex task. Follow the example to break it into workflow steps.
Example task: batch-process 50 images (resize, add watermark)Example decomposition:1. Read the image list (input: directory path, output: file list)2. Process each image in parallel:   2a. Resize (input: original image, output: resized image)   2b. Add watermark (input: resized image, output: final image)3. Save the results (input: processed image list, output: saved-path list)
Now decompose this task: generate a contributor-stats report for 20 Git repositories

The upside of LLM decomposition: it drafts a first plan fast and catches steps you might have missed.

The downside of LLM decomposition: it can stay too abstract (say "analyze the data" instead of "compute the cyclomatic complexity of each file"), so it needs a human to sharpen it.¹

Practical tips for spotting dependencies

Tip 1: ask "could this step run before the first one?"

If the answer is "yes," they can run in parallel. If it's "no, it needs the first step's result," there's a dependency.

Tip 2: draw the dependency graph

Arrows mean dependency: A → B means "B depends on A's output"
Step 1 → Step 2 → Step 4         ↓       Step 3 ↗

Arrows mean dependency: A → B means "B depends on A's output"
Step 1 → Step 2 → Step 4         ↓       Step 3 ↗

Can step 2 and step 3 run in parallel? Yes — both depend only on step 1.

Can step 3 and step 4 run in parallel? No — step 4 depends on step 2.

A graph where arrows mean dependency and never loop back to the start has a formal name: a DAG (directed acyclic graph). Step 1 depends on nothing, so it's a leaf the graph can run first. Ordering every step so you never violate an arrow's direction is called a topological sort.

Tip 3: check the data flow

List each step's input and output:

Step	Input	Output
1. Read file	file path	file contents
2. Parse code	file contents	AST
3. Extract functions	AST	function list
4. Generate docs	function list	Markdown

If step X's input comes from step Y's output, X depends on Y.

Common decomposition mistakes

Mistake 1: steps that are too big

What does "prepare the data" cover? Read files? Parse config? Connect to a database? Too vague.

✓ Good:1. Read the config file2. Connect to the database3. Read the source data table4. Transform the data format5. Write to the target data table6. Run a verification query

✓ Good:1. Read the config file2. Connect to the database3. Read the source data table4. Transform the data format5. Write to the target data table6. Run a verification query

Mistake 2: no error-handling steps

What if step 2 fails? Service A is already deployed but B isn't, and the system is in an inconsistent state.

✓ Good:1. Back up the current config2. Deploy service A3. Health-check service A4. If step 3 fails → roll back service A5. Deploy service B6. Health-check service B7. If step 6 fails → roll back services A and B8. Update the load balancer

✓ Good:1. Back up the current config2. Deploy service A3. Health-check service A4. If step 3 fails → roll back service A5. Deploy service B6. Health-check service B7. If step 6 fails → roll back services A and B8. Update the load balancer

Mistake 3: ignoring parallel opportunities

❌ Bad (sequential):for (const service of services) {  await buildService(service);  await testService(service);  await deployService(service);}

❌ Bad (sequential):for (const service of services) {  await buildService(service);  await testService(service);  await deployService(service);}

This processes each service one at a time. Slow.

✓ Good (hybrid parallel):// Build all services in parallelawait Promise.all(services.map(s => buildService(s)));
// Test all services in parallelawait Promise.all(services.map(s => testService(s)));
// Deploy all services in parallelawait Promise.all(services.map(s => deployService(s)));

✓ Good (hybrid parallel):// Build all services in parallelawait Promise.all(services.map(s => buildService(s)));
// Test all services in parallelawait Promise.all(services.map(s => testService(s)));
// Deploy all services in parallelawait Promise.all(services.map(s => deployService(s)));

Next: Lesson 4: State Management and Passing Context — learn how to pass and manage data correctly between the steps of a workflow.

ApX Machine Learning: Task Decomposition Strategies for LLM Agents — https://apxml.com/courses/agentic-llm-memory-architectures/chapter-4-complex-planning-tool-integration/task-decomposition-strategies ↩ ↩² ↩³
ACONIC paper: Systematic LLM Task Decomposition — https://arxiv.org/html/2510.07772v1 ↩
OneUpTime: How to Create a Task Decomposition — https://oneuptime.com/blog/post/2026-01-30-task-decomposition/view ↩ ↩²
MindStudio: Five Claude Code Agentic Workflow Patterns — https://www.mindstudio.ai/blog/claude-code-agentic-workflow-patterns ↩

Exercises

Pick one of the tasks below and break it into 5-8 steps:

Level 1: Decompose a real task

Task A: generate a performance report for a web app (load time, resource size, Core Web Vitals)

Task B: clean up a Git repository (remove unused dependencies, delete dead code, update stale comments)

Requirements:

For each step, spell out what it does, its input, and its output
Mark which steps can run in parallel
Draw the dependency graph (words or arrows)
Say whether it's sequential, parallel, or hybrid decomposition

Done criteria · checked locally

The step count is reasonable (5-8 steps, not 3 huge ones and not 15 fragments)each step has clear inputs and outputsparallel opportunities are correctly identified (e.g. in Task A, load time, resource size, and Core Web Vitals can be measured in parallel)the dependency graph is correctthe choice of decomposition strategy is sound.

Below is a decomposition for a "batch-migrate API endpoints" task. It has 3 serious problems. Find them and give a corrected plan.

Level 2: Fix a broken decomposition

Original decomposition:1. Read all API endpoint configs2. Generate the new endpoint definitions3. Deploy to production

Original decomposition:1. Read all API endpoint configs2. Generate the new endpoint definitions3. Deploy to production

Requirements:

Find the 3 problems (hint: steps too big, no error handling, ignored parallelism)
Give a corrected, complete decomposition (5-8 steps)

Done criteria · checked locally

Correctly identifies the 3 key problems (step 2 is too vague and doesn't say how to generatethere's no test/verification stepthere's no rollbackmultiple endpoints aren't processed in parallel)the corrected plan has at least 6 stepsit includes a test/verification stepit includes an error-handling or rollback stepit identifies the parallel opportunity.

Lesson 3: Decomposing a Complex Task into a Workflow

From "I don't know where to start" to clear steps

Strategy 1: Sequential Decomposition

Example: generating technical docs

Strategy 2: Parallel Decomposition

Example: security-auditing a codebase

Strategy 3: Hybrid Decomposition

Example: a large-scale refactor

Using an LLM to help you decompose

Zero-shot

Chain-of-thought

Few-shot

Practical tips for spotting dependencies

Common decomposition mistakes

Footnotes

Exercises

Pick one of the tasks below and break it into 5-8 steps:

Below is a decomposition for a "batch-migrate API endpoints" task. It has 3 serious problems. Find them and give a corrected plan.