task-decomposition

What this skill does

# Task Decomposition Strategy

This skill provides comprehensive guidelines for breaking down project goals into actionable tasks. Use this when planning teamwork projects to ensure optimal task granularity, proper role assignment, and appropriate complexity assessment.

---

## Hybrid Decomposition Strategy

Use a combination of plan-based (Strategy A) and semantic (Strategy B) decomposition:

### Strategy A: Plan Document Based

Use when `plans` option is provided with detailed implementation documents.

1. **Extract Steps**: Parse plan documents for Markdown headers (## Step N, ### Phase N)
2. **Map to Tasks**: Each header section becomes a task candidate
3. **Sub-decompose**: If a step mentions multiple files (>3), split into sub-tasks
4. **Verify Atomicity**: Each task should be completable in one worker session

Example transformation:
```
Plan: "03.impl-workspace-setup.md"
|- Step 1: Root workspace -> Task: "Initialize pnpm monorepo workspace"
|- Step 2.1: Database package -> Task: "Create database package structure"
|- Step 2.2: items schema -> Task: "Implement items.schema.ts"
|- Step 2.3: item-features schema -> Task: "Implement item-features.schema.ts with pgvector"
+- Step 3: Docker -> Task: "Configure Docker Compose for dev environment"
```

### Strategy B: Semantic Decomposition

Use when no plan documents provided, or as sub-decomposition within Strategy A.

1. **File-based**: New file creation = separate task
2. **Complexity-based**: Complex file with multiple classes -> split by class
3. **Dependency-based**: Interface and implementation = separate tasks
4. **Test-based**: Each independently testable unit = candidate task

---

## Granularity Rules

- 1 task = 1-3 files changed (recommended)
- 1 task = 10-30 minutes work (recommended)
- 1 task = independently testable/verifiable

### Anti-patterns (Avoid)

- "Setup entire workspace" (too broad)
- "Implement backend" (too vague)
- "Create all schemas" (bundles multiple files)

### Good patterns (Recommended)

- "Create items.schema.ts with Item table"
- "Add SearchUseCase with keyword search"
- "Configure Docker Compose for PostgreSQL"

---

## Task Creation with Native API

Create tasks using the native `TaskCreate` API:

```python
# Create a task
TaskCreate(
    subject="Implement items.schema.ts",
    description="Create PostgreSQL schema for items table with id, name, description, price columns. Include proper indexes.",
    activeForm="Implementing items schema"
)  # Returns task with auto-assigned ID
```

### Setting Dependencies

Use `TaskUpdate` with `addBlockedBy` to define task dependencies:

```python
# Task 1: no dependencies (can start immediately)
TaskCreate(subject="Setup database schema", description="...")  # -> task 1

# Task 2: depends on task 1
TaskCreate(subject="Implement auth middleware", description="...")  # -> task 2
TaskUpdate(taskId="2", addBlockedBy=["1"])

# Task 3: depends on task 2
TaskCreate(subject="Create login/signup UI", description="...")  # -> task 3
TaskUpdate(taskId="3", addBlockedBy=["2"])

# Task 4: depends on both task 1 and task 2
TaskCreate(subject="Write integration tests", description="...")  # -> task 4
TaskUpdate(taskId="4", addBlockedBy=["1", "2"])
```

### Dependency Rules

- **Minimize dependencies**: Maximize parallelism by only adding necessary `blockedBy` links
- **No circular dependencies**: Task A blocks B blocks A is invalid
- **Blocked tasks auto-unblock**: When all `blockedBy` tasks complete, the task becomes available for workers
- **Independent tasks have no blockedBy**: They can be picked up by any idle worker immediately

### Example: Full Task Creation

```python
# Foundation tasks (no dependencies)
TaskCreate(subject="Initialize project structure", description="...")      # -> task 1
TaskCreate(subject="Configure TypeScript and ESLint", description="...")  # -> task 2

# Core implementation (depends on foundation)
TaskCreate(subject="Create database models", description="...")           # -> task 3
TaskUpdate(taskId="3", addBlockedBy=["1"])

TaskCreate(subject="Implement REST API endpoints", description="...")     # -> task 4
TaskUpdate(taskId="4", addBlockedBy=["1", "3"])

TaskCreate(subject="Build React components", description="...")           # -> task 5
TaskUpdate(taskId="5", addBlockedBy=["2"])

# Integration (depends on both API and UI)
TaskCreate(subject="Connect frontend to API", description="...")          # -> task 6
TaskUpdate(taskId="6", addBlockedBy=["4", "5"])

# Testing (depends on integration)
TaskCreate(subject="Write E2E tests", description="...")                  # -> task 7
TaskUpdate(taskId="7", addBlockedBy=["6"])
```

This creates a natural execution order where independent tasks run in parallel and dependent tasks wait for their prerequisites.

---

## Role Assignment

Assign each task to the appropriate role based on its primary focus:

| Role       | When to Use                                |
| ---------- | ------------------------------------------ |
| `frontend` | UI, components, styling, user interactions |
| `backend`  | API, services, database, business logic    |
| `test`     | Tests, fixtures, mocks                     |
| `devops`   | CI/CD, deployment, infrastructure          |
| `docs`     | Documentation, README, examples            |
| `security` | Auth, permissions, input validation        |
| `review`   | Code review, refactoring                   |
| `general`  | Miscellaneous, cross-cutting               |

---

## Complexity Assessment

Workers use different models based on task complexity. Assign complexity to optimize resource usage:

| Complexity | Model | Criteria | Examples |
| ---------- | ----- | -------- | -------- |
| `simple`   | haiku | Single file, <10 lines, minor changes | Config updates, typo fixes, simple docs |
| `standard` | sonnet | 1-3 files, typical CRUD, straightforward | API endpoints, UI components, tests |
| `complex`  | opus | 5+ files, architecture, security-critical | Auth systems, DB migrations, major refactors |

### Guidelines for Complexity Assessment

- **simple**: Task is obvious, minimal thinking required, low risk
- **standard**: Task requires moderate planning, some decision-making
- **complex**: Task requires deep analysis, multiple considerations, high impact

### Decision Rules

**Default to `standard`** when uncertain. Upgrade to `complex` if:
- Task involves authentication/authorization
- Task touches database schema
- Task spans 5+ files
- Task has architectural implications
- Task is security-sensitive

---

## Structured Description Convention

Tasks should use structured descriptions with markdown sections to provide clear guidance to workers.

### Description Template

```markdown
## Description
What needs to be done (clear, actionable explanation)

## Approach
standard | tdd

## Success Criteria
- Criterion 1
- Criterion 2
- Criterion 3

## Verification Commands
command1
command2
```

### Section Definitions

| Section | Required | Default | Purpose |
|---------|----------|---------|---------|
| `## Description` | Yes | - | What needs to be done |
| `## Approach` | No | standard | `standard` or `tdd` workflow |
| `## Success Criteria` | Recommended | General evidence | Checklist for verification |
| `## Verification Commands` | Recommended | Skip | Commands workers run to verify |

### Approach Selection

| Task Type | Recommended Approach | Rationale |
|-----------|---------------------|-----------|
| New feature with clear spec | tdd | Test-first ensures spec compliance |
| Bug fix | tdd | Test reproduces bug first |
| Refactoring | standard | Existing tests cover behavior |
| Configuration/docs | standard | Not testable |
| Security-critical code | tdd | Security tests first |
| API endpoints | tdd | Contract-driven development |
| Database schema | standard | Migrations not test-driven |
| UI components | standard | Visual testing preferred |

### Success Criteria Guidelines

**Good criteria are:**
- **Specific**: "Test