name	task-breakdown
description	Break technical designs into atomic, TDD-driven tasks with 5-20 minute granularity, clear dependencies, and parallel execution opportunities

Task Breakdown

Overview

Transform technical design documents into executable, atomic tasks with Test-Driven Development ordering, clear dependencies, and maximum parallelization opportunities.

Core Principle: Tasks should be atomic (5-20 min), independently testable, and organized by TDD phases (Red � Green � Refactor).

Announce at start: "I'm using the task-breakdown skill to create an implementation plan with atomic, TDD-ordered tasks."

Quick Reference

Phase	Purpose	Key Pattern	Output
Foundation Tasks	Core infrastructure	Blocks all stories	Database, DI, base schemas
Per-Story Tasks	User story implementation	Red � Green � Refactor	Tests � Impl � Verify
Dependency Mapping	Execution order	Sequential vs parallel	Dependency graph
Rastreabilidade	Task � requirement mapping	Full traceability	Traceability matrix
Parallel Groups	Concurrent execution	Mark [P] for parallel tasks	Parallel execution plan

Task Granularity: The 5-20 Minute Rule

Why 5-20 Minutes?

Benefits:

Focus: Small enough to complete in one sitting
Visibility: Progress is constantly visible
Flexibility: Easy to reorder or deprioritize
Estimation accuracy: Easier to estimate small tasks
CI/CD friendly: Small commits, fast builds

Too Small (< 5 min): Overhead exceeds value (e.g., "Add semicolon")

Too Large (> 20 min): Becomes vague, hard to estimate, risky

Examples

Good (Atomic, 5-20 min):

"Create User entity in src/domain/entities/user.entity.ts"
"Implement UserRepository interface in src/domain/ports/repositories/user.repository.ts"
"Write failing test for SendMessage use case in src/application/use-cases/__tests__/send-message.use-case.test.ts"
"Implement bcrypt password hashing in src/infrastructure/adapters/crypto/bcrypt-hasher.ts"

L Bad (Too Vague or Large):

"Implement user functionality" (What does "functionality" mean? Too broad)
"Add database support" (Which tables? What operations? Too vague)
"Build authentication system" (Too large, many subtasks needed)

The Process

Phase 1: Read Design Documents

Goal: Understand complete technical scope

Activities:

