Task Breakdown

Transform ARCHITECTURE.md and FUNCTIONAL_SPEC.md artifacts into a comprehensive TASKS.md artifact containing epics, granular tasks with effort estimates, a dependency graph, and implementation ordering. This is the fifth step in the greenfield specification pipeline — it takes a system design and produces a concrete work plan that developers can execute.

When to Use This Skill

• ARCHITECTURE.md and FUNCTIONAL_SPEC.md exist and have been validated
• The team needs a backlog of actionable work items
• Sprint planning requires effort estimates and dependency awareness
• Development sequencing needs to be determined
• Stakeholders need visibility into the volume and complexity of work

Pipeline Position

[Raw Idea] → [PROBLEM_BRIEF.md] → [REQUIREMENTS.md] → [FUNCTIONAL_SPEC.md] → [ARCHITECTURE.md] → **TASK BREAKDOWN** → [TASKS.md] → Implementation Planning

Input: artifacts/greenfield/<project_name>/ARCHITECTURE.md, artifacts/greenfield/<project_name>/FUNCTIONAL_SPEC.md Output: artifacts/greenfield/<project_name>/TASKS.md

Process

Step 1: Read and Analyze Inputs

Load ARCHITECTURE.md and FUNCTIONAL_SPEC.md. Extract:

From ARCHITECTURE.md:

• Components (COMP-NNNN) — each component generates at least one epic
• Interfaces — each interface generates integration tasks
• Technology stack — informs task complexity and tooling tasks
• Deployment architecture — generates infrastructure tasks
• Security architecture — generates security-specific tasks

From FUNCTIONAL_SPEC.md:

• Feature specs (FS-NNNN) — each feature generates implementation tasks
• Business rules (BR-NNNN) — each rule generates validation/logic tasks
• Edge cases (EC-NNNN) — each edge case generates handling tasks
• API contracts (API-NNNN) — each endpoint generates API tasks
• Data models — generate database/schema tasks

Step 2: Define Epics

Create epics (EPIC-NNNN) by grouping related work around architecture components:

Epic format:

EPIC-NNNN: [Epic Name]
Component: COMP-NNNN
Features: FS-NNNN, FS-NNNN
Description: [What this epic delivers when complete]
Priority: P0 | P1 | P2
Estimated Total Effort: [Sum of task estimates]

Rules for epics:

• Every architecture component (COMP-NNNN) maps to at least one epic
• Every feature spec (FS-NNNN) maps to at least one epic
• Epics should be completable in 1-3 sprints (2-6 weeks)
• If an epic exceeds 3 sprints of work, split it into sub-epics
• Epic priority is inherited from the highest-priority FS it implements

Standard epic types:

Epic Type	Description	Typical Tasks
Foundation	Core infrastructure setup	Project scaffolding, CI/CD, database setup
Feature	End-to-end feature implementation	API, business logic, UI, tests
Integration	Connecting components or external services	API clients, adapters, webhooks
Security	Authentication, authorization, data protection	Auth setup, role system, encryption
Quality	Testing, monitoring, observability	Test suites, logging, alerting
Deployment	Infrastructure and release pipeline	Containerization, orchestration, rollback

Step 3: Break Epics into Tasks

For each epic, create granular tasks (TASK-NNNN):

Task format:

TASK-NNNN: [Task Title]
Epic: EPIC-NNNN
Type: [Feature | Bug | Chore | Spike | Test]
Description: [Specific, actionable description of what to do]
Implements: [FS-NNNN, BR-NNNN, EC-NNNN, API-NNNN, or COMP-NNNN reference]
Dependencies: [TASK-NNNN list, or "None"]
Effort: [T-shirt size]
Acceptance Criteria:
  - [Criterion 1]
  - [Criterion 2]

T-shirt size definitions:

Size	Time Estimate	Complexity	Examples
XS	< 2 hours	Trivial change, no unknowns	Config change, copy update, add field
S	2-4 hours	Straightforward, well-understood	CRUD endpoint, simple UI component
M	4-8 hours (1 day)	Moderate complexity, some decisions	Business logic module, complex query
L	1-2 days	Significant complexity, integration needed	Full feature flow, external API integration
XL	2-5 days	High complexity, research/spike needed	Architecture component, complex algorithm

