Breakdown - Epic Decomposition

Patterns for breaking down large features into concrete, parallelizable tasks.

Decomposition Patterns

New Feature Pattern

1. Infrastructure
   └── Types, contexts, schemas, state management

2. Core Implementation
   └── Main components, business logic

3. Integration
   └── Connect pieces, wire up routes

4. Polish
   └── Edge cases, error handling, UX improvements

5. Validation
   └── Tests, documentation updates

Example: Dark Mode 1. Infrastructure: Theme context, CSS variables 2. Core: Theme toggle component, styled components 3. Integration: Apply to all pages 4. Polish: System preference detection, smooth transitions 5. Validation: Visual regression tests

Refactor Pattern

1. Create New
   └── Build new pattern alongside old

2. Migrate
   └── Move components one at a time

3. Cleanup
   └── Remove old pattern, dead code

4. Verify
   └── Update tests, ensure no regressions

Example: Move to React Query 1. Create: Set up React Query provider 2. Migrate: Convert hooks one by one 3. Cleanup: Remove old fetch utilities 4. Verify: Update tests for new patterns

Bug Fix Pattern

1. Investigate (if complex)
   └── Reproduce, identify root cause

2. Fix
   └── Implement the solution

3. Verify
   └── Add regression test

Most bugs don't need decomposition - only create subtasks for complex bugs requiring investigation.

Task Sizing

Target: S-M tasks. XS is too granular, L-XL should be broken down.

Dependency Patterns

Sequential (A → B → C)

A: Create database schema
B: Implement API endpoint (blocked by A)
C: Add frontend form (blocked by B)

Fan-out (A → B, C, D in parallel)

A: Create shared context
B: Use in Header (blocked by A)
C: Use in Footer (blocked by A)
D: Use in Sidebar (blocked by A)

Fan-in (B, C, D → E)

B, C, D: Independent features
E: Integration testing (blocked by B, C, D)

File Conflict Sequencing

B: Update styles.css for Header
C: Update styles.css for Footer (blocked by B)

Even though B and C are conceptually parallel, they touch the same file.

Identifying File Overlaps

Common conflict points: - Shared styles (styles.css, theme.ts) - Route configuration (routes.tsx, App.tsx) - State management (store.ts, context.tsx) - Shared types (types.ts, interfaces.ts) - Test utilities (testUtils.ts, fixtures.ts)

When detected: Add dependency between tasks to sequence them.

Wave Planning

Group tasks into waves:

## Wave 1 (Ready Now)
Tasks with no blockers - start immediately

## Wave 2 (After Wave 1)
Tasks blocked by Wave 1 - becomes ready when Wave 1 completes

## Wave 3 (After Wave 2)
Final integration, polish tasks

Max 3-5 tasks per wave for manageability.

Quality Checks

Before finalizing breakdown:

1. Is each task concrete? Should be implementable without further planning
2. Are dependencies correct? No circular deps, no unnecessary sequencing
3. Are file conflicts handled? Same-file tasks sequenced
4. Is it parallelizable? Maximize concurrent work
5. Is it right-sized? No XS or XL tasks

References

• dependencies.md - Dependency patterns
• epics.md - Epic management