Read technical design: docs/design/DESIGN-{###}-{name}.md
Read all ADRs referenced in design: docs/adr/ADR-*.md
Read specification for user stories: docs/specs/SPEC-{###}-{name}.md
Note architecture gates and complexity tracking

Questions to Answer:

What architecture pattern are we using? (Clean Architecture, Hexagonal, etc.)
What is the system structure? (Layers, directories, modules)
What entities, value objects, and repositories are needed?
What API endpoints need to be implemented?
What user stories need to be fulfilled?

Output: Understanding of technical scope

Phase 2: Organize by Implementation Phases

Goal: Structure tasks into logical execution phases

Phase Structure (from Task-Master & Spec-Kit):

PHASE 0: Foundation (Core Infrastructure)
 Project structure
 Database setup
 DI Container
 Base error handling
 Zod schema structure

PHASE 1: User Story 1 (P1 - MVP)
 Tests First (Red)
 Implementation (Green)
 Verification

PHASE 2: User Story 2 (P2)
 Tests First (Red)
 Implementation (Green)
 Verification

PHASE N: User Story N (P3)
 Tests First (Red)
 Implementation (Green)
 Verification

PHASE FINAL: Quality Gates
 Complete test coverage
 Documentation
 Final validation

Key Insight: Foundation blocks ALL stories. User stories are independent after foundation.

Phase 3: Foundation Tasks (Phase 0)

Goal: Create core infrastructure that all features depend on

Foundation Checklist:

3.1 Project Structure

- [ ] T001 [] Create Clean Architecture directory structure
  - Layers: src/domain/, src/application/, src/infrastructure/ (including infrastructure/http/)
  - Files: Exact paths from DESIGN-{###}
  - Depends: None (first task)
  - Estimate: 5 min

3.2 Database Schema & Migrations

- [ ] T002 [] Create Drizzle schema for User entity
  - Story: Foundation
  - Requirements: FR-001 (data model)
  - Files: src/infrastructure/database/schemas/user.schema.ts
  - Depends: T001
  - Estimate: 10 min

- [ ] T003 [] Generate and run initial migration
  - Story: Foundation
  - Requirements: FR-001
  - Files: drizzle/migrations/0001_initial.sql
  - Depends: T002
  - Estimate: 5 min

3.3 DI Container Setup

- [ ] T004 [] Create DI Container with Symbol tokens
  - Story: Foundation
  - Requirements: Clean Architecture pattern (ADR-####)
  - Files: src/infrastructure/container/types.ts, src/infrastructure/container/container.ts
  - Depends: T001
  - Estimate: 15 min
  - Note: Symbol-based tokens for type safety

- [ ] T005 [] Create registration functions by layer
  - Story: Foundation
  - Requirements: Clean Architecture
  - Files: src/infrastructure/container/register-domain.ts, register-application.ts, register-infrastructure.ts
  - Depends: T004
  - Estimate: 10 min

3.4 Base Error Handling

- [ ] T006 [] Create Result<T, E> type for error handling
  - Story: Foundation
  - Requirements: NFR-M-001 (maintainability)
  - Files: src/domain/shared/result.ts
  - Depends: T001
  - Estimate: 10 min

3.5 Zod Schema Structure

- [ ] T007 [] Create base Zod schemas directory
  - Story: Foundation
  - Requirements: Type Safety Gate
  - Files: src/infrastructure/http/schemas/index.ts
  - Depends: T001
  - Estimate: 5 min

Foundation Phase Complete: All user stories can now begin in parallel (after foundation tasks complete)

Phase 4: Per-Story Task Breakdown (TDD Order)

Goal: For EACH user story, create tasks in TDD order: Red � Green � Refactor

TDD Phases:

Red: Write failing tests FIRST
Green: Implement minimum code to make tests pass
Refactor: Clean up implementation while keeping tests green

4.1 Tests First (Red Phase)

For each user story:

### User Story 1 - Real-Time Message Delivery (P1)

#### Red Phase: Tests First

- [ ] T101 [] Write failing contract test for POST /api/messages endpoint

  - Story: US-1
  - Requirements: FR-001, NFR-P-001
  - Files: tests/integration/api/messages.integration.test.ts
  - Depends: T001-T007 (foundation)
  - Estimate: 15 min
  - Note: Must FAIL initially (endpoint doesn't exist yet)

- [ ] T102 [] Write failing integration test for SendMessage use case

  - Story: US-1
  - Requirements: FR-001
  - Files: src/application/use-cases/**tests**/send-message.use-case.test.ts
  - Depends: T001-T007
  - Estimate: 15 min
  - Note: Test with mock repository

- [ ] T103 [] Write failing E2E test for full message send journey
  - Story: US-1
  - Requirements: FR-001, US-1 acceptance criteria
  - Files: tests/e2e/messages/send-message.e2e.test.ts
  - Depends: T001-T007
  - Estimate: 20 min
  - Note: Uses real WebSocket connection

**Verification Checkpoint:** Run all tests � All FAIL (expected in Red phase)

4.2 Implementation (Green Phase)

Implement minimum code to make tests pass:

#### Green Phase: Implementation

- [ ] T104 [P] Create Message entity

  - Story: US-1
  - Requirements: FR-001
  - Files: src/domain/entities/message.entity.ts
  - Depends: T101-T103 (tests written)
  - Estimate: 10 min

- [ ] T105 [P] Create MessageContent value object

  - Story: US-1
  - Requirements: FR-006 (5000 char limit)
  - Files: src/domain/value-objects/message-content.ts
  - Depends: T101-T103
  - Estimate: 10 min

- [ ] T106 [P] Create MessageRepository interface

  - Story: US-1
  - Requirements: FR-002 (persistence)
  - Files: src/domain/ports/repositories/message.repository.ts
  - Depends: T101-T103
  - Estimate: 5 min

- [ ] T107 [] Implement MessageRepository with Drizzle

  - Story: US-1
  - Requirements: FR-002
  - Files: src/infrastructure/repositories/message.repository.impl.ts
  - Depends: T106
  - Estimate: 15 min

- [ ] T108 [] Implement SendMessage use case

  - Story: US-1
  - Requirements: FR-001, FR-002
  - Files: src/application/use-cases/send-message.use-case.ts
  - Depends: T104, T105, T106
  - Estimate: 15 min

- [ ] T109 [] Create POST /api/messages self-registering controller

  - Story: US-1
  - Requirements: FR-001
  - Files: src/infrastructure/http/controllers/messages.controller.ts
  - Depends: T108
  - Estimate: 10 min
  - Note: Controller auto-registers routes in constructor via HttpServer port

- [ ] T110 [] Setup HttpServer adapter (if not exists)

  - Story: US-1
  - Requirements: FR-001
  - Files: src/infrastructure/http/server/hono-http-server.adapter.ts
  - Depends: T109
  - Estimate: 5 min

- [ ] T111 [] Register Message dependencies in DI container
  - Story: US-1
  - Requirements: Clean Architecture
  - Files: src/infrastructure/container/register-application.ts
  - Depends: T107, T108
  - Estimate: 10 min

**Verification Checkpoint:** Run tests (T101-T103) � All PASS (Green achieved!)

4.3 Refactor Phase (Optional)

Clean up code while keeping tests green:

#### Refactor Phase (if needed)

- [ ] T112 [] Extract message validation logic to separate validator

  - Story: US-1
  - Requirements: Clean Code Gate (functions < 20 lines)
  - Files: src/domain/validators/message.validator.ts
  - Depends: T108 (use case implemented)
  - Estimate: 10 min
  - Note: Only if SendMessage use case exceeds 20 lines

- [ ] T113 [] Refactor repository error handling to use Result<T, E>
  - Story: US-1
  - Requirements: NFR-M-001
  - Files: src/infrastructure/repositories/message.repository.impl.ts
  - Depends: T107
  - Estimate: 10 min

**Verification Checkpoint:** Run tests � All still PASS (refactor didn't break anything)

Phase 5: Task Format & Metadata

Goal: Provide complete information for each task

Task Format:

- [ ] T{###} [P?] [US#] {Clear, specific description}
  - Story: US-# or Foundation or Final
  - Requirements: FR-###, NFR-{category}-###
  - Files: {exact file paths from technical design}
  - Depends: T###, T### (list all prerequisite tasks)
  - Estimate: {5-20 minutes}
  - Note: {Additional context if needed}

Field Explanations:

T{###}: Sequential task number (T001, T002, etc.)
[P]: Parallel marker - can execute concurrently with other [P] tasks in same phase
[US#]: User story reference (optional, for clarity)
Description: Active voice, specific action + file/component
Story: Which user story or phase this supports
Requirements: Traceability to spec requirements
Files: Exact file paths (enables quick navigation)
Depends: Prerequisites (enforces execution order)
Estimate: Time estimate (5-20 min for atomic tasks)
Note: Additional context, edge cases, reminders

Example:

- [ ] T104 [P] [US-1] Create Message entity
  - Story: US-1
  - Requirements: FR-001
  - Files: src/domain/entities/message.entity.ts
  - Depends: T101, T102, T103 (tests written first)
  - Estimate: 10 min
  - Note: Include userId, roomId, content (MessageContent VO), createdAt

Phase 6: Dependency Mapping

Goal: Create visual dependency graph showing execution order

Dependency Types:

Sequential: Must complete Task A before starting Task B
Parallel: Tasks can run concurrently (marked with [P])
Batch: Group of parallel tasks that must all complete before next phase

Dependency Graph Example:

Foundation Phase (Sequential, then Parallel):
T001 (structure)
  � T002 (DB schema) � T003 (migration)
  � T004 (DI container) � T005 (register functions)
  � T006 (Result type)
  � T007 (Zod base)

User Story 1 - Tests (Sequential):
T001-T007 completed
  � T101 (contract test)
  � T102 (integration test)
  � T103 (E2E test)

User Story 1 - Implementation (Parallel batch):
T101-T103 completed
  � [P] T104 (Message entity)
  � [P] T105 (MessageContent VO)
  � [P] T106 (MessageRepository interface)
        � T107 (MessageRepository impl)
             � T111 (DI registration)
        � T108 (SendMessage use case)
              � T109 (Controller)
                    � T110 (Routes)

Verification:
T110 completed � Run tests T101-T103 (expect GREEN)

Refactor (Optional, Parallel if multiple):
T110 completed
  � [P] T112 (Extract validator)
  � [P] T113 (Result error handling)

Parallel Opportunities Identification:

Tasks with same dependencies and no inter-dependencies can run in parallel
Mark with [P] in task list
Example: T104, T105, T106 all depend on T101-T103 but don't depend on each other � [P]

Phase 7: Rastreabilidade (Traceability Matrix)

Goal: Map every task back to requirements and user stories

Format:

## Traceability Matrix

| Task ID | User Story | Requirements      | Files                                   |
| ------- | ---------- | ----------------- | --------------------------------------- |
| T001    | Foundation | Architecture      | src/domain/, src/application/, ...      |
| T002    | Foundation | FR-001            | src/infrastructure/database/schemas/... |
| T101    | US-1       | FR-001, NFR-P-001 | tests/integration/api/messages.int...   |
| T104    | US-1       | FR-001            | src/domain/entities/message.entity.ts   |
| T108    | US-1       | FR-001, FR-002    | src/application/use-cases/send-...      |

Why This Matters:

Impact analysis: Changing FR-001 affects tasks T002, T101, T104, T108
Coverage verification: Every requirement has corresponding tasks
Progress tracking: Can track US-1 completion by task completion

Phase 8: Generate Implementation Plan & Tasks Documents

Goal: Create structured documents for execution

8.1 Implementation Plan

Activities:

Load ~/.claude/plugins/marketplaces/claude-craftkit/plugins/product-engineering/templates/implementation-plan.md
Auto-number: Scan docs/plans/ for next PLAN-###
Fill sections with phases, approach, architecture gates
Link to design: design: DESIGN-{###}
Save to docs/plans/PLAN-{###}-{name}.md

Template Sections:

Header: Plan number, design link, status, created date
Overview: High-level implementation approach
Phase -1: Pre-Implementation Gates: Architecture gates validation
Phase 0: Foundation: Core infrastructure tasks
Phase 1-N: User Stories: Per-story implementation with TDD
Phase Final: Quality Gates: Final validation
Dependencies: Dependency graph
Parallel Execution: Opportunities for concurrent work
Rastreabilidade: Task � requirement mapping

8.2 Tasks Document

Activities:

Load ~/.claude/plugins/marketplaces/claude-craftkit/plugins/product-engineering/templates/tasks.md
Auto-number: Scan docs/tasks/ for next TASKS-###
Fill with complete task list (T001-TXXX)
Link to plan: plan: PLAN-{###}
Save to docs/tasks/TASKS-{###}-{name}.md

Template Sections:

Header: Tasks number, plan link, status
Task List: Complete checklist with all metadata
Dependency Graph: Visual dependencies
Parallel Groups: Batch execution opportunities
Traceability Matrix: Task � requirement mapping

Key Principles

Principle 1: Atomic Tasks (5-20 Minutes)

Every task should be completable in one focused session

Too small (< 5 min) = overhead exceeds value
Too large (> 20 min) = becomes vague and risky

Principle 2: TDD Ordering (Red � Green � Refactor)

Tests ALWAYS come before implementation

Write failing tests FIRST (Red)
Implement minimum code to pass (Green)
Refactor while keeping tests green

This is non-negotiable per Test-First Gate

Principle 3: Exact File Paths

Every task must specify exact file paths

Enables quick navigation
Prevents confusion about where code belongs
Aligns with technical design structure

Principle 4: Dependency Clarity

Every task lists prerequisites explicitly

Sequential dependencies must be clear
Parallel opportunities marked with [P]
No hidden dependencies

Principle 5: Traceability to Requirements

Every task maps back to requirements

Ensures complete coverage
Enables impact analysis
Supports validation phase

Common Pitfalls

L Don't:

Create vague tasks - "Implement user stuff" (What stuff? Where?)
Skip exact file paths - Makes tasks ambiguous
Forget dependencies - Tasks run in wrong order
Miss parallel opportunities - Slows execution unnecessarily
Skip test tasks - Violates TDD/Test-First Gate
Make tasks too large - > 20 min tasks are risky
Forget traceability - Can't validate requirements coverage

Do:

Make tasks atomic (5-20 min) - "Create User entity in src/domain/entities/user.entity.ts"
Include exact file paths - No ambiguity about location
Map dependencies explicitly - "Depends: T001, T002"
Mark parallel tasks [P] - Maximize concurrent execution
Tests before implementation - Red � Green � Refactor (TDD)
Create traceability matrix - Task � requirement mapping
Organize by phases - Foundation � Story 1 � Story 2 � Final

Task Breakdown Checklist

Use this checklist to validate your task breakdown quality:

Structure

Tasks organized by phases (Foundation � User Stories � Final)
Each phase has clear purpose
Foundation tasks identified (block all stories)
User stories ordered by priority (P1 � P2 � P3)

Task Quality

All tasks are atomic (5-20 min estimate)
All tasks have exact file paths
All tasks list dependencies explicitly
All tasks reference requirements (FR-###, NFR-###)
All tasks reference user stories (US-#)

TDD Ordering

Tests written BEFORE implementation (Red phase)
Implementation follows tests (Green phase)
Refactor phase included (if needed)
Verification checkpoints after each phase

Dependencies

All dependencies documented (Depends: T###)
Parallel tasks marked [P]
Dependency graph created
No circular dependencies

Traceability

Traceability matrix complete
Every requirement has corresponding tasks
Every task maps to requirement
User story coverage verified

Completeness

Foundation tasks cover: structure, DB, DI, error handling, schemas
All user stories have tasks (Red � Green � Refactor)
Final quality gates included
Documents generated (PLAN-### and TASKS-###)

Handoff Pattern

When task breakdown is complete:

Announce:

"Implementation plan and tasks complete:

Plan: docs/plans/PLAN-{###}-{name}.md Tasks: docs/tasks/TASKS-{###}-{name}.md

Task Summary:

{N} total tasks
Foundation: {N} tasks (core infrastructure)
User Story 1 (P1): {N} tasks
User Story 2 (P2): {N} tasks
User Story N (P3): {N} tasks
Final Quality Gates: {N} tasks

Execution Approach:

TDD ordering: Red (tests first) � Green (implement) � Refactor
{N} parallel execution opportunities identified
All tasks 5-20 minutes (atomic)
Complete traceability to requirements

Dependencies:

Foundation blocks all stories
Stories can execute in parallel after foundation
{N} parallel groups identified

Ready to begin implementation using superpowers:executing-plans?"

Wait for user confirmation before proceeding to implementation.

Powered by research from Task-Master, Perplexity MCP, and industry best practices for agile task decomposition

Install Skill

SKILL.md

Task Breakdown

Overview

Quick Reference

Task Granularity: The 5-20 Minute Rule

Why 5-20 Minutes?

Examples

The Process

Phase 1: Read Design Documents

Phase 2: Organize by Implementation Phases

Phase 3: Foundation Tasks (Phase 0)

3.1 Project Structure

3.2 Database Schema & Migrations

3.3 DI Container Setup

3.4 Base Error Handling

3.5 Zod Schema Structure

Phase 4: Per-Story Task Breakdown (TDD Order)

4.1 Tests First (Red Phase)

4.2 Implementation (Green Phase)

4.3 Refactor Phase (Optional)

Phase 5: Task Format & Metadata

Phase 6: Dependency Mapping

Phase 7: Rastreabilidade (Traceability Matrix)

Phase 8: Generate Implementation Plan & Tasks Documents

8.1 Implementation Plan

8.2 Tasks Document

Key Principles

Principle 1: Atomic Tasks (5-20 Minutes)

Principle 2: TDD Ordering (Red � Green � Refactor)

Principle 3: Exact File Paths

Principle 4: Dependency Clarity

Principle 5: Traceability to Requirements

Common Pitfalls

Task Breakdown Checklist

Structure

Task Quality

TDD Ordering

Dependencies

Traceability

Completeness

Handoff Pattern