Rules for tasks:

• Every task must be completable by a single developer
• XL tasks should be considered for splitting (if possible)
• Every task must have at least one acceptance criterion
• Every task must map to an epic
• Every task must reference what it implements (FS, BR, EC, API, or COMP)
• Task descriptions must be actionable ("Implement X" not "Consider Y")

Task decomposition patterns:

For a typical feature (FS-NNNN), create tasks in this order:

1. Data model task: Create/modify database schema for the feature's entities
2. Business logic task: Implement business rules (BR-NNNN) as service-layer functions
3. API task: Implement API endpoints (API-NNNN) with request/response handling
4. Validation task: Implement input validation and edge case handling (EC-NNNN)
5. Integration task: Wire components together, implement interface contracts
6. Test task: Write unit tests, integration tests for the feature
7. Documentation task: Update API docs, add inline documentation

Step 4: Map Dependencies

Create a dependency graph ensuring:

• All dependencies form a valid DAG (Directed Acyclic Graph)
• No circular dependencies exist
• Foundation tasks come before feature tasks
• Data model tasks come before business logic tasks
• Business logic tasks come before API tasks
• Test tasks depend on the implementation tasks they test

Dependency types:

Type	Meaning	Example
Hard	Cannot start until dependency is complete	API task depends on data model task
Soft	Can start in parallel but needs dependency for testing	UI task can start before API is done (mock data)

Validation rules:

1. Walk the graph from every leaf node to a root — if you visit the same node twice, there is a cycle
2. Every task with no dependencies is a "root task" — these can start immediately
3. The longest path through the graph is the critical path

Step 5: Estimate Effort

For each task, assign a T-shirt size based on:

Estimation factors:

1. Complexity: How many decisions/unknowns are involved?
2. Scope: How many files/components are touched?
3. Risk: How likely is the estimate to be wrong?
4. Dependencies: How much coordination is needed?
5. Testing: How much test coverage is required?

Estimation rules:

• When in doubt, size up (M instead of S)
• Tasks with external API dependencies: add one size for integration risk
• First task in a new component: add one size for setup overhead
• Tasks requiring research/spike: minimum L
• Round up, never down

Effort aggregation:

XS = 1 point, S = 2 points, M = 4 points, L = 8 points, XL = 16 points
Epic effort = sum of task points
Total project effort = sum of epic points

Step 6: Validate Task Completeness

Before writing the artifact, validate:

1. Every FS-NNNN has at least one implementing task
2. Every BR-NNNN has an implementing task
3. Every EC-NNNN has a handling task
4. Every API-NNNN has an implementation task
5. Every COMP-NNNN has setup/infrastructure tasks
6. Test tasks exist for all P0 features
7. Dependency graph is a valid DAG
8. No orphan tasks (every task belongs to an epic)
9. No orphan epics (every epic has at least one task)

Output Format

Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/TASKS.template.md.

The artifact must follow the standard artifact template structure:

# TASKS: [Project Name]

## Summary
[2-3 sentence summary: epic count, task count, total effort points, critical path length]

## Inputs
- **Architecture**: `ARCHITECTURE.md` — [COMP-NNNN count, interfaces referenced]
- **Functional Spec**: `FUNCTIONAL_SPEC.md` — [FS-NNNN, BR-NNNN, EC-NNNN, API-NNNN counts]

## Outputs
- This document (TASKS.md)
- Feeds into: IMPLEMENTATION_PLAN.md (via implementation-planning skill)

## Assumptions
- [ASM-0001]: [Task-specific assumption — e.g., "Team velocity: 40 points per sprint"]
- ...

## Open Questions
- [OQ-0001]: [Question affecting task scope — e.g., "Third-party API documentation availability?"]
- ...

## Main Content

### Effort Summary

| Metric | Value |
|--------|-------|
| Total Epics | [N] |
| Total Tasks | [N] |
| Total Effort Points | [N] |
| Critical Path Length | [N] tasks, [N] points |
| Estimated Duration | [N] sprints (at [N] points/sprint velocity) |

### Epic Breakdown

