---

name: arc42-epic-decomposer description: Analyses Arc42 architecture documentation and decomposes it into well-sized Epics suitable for Speckit implementation. Use when breaking down architecture into implementable work, creating epic catalogues from design docs, preparing Arc42 for agile delivery, or when asked to plan epics from architecture.

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:

Copydocs/
├── 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:

CopyArc42 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:

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

See references/dependency-patterns.md for examples.

Phase 6: Generate Outputs

Create files in docs/planning/:

Copydocs/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)

Copy# 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):

Copygit checkout -b epXX-epic-name

Copy/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:

CopyEpic 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