Complex Task Decomposition

Large tasks overwhelm single agent sessions. The solution isn’t a better prompt — it’s breaking the task into units that fit comfortably within a single context window while maintaining coherence across the whole.

The Decomposition Principle

A task is too large for a single session when:

• It requires reading more than 15-20 files to understand
• It spans more than 3 major components
• It would take a human developer more than a day
• The implementation plan has more than 10 steps

When any of these apply, decompose before executing.

Decomposition Strategies

Vertical Slicing

Break features into thin, end-to-end slices rather than horizontal layers:

# BAD: Horizontal decomposition
Task 1: Build all database models
Task 2: Build all API endpoints
Task 3: Build all frontend components
Task 4: Connect everything

# GOOD: Vertical decomposition
Task 1: User can create an account (DB + API + UI)
Task 2: User can log in (DB + API + UI)
Task 3: User can reset password (DB + API + UI)

Each vertical slice is independently testable and deployable.

Dependency-Ordered Decomposition

Order tasks by dependency, with foundational work first:

1. Foundation: Shared types, interfaces, and schemas
2. Infrastructure: Database migrations, middleware, shared utilities
3. Core logic: Business rules and service layer
4. Integration: API endpoints, event handlers
5. Interface: UI components, CLI commands
6. Verification: Integration tests, E2E tests

Research-Informed Decomposition

Let a research sub-agent inform the decomposition:

Use sub-agents to research:
1. All files that would need to change for [feature]
2. Dependencies between these files
3. Existing test infrastructure

Then create a decomposition plan that:
- Groups related changes into independent tasks
- Orders tasks by dependency
- Estimates context cost per task
- Identifies tasks that can run in parallel

Task Sizing

Each decomposed task should:

Property	Target
Files read	< 10
Files modified	< 5
Context utilization	< 60%
Verification	Self-contained (own tests)
Duration	15-45 minutes

Tip

If a task requires reading more than 10 files, consider whether a sub-agent should do the reading and provide a summary instead.

Coordination Across Tasks

Shared Spec

All tasks reference a single specification file:

# Task 3 of 6: Implement password reset service
Follow .sdlc/specs/auth-overhaul.md, section "Password Reset."
Previous tasks have completed the DB models and auth middleware.
Build on those — don't modify them.

Interface Contracts

Define interfaces between tasks before implementation:

// Agreed interface — all tasks code against this
interface AuthService {
  login(email: string, password: string): Promise<Result<Session, AuthError>>;
  resetPassword(token: string, newPassword: string): Promise<Result<void, AuthError>>;
  // ... defined before any task starts
}

Progressive Integration

Each task integrates with previous tasks:

Task 1: Foundation → commit → verify
Task 2: Core logic → integrates with Task 1 → commit → verify
Task 3: API layer → integrates with Task 1+2 → commit → verify
Task 4: Full integration test → verifies everything together

Parallel Execution

Independent tasks can run in parallel via worktree-isolated agents:

Main Agent: Decomposes into 3 independent tasks
├── Agent (worktree-1): Task A (user service)
├── Agent (worktree-2): Task B (notification service)
└── Agent (worktree-3): Task C (analytics service)
    └── Main Agent: Reviews and merges all branches

Tasks are independent when they:

• Modify different files
• Don’t share mutable state
• Have defined interface contracts
• Can be tested in isolation