task-decomposition

name	task-decomposition
description	Break down complex tasks into atomic, actionable goals with clear dependencies and success criteria. Use this skill when you need to plan multi-step projects, coordinate agents, or decompose complex user requests into manageable sub-tasks.

Task Decomposition

Enable effective planning and execution by decomposing high-level objectives into manageable, testable sub-tasks.

When to Use

• Complex user requests with multiple components
• Multi-phase projects requiring coordination
• Tasks that could benefit from parallel execution
• When planning agent coordination strategies

Decomposition Framework

1. Requirements Analysis

Extract Information:

• Primary objective (what user wants to achieve)
• Implicit requirements (quality, performance, documentation)
• Constraints (time, resources, compatibility)
• Success criteria (how to measure completion)

Questions to Ask:

• What is the core goal?
• What are the sub-goals that contribute to the main goal?
• What are the dependencies between sub-goals?
• What could go wrong and how to prevent it?

2. Goal Hierarchy

Top-Down Decomposition:

Main Goal: [High-level objective]
├─ Sub-goal 1: [Component 1]
│  ├─ Task 1.1: [Atomic action]
│  └─ Task 1.2: [Atomic action]
├─ Sub-goal 2: [Component 2]
│  ├─ Task 2.1: [Atomic action]
│  └─ Task 2.2: [Atomic action]
└─ Sub-goal 3: [Component 3]
   └─ Task 3.1: [Atomic action]

Atomic Task Criteria:

• Single, clear action
• Well-defined inputs and outputs
• Can be completed by one agent
• Testable/verifiable completion
• Time-bounded (estimable duration)

3. Dependency Mapping

Dependency Types:

Sequential Dependencies:

Task A → Task B → Task C
(B requires A's output, C requires B's output)

Parallel Independent:

Task A ─┐
Task B ─┼─ [All can run simultaneously]
Task C ─┘

Converging Dependencies:

Task A ─┐
Task B ─┼─> Task D (requires A, B, C)
Task C ─┘

Resource Dependencies:

Task A (needs resource X)
Task B (needs resource X)
→ Sequential or resource pooling required

4. Success Criteria Definition

For each task, define:

Input Requirements:

• What data/state is needed to start
• What resources must be available
• What preconditions must be met

Output Expectations:

• What artifacts will be produced
• What state changes will occur
• What metrics define success

Quality Standards:

• Performance requirements
• Code quality standards (from AGENTS.md)
• Testing requirements
• Documentation requirements

Decomposition Process

Step 1: Understand the Goal

User Request: [Original request]

Analysis:
- Primary Goal: [Main objective]
- Type: [Implementation/Debug/Refactor/Analysis]
- Domain: [Specific area of codebase]
- Complexity: [Simple/Medium/Complex]

Step 2: Identify Major Components

Break main goal into 3-7 major components:

Main Goal: Implement batch pattern update feature

Major Components:
1. Database layer (Turso + redb)
2. API layer (public interface)
3. Business logic (batch processing)
4. Testing (unit + integration)
5. Documentation (API docs + examples)

Step 3: Decompose Each Component

For each component, identify atomic tasks:

Component: Database layer

Tasks:
1. Design batch schema/structure
   - Input: Pattern data structures
   - Output: Schema definition
   - Success: Supports efficient batch operations

2. Implement Turso batch operations
   - Input: Schema, patterns array
   - Output: Batch insert/update functions
   - Success: Atomic transaction, proper error handling

3. Implement redb batch caching
   - Input: Schema, patterns array
   - Output: Batch cache update functions
   - Success: Fast writes, consistency maintained

Step 4: Map Dependencies

Dependency Graph:

[Design schema] ──┬──> [Implement Turso batch] ──┐
                  │                               ├──> [Write tests]
                  └──> [Implement redb batch] ───┘

[Write tests] ──> [Write documentation]

Step 5: Assign Priorities

Priority Levels:

• P0 (Critical): Must complete for goal achievement
• P1 (Important): Significantly improves quality/functionality
• P2 (Nice-to-have): Enhances but not essential

Prioritization Factors:

• Blocks other tasks (critical path)
• High user value
• Risk reduction (address unknowns early)
• Quick wins (early validation)

