Obsidian-Owl avatar

arc42-epic-decomposer

Analyses Arc42 architecture documentation and decomposes it into well-sized Epics suitable for Speck

by Obsidian-Owl|Open Source

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:

ExtractSourcePurpose
Strategic directiondocs/vision/Epic prioritisation
Project principles.specify/memory/constitution.mdConstraints on approach
Business driversArc42 §1Epic acceptance criteria
System boundariesArc42 §3Integration epic identification
Technical constraintsArc42 §2 + ADRsEpic technical requirements
Quality attributesArc42 §10Non-functional requirements

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:

DimensionTargetIf Violated
Duration4-8 weeksSplit if >8 weeks, merge if <2 weeks
User stories5-12 expectedDecompose if >15, expand if <3
MVPDefinedMust identify minimum viable slice
IndependenceTestable aloneExtract shared work to foundation

Classify each epic:

TypeDescriptionExamples
FoundationEnables other workCI/CD, dev environment, auth, shared libs
BusinessDelivers user valueFeatures, domain modules, bounded contexts
EnablerTechnical excellenceLogging, monitoring, security, tech debt
IntegrationConnects systemsExternal APIs, data sync, migrations

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

Download Skill