| Priority | Epics | Tasks | Points | % of Total |
|----------|-------|-------|--------|------------|
| P0 | [N] | [N] | [N] | [N]% |
| P1 | [N] | [N] | [N] | [N]% |
| P2 | [N] | [N] | [N] | [N]% |
| **Total** | **[N]** | **[N]** | **[N]** | **100%** |

### Epic List

#### EPIC-0001: [Epic Name]
- **Component**: COMP-0001
- **Features**: FS-0001, FS-0002
- **Priority**: P0
- **Total Effort**: [N] points ([N] tasks)
- **Description**: [What this epic delivers]

#### EPIC-0002: [Epic Name]
- **Component**: COMP-0002
- **Features**: FS-0003
- **Priority**: P0
- **Total Effort**: [N] points ([N] tasks)
- **Description**: [What this epic delivers]

[... additional epics ...]

### Task List

#### EPIC-0001: [Epic Name]

**TASK-0001: [Task Title]**
- **Epic**: EPIC-0001
- **Type**: Chore
- **Description**: [Actionable description]
- **Implements**: COMP-0001
- **Dependencies**: None
- **Effort**: M (4 points)
- **Acceptance Criteria**:
  - [Criterion 1]
  - [Criterion 2]

**TASK-0002: [Task Title]**
- **Epic**: EPIC-0001
- **Type**: Feature
- **Description**: [Actionable description]
- **Implements**: FS-0001, BR-0001
- **Dependencies**: TASK-0001
- **Effort**: L (8 points)
- **Acceptance Criteria**:
  - [Criterion 1]
  - [Criterion 2]
  - [Criterion 3]

**TASK-0003: [Task Title]**
- **Epic**: EPIC-0001
- **Type**: Feature
- **Description**: [Actionable description]
- **Implements**: API-0001
- **Dependencies**: TASK-0002
- **Effort**: S (2 points)
- **Acceptance Criteria**:
  - [Criterion 1]
  - [Criterion 2]

**TASK-0004: [Task Title]**
- **Epic**: EPIC-0001
- **Type**: Test
- **Description**: [Actionable description]
- **Implements**: FS-0001
- **Dependencies**: TASK-0002, TASK-0003
- **Effort**: M (4 points)
- **Acceptance Criteria**:
  - [Criterion 1]
  - [Criterion 2]

[... additional tasks for EPIC-0001 ...]

#### EPIC-0002: [Epic Name]

[... tasks for EPIC-0002 ...]

### Dependencies Graph