Step 6: Estimate Complexity

For each task:

Task: [Name]
- Complexity: [Low/Medium/High]
- Effort: [Small/Medium/Large]
- Risk: [Low/Medium/High]
- Dependencies: [List]

Decomposition Patterns

Pattern 1: Layer-Based Decomposition

For architectural changes:

1. Data/Storage layer
2. Business logic layer
3. API/Interface layer
4. Testing layer
5. Documentation layer

Pattern 2: Feature-Based Decomposition

For new features:

1. Core functionality (MVP)
2. Error handling & edge cases
3. Performance optimization
4. Integration with existing system
5. Testing & validation
6. Documentation & examples

Pattern 3: Phase-Based Decomposition

For large projects:

Phase 1: Research & Design
Phase 2: Foundation & Infrastructure
Phase 3: Core Implementation
Phase 4: Integration & Testing
Phase 5: Optimization & Polish
Phase 6: Documentation & Release

Pattern 4: Problem-Solution Decomposition

For debugging/fixing:

1. Reproduce issue
2. Diagnose root cause
3. Design solution
4. Implement fix
5. Verify fix
6. Prevent regression (tests)

Example Decompositions

Example 1: Simple Task

Request: "Fix failing test in pattern extraction"

Analysis: Simple, focused task

Decomposition:
1. Run test to observe failure
2. Identify failure cause
3. Apply fix
4. Verify test passes
5. Check for similar issues

Dependencies: Sequential (1→2→3→4→5)
Complexity: Low
Strategy: Single agent, sequential execution

Example 2: Medium Task

Request: "Add caching to episode retrieval"

Analysis: Medium complexity, multiple components

Decomposition:
1. Design cache strategy
2. Implement cache layer
3. Integrate with retrieval
4. Add tests
5. Measure performance

Dependencies:
- 1 → 2 → 3 (sequential)
- 4 depends on 3
- 5 depends on 3

Strategy: Sequential with parallel testing

Example 3: Complex Task

Request: "Refactor storage layer to support multiple backends"

Analysis: High complexity, architectural change

Major Components:
1. Storage abstraction layer
2. Turso backend implementation
3. redb backend implementation
4. Backend factory & configuration
5. Migration utilities
6. Testing infrastructure
7. Documentation

Strategy: Multi-phase hybrid execution
Coordination: GOAP agent + multiple specialized agents

Quality Checklist

Good Decomposition Characteristics

✓ Each task is atomic and actionable ✓ Dependencies are clearly identified ✓ Success criteria are measurable ✓ Complexity is appropriately estimated ✓ All requirements are covered ✓ No task is too large (>4 hours work) ✓ Parallelization opportunities identified

Common Pitfalls

✗ Tasks too large or vague ✗ Missing dependencies ✗ Unclear success criteria ✗ Over-decomposition (too granular) ✗ Missing quality/testing tasks ✗ No consideration for error handling ✗ Forgetting documentation tasks

Integration with GOAP Agent

The GOAP agent uses task decomposition as its first phase:

1. Receive user request
2. Apply decomposition framework (this skill)
3. Create execution plan (agent-coordination skill)
4. Execute with monitoring (parallel-execution skill)
5. Report results

Tips for Effective Decomposition

1. Start with Why

• Understand the true goal behind the request
• Identify implicit requirements
• Consider broader context

2. Think Top-Down

• Start with high-level components
• Decompose each component separately
• Stop at appropriate granularity

3. Consider the User

• What value does each task provide?
• Can tasks be reordered for faster feedback?
• What's the minimum viable solution?

4. Plan for Quality

• Include testing tasks
• Include documentation tasks
• Include review/validation tasks

5. Anticipate Issues

• What could go wrong?
• What are the unknowns?
• Where are the risks?

6. Enable Parallelization

• Identify truly independent tasks
• Break dependencies where possible
• Consider resource constraints

Summary

Good task decomposition is the foundation of effective planning and coordination. By breaking complex goals into atomic, well-defined tasks with clear dependencies, you enable:

• Optimal execution strategies (parallel/sequential)
• Clear success criteria and validation
• Effective agent coordination
• Better progress tracking
• Higher quality outcomes

Use this skill as the first step in any complex task planning workflow.