arc42-epic-decomposer

Arc42 to Epic Decomposition

Transforms Arc42 architecture documentation into Speckit-ready Epics with proper sizing, dependency management, and traceability.

Project Structure Conventions

This skill expects the following folder structure:

docs/
├── architecture/
│   ├── arc42/          # Arc42 documentation (input)
│   └── adr/            # Architecture Decision Records (input)
├── requirements/       # Personas, use-cases, requirements (input)
├── vision/             # Vision statements, north stars (input)
└── planning/           # Epic catalogue and roadmap (output)
    └── epics/          # Individual epic files

.specify/
└── memory/
    └── constitution.md # Speckit constitution (reference)

Quick Start

1. Read docs/architecture/arc42/ for architecture documentation
2. Check .specify/memory/constitution.md for project principles
3. Run the analysis workflow
4. Generate epic catalogue in docs/planning/epics/

Analysis Workflow

Copy this checklist and track progress:

Arc42 Epic Decomposition Progress:
- [ ] Phase 1: Read all input documentation
- [ ] Phase 2: Extract context and constraints
- [ ] Phase 3: Map building blocks to epic candidates
- [ ] Phase 4: Apply sizing rules and form epics
- [ ] Phase 5: Analyse dependencies and sequence
- [ ] Phase 6: Generate output files in docs/planning/

Phase 1: Read Documentation

Read in this order:

1. Vision (if exists): docs/vision/ — North star, strategic direction
2. Constitution: .specify/memory/constitution.md — Project principles
3. Arc42: docs/architecture/arc42/ — Architecture documentation
4. ADRs: docs/architecture/adr/ — Key decisions and rationale
5. Requirements (if exists): docs/requirements/ — Personas, use-cases

Minimum required: Arc42 sections 1, 3, and 5.

Phase 2: Extract Context

Summarise these elements:

Phase 3: Map Building Blocks

From Arc42 §5 Building Block View:

• List each Level 1 component's name and responsibility
• Note dependencies between components
• Flag shared/foundational components

Cross-reference with:

• Arc42 §6 Runtime View for workflow boundaries
• Arc42 §7 Deployment View for infrastructure needs
• Arc42 §8 Crosscutting Concepts for enabler epics

See references/arc42-mapping.md for detailed mapping guidance.

Phase 4: Form Epics

Apply sizing rules to each candidate:

Classify each epic:

Use template: templates/epic-template.md

Phase 5: Dependency Analysis

Ensure dependency graph has:

• Foundation epics with no blockers
• No circular dependencies
• Soft dependencies use interface contracts
• Clear critical path identified

Apply WSJF prioritisation:

Score = (Business Value + Time Criticality + Risk Reduction) / Size

See references/dependency-patterns.md for examples.

Phase 6: Generate Outputs

Create files in docs/planning/:

docs/planning/
├── epic-catalogue.md      # Summary table and roadmap
├── dependency-graph.mermaid
├── speckit-guide.md       # Workflow for Speckit handoff
└── epics/
    ├── EP01-*.md
    ├── EP02-*.md
    └── ...

Epic Template (Summary)

# EP[XX]: [Epic Name]

## Classification
| Attribute | Value |
|-----------|-------|
| Type | Foundation / Business / Enabler / Integration |
| Priority | P0 / P1 / P2 / P3 |
| Size | S / M / L / XL |
| Duration | X weeks |

## Business Outcome Hypothesis
**If** we deliver [this epic],
**Then** [stakeholder] will be able to [outcome],
**Measured by** [metric].

## Scope
- **In Scope**: [capabilities]
- **Out of Scope**: [exclusions]
- **MVP**: [minimum viable slice]

## Traceability
- **Arc42 Building Blocks**: [from §5]
- **ADRs**: [relevant decision numbers]
- **Quality Requirements**: [from §10]

## Dependencies
| Blocked By | Type | What's Needed |
|------------|------|---------------|
| EPxx | Hard/Soft | Description |

## Acceptance Criteria
- [ ] [testable criterion]

## Speckit Handoff Notes
- Primary persona: [from requirements]
- Key workflow: [main user journey]
- Constraints: [from constitution + ADRs]

Full template: templates/epic-template.md

Speckit Integration

After generating epics, for each epic (in dependency order):

git checkout -b epXX-epic-name

/speckit.specify [Paste epic scope and business outcome from EPxx.md]
/speckit.clarify
/speckit.plan [Include constraints from constitution and ADRs]
/speckit.tasks
/speckit.implement

The constitution at .specify/memory/constitution.md will automatically inform Speckit's decisions.

Validation Checklist

Before finalising:

Epic Quality Check:
- [ ] Every Arc42 building block maps to at least one epic
- [ ] Every external interface (§3) has an integration epic
- [ ] Crosscutting concerns (§8) have enabler epics
- [ ] No epic exceeds 8 weeks duration
- [ ] No circular dependencies exist
- [ ] Each epic has defined MVP
- [ ] Acceptance criteria are testable
- [ ] ADR constraints reflected in relevant epics
- [ ] Constitution principles respected

References

• Arc42 Section Mapping — Which sections inform which epic types
• Dependency Patterns — Good and bad dependency examples
• Sizing Guidelines — When to split or merge epics
• Epic Template — Full template with all fields
• Catalogue Template — Epic catalogue structure
• Speckit Guide Template — Per-epic Speckit workflow