```mermaid
graph LR
    TASK-0001 --> TASK-0002
    TASK-0002 --> TASK-0003
    TASK-0002 --> TASK-0005
    TASK-0003 --> TASK-0004
    TASK-0005 --> TASK-0006

    style TASK-0001 fill:#e1f5fe
    style TASK-0002 fill:#e1f5fe
    style TASK-0003 fill:#e1f5fe
    style TASK-0004 fill:#e1f5fe

Legend:

• Blue nodes: Critical path tasks
• Arrows: Hard dependencies (must complete before dependent starts)

Critical Path

The critical path is the longest chain of dependent tasks that determines minimum project duration:

TASK-0001 (M:4) → TASK-0002 (L:8) → TASK-0003 (S:2) → TASK-0004 (M:4)
Total: 18 points

Critical path tasks must be prioritized in sprint planning. Any delay on the critical path delays the entire project.

Effort Estimates by Category

Task Type	Count	Points	% of Total
Feature	[N]	[N]	[N]%
Chore	[N]	[N]	[N]%
Test	[N]	[N]	[N]%
Spike	[N]	[N]	[N]%
Bug	[N]	[N]	[N]%
Total	[N]	[N]	100%

Parallelization Opportunities

[Identify tasks that can be worked on simultaneously by different developers]

Parallel Track A	Parallel Track B	Sync Point
TASK-0001, TASK-0002	TASK-0005, TASK-0006	TASK-0007 (depends on both tracks)

Acceptance Criteria

• Every FS-NNNN has at least one implementing task
• Every BR-NNNN has an implementing task
• Every EC-NNNN has a handling task
• Every API-NNNN has an implementation task
• Every COMP-NNNN has setup tasks
• Every task belongs to an epic
• Every epic has at least one task
• Dependencies form a valid DAG (no cycles)
• Critical path is identified and documented
• All tasks have effort estimates (T-shirt sizes)
• Test tasks exist for all P0 features
• All IDs are sequential and sorted appropriately
• Parallelization opportunities are identified

**Output path**: `artifacts/greenfield/<project_name>/TASKS.md`

## Determinism Rules

1. EPIC-NNNN IDs: Sort alphabetically by epic name, assign sequential 4-digit numbers starting from 0001
2. TASK-NNNN IDs: Sort by parent EPIC-NNNN first, then by dependency order within each epic (tasks with no dependencies first, then tasks that depend on earlier tasks), then alphabetically by task title for tasks at the same dependency level. Assign sequential 4-digit numbers starting from 0001 globally (not per-epic).
3. ASM-NNNN IDs: Sort alphabetically by assumption text, assign sequential numbers
4. OQ-NNNN IDs: Sort alphabetically by question text, assign sequential numbers
5. Epics listed by EPIC-NNNN order
6. Tasks listed within their parent epic section
7. No timestamps in artifact body
8. Sections must appear in template order
9. Effort summary tables appear before detailed listings

## Task Sizing Guidelines

### XS Tasks (< 2 hours)
- Update a configuration file
- Add a new field to an existing data model
- Fix a typo or copy change
- Add an environment variable
- Update a dependency version

### S Tasks (2-4 hours)
- Implement a single CRUD endpoint
- Create a simple UI component
- Write unit tests for one module
- Add input validation for one form
- Create a database migration script

### M Tasks (4-8 hours)
- Implement business logic for one feature
- Create an API endpoint with validation and error handling
- Build a complex UI component with state management
- Write integration tests for one feature
- Set up a third-party service integration

### L Tasks (1-2 days)
- Implement a complete feature end-to-end (API + logic + UI)
- Set up authentication/authorization system
- Build a data pipeline or ETL process
- Create a monitoring and alerting setup
- Implement a complex algorithm or optimization

### XL Tasks (2-5 days)
- Set up project infrastructure from scratch
- Implement a real-time communication system
- Build a complex search or recommendation engine
- Create a comprehensive test suite for a major component
- Design and implement a data migration strategy

**If a task is larger than XL (>5 days), it MUST be split into smaller tasks.**

## Quality Checklist

Before completing, verify:
- [ ] Every architecture component has at least one epic
- [ ] Every feature spec has implementing tasks
- [ ] Every business rule has an implementation task
- [ ] Every edge case has a handling task
- [ ] Every API contract has an implementation task
- [ ] Test tasks exist for all P0 feature implementations
- [ ] Dependencies form a valid DAG (no cycles)
- [ ] Critical path is identified and documented
- [ ] No task is larger than XL
- [ ] Every task has specific, testable acceptance criteria
- [ ] Effort estimates are consistent (similar tasks have similar sizes)
- [ ] Parallelization opportunities are documented
- [ ] Total effort is reasonable for the project scope
- [ ] All IDs are sequential and deterministically ordered
- [ ] Artifact follows the standard template structure

## Common Pitfalls

1. **Tasks too large**: "Implement the backend" is not a task. Tasks must be completable by one developer in 5 days or less.
2. **Missing test tasks**: Every feature implementation task should have a corresponding test task. Testing is not optional.
3. **Circular dependencies**: TASK-A depends on TASK-B which depends on TASK-A. Resolve by identifying which truly needs to be done first, or extract the shared dependency into a separate task.
4. **Over-optimistic estimates**: The most common estimation error is underestimation. When unsure, size up.
5. **Ignoring infrastructure tasks**: Project setup, CI/CD, monitoring, and deployment are real work that needs to be estimated and scheduled.
6. **No critical path awareness**: Without identifying the critical path, sprint planning cannot optimize for delivery speed.
7. **Orphan tasks**: Every task must belong to an epic and trace back to a feature spec or component. Tasks without traceability indicate scope creep.
8. **All tasks are "Feature" type**: A healthy task list includes Feature, Chore, Test, and Spike types. If everything is a Feature, you are likely missing infrastructure and testing work.