Decomposition Planning Roadmap

Decomposition Planning and Roadmap

This skill creates structured decomposition plans and roadmaps to guide the migration from monolithic to distributed architectures, prioritizing work and tracking progress through decomposition patterns.

How to Use

Quick Start

Request creation of a decomposition plan:

• "Create a decomposition roadmap for this codebase"
• "Plan the decomposition migration strategy"
• "Prioritize decomposition work based on component analysis"
• "Create a step-by-step decomposition plan"

Usage Examples

Example 1: Complete Roadmap

User: "Create a decomposition roadmap for this codebase"

The skill will:
1. Analyze current codebase state
2. Identify decomposition patterns to apply
3. Prioritize work based on risk and value
4. Create phased roadmap
5. Generate architecture stories
6. Estimate effort and dependencies

Example 2: Prioritized Plan

User: "Prioritize decomposition work based on component analysis"

The skill will:
1. Review component inventory and dependencies
2. Assess risk and value for each pattern
3. Prioritize patterns by impact
4. Create prioritized work plan

Example 3: Phase Planning

User: "Create a phased decomposition plan"

The skill will:
1. Group decomposition patterns into phases
2. Identify dependencies between phases
3. Create phase timeline
4. Define phase success criteria

Step-by-Step Process

1. Assess Current State: Analyze codebase and identify what's been done 2. Identify Patterns: Determine which decomposition patterns to apply 3. Prioritize Work: Rank patterns by risk, value, and dependencies 4. Create Roadmap: Build phased plan with milestones 5. Generate Stories: Create architecture stories for tracking 6. Track Progress: Monitor progress through decomposition phases

When to Use

Apply this skill when:

• Starting a decomposition effort
• Planning migration from monolith to distributed architecture
• Prioritizing decomposition work
• Creating architecture stories for decomposition
• Tracking progress through decomposition patterns
• Need structured approach to decomposition
• Want to estimate effort and dependencies

Core Concepts

Decomposition Pattern Sequence

The six component-based decomposition patterns should be applied in sequence:

1. Identify and Size Components - Understand what you have 2. Gather Common Domain Components - Find duplicates 3. Flatten Components - Remove orphaned classes 4. Determine Component Dependencies - Assess coupling 5. Create Component Domains - Group into domains 6. Create Domain Services - Extract to services

Phased Approach

Decomposition typically follows phases:

Phase 1: Analysis & Preparation (Patterns 1-4)

• Component identification and sizing
• Common component detection
• Component flattening
• Dependency analysis

Phase 2: Domain Organization (Pattern 5)

• Domain identification
• Component grouping
• Namespace refactoring

Phase 3: Service Extraction (Pattern 6)

• Domain service creation
• Service extraction
• API boundary definition

Prioritization Factors

When prioritizing decomposition work, consider:

• Risk: Low risk = easier to extract, fewer dependencies
• Value: High value = business-critical, high impact
• Dependencies: Can this be done independently?
• Complexity: Simple = fewer components, clear boundaries
• Coupling: Low coupling = easier to extract

Analysis Process

Phase 1: Assess Current State

Analyze what's already been done:

1. Check Component Inventory

• Have components been identified and sized?
• Is there a component inventory document?
• Are oversized components identified?

2. Check Common Component Analysis

• Have common domain components been identified?
• Are consolidation opportunities documented?
• Has coupling impact been analyzed?

3. Check Component Structure

• Have components been flattened?
• Are there orphaned classes?
• Is component structure clean?

4. Check Dependency Analysis

• Have component dependencies been mapped?
• Is coupling analysis complete?
• Is feasibility assessed?

5. Check Domain Identification

• Have domains been identified?
• Are components grouped into domains?
• Are namespaces aligned with domains?

6. Check Service Extraction

• Have any services been extracted?
• Are domain services created?
• Is service-based architecture in place?

Output: Current state assessment showing what's done and what's remaining

Phase 2: Identify Patterns to Apply

Determine which decomposition patterns need to be applied:

1. Review Pattern Prerequisites

• Pattern 1: Always needed (foundation)
• Pattern 2: Needed if common components exist
• Pattern 3: Needed if components have hierarchy
• Pattern 4: Always needed (feasibility check)
• Pattern 5: Needed before service extraction
• Pattern 6: Final step (service extraction)

2. Check Pattern Completion

• Which patterns are complete?
• Which patterns are in progress?
• Which patterns haven't started?

3. Identify Missing Patterns

• What patterns still need to be applied?
• What's blocking pattern application?
• What dependencies exist?

Output: List of patterns to apply with status

Phase 3: Prioritize Work

Prioritize decomposition patterns and work items:

1. Assess Risk

• Low Risk: Infrastructure components, standalone functionality
• Medium Risk: Domain components with some dependencies
• High Risk: Core business logic, high coupling

2. Assess Value

• High Value: Business-critical, high impact, frequent changes
• Medium Value: Important but not critical
• Low Value: Nice to have, low impact

3. Assess Dependencies

• Independent: Can be done without other work
• Dependent: Requires other patterns/work first
• Blocking: Blocks other work from proceeding

4. Calculate Priority Score

   Priority = (Value × 3) - (Risk × 2) - (Dependencies × 1)

   Higher score = Higher priority

Output: Prioritized list of patterns and work items

Phase 4: Create Phased Roadmap

Build a phased roadmap with milestones:

1. Define Phases

• Phase 1: Analysis & Preparation
• Phase 2: Domain Organization
• Phase 3: Service Extraction
• Phase 4: Optimization & Refinement

2. Assign Patterns to Phases

• Which patterns belong in which phase?
• What's the sequence within each phase?
• What are the phase dependencies?

3. Set Milestones

• What marks completion of each phase?
• What are the success criteria?
• What deliverables are expected?

4. Estimate Timeline

• How long will each phase take?
• What are the dependencies?
• What's the critical path?

Output: Phased roadmap with timeline and milestones

Phase 5: Generate Architecture Stories

Create architecture stories for tracking work:

1. Create Story Template

   As an architect, I need to [apply pattern/refactor component]
   to support [architectural characteristic/business need]
   so that [benefit/outcome]

2. Break Down Work

• One story per pattern application
• One story per major refactoring
• One story per domain grouping

3. Add Acceptance Criteria

• What defines "done"?
• What metrics validate success?
• What tests verify completion?

4. Estimate Effort

• Story points or time estimates
• Complexity assessment
• Risk factors

Output: List of architecture stories with estimates

Phase 6: Track Progress

Monitor progress through decomposition:

1. Track Pattern Completion

• Which patterns are complete?
• Which are in progress?
• Which are blocked?

2. Track Story Completion

• Stories completed
• Stories in progress
• Stories not started

3. Track Metrics

• Components identified
• Components refactored
• Domains created
• Services extracted

4. Identify Blockers

• What's blocking progress?
• What dependencies are missing?
• What risks have emerged?

Output: Progress dashboard and status report

Output Format

Decomposition Roadmap

# Decomposition Roadmap

## Current State Assessment

**Completed Patterns**:

- ✅ Pattern 1: Identify and Size Components
- ✅ Pattern 2: Gather Common Domain Components
- ⚠️ Pattern 3: Flatten Components (in progress)
- ❌ Pattern 4: Determine Component Dependencies (not started)
- ❌ Pattern 5: Create Component Domains (not started)
- ❌ Pattern 6: Create Domain Services (not started)

**Key Findings**:

- 75 components identified
- 3 common domain components found
- 2 oversized components need splitting
- High database coupling detected

## Phased Roadmap

### Phase 1: Analysis & Preparation (Weeks 1-4)

**Goal**: Complete component analysis and refactoring

**Patterns**:

1. Complete Pattern 3: Flatten Components
2. Apply Pattern 4: Determine Component Dependencies
3. Refactor oversized components

**Milestones**:

- Week 2: Component flattening complete
- Week 4: Dependency analysis complete

**Deliverables**:

- Flattened component structure
- Dependency diagram
- Feasibility assessment

### Phase 2: Domain Organization (Weeks 5-8)

**Goal**: Organize components into domains

**Patterns**:

1. Apply Pattern 5: Create Component Domains
2. Refactor namespaces for domain alignment

**Milestones**:

- Week 6: Domains identified
- Week 8: Namespace refactoring complete

**Deliverables**:

- Domain map
- Refactored component namespaces
- Domain documentation

### Phase 3: Service Extraction (Weeks 9-16)

**Goal**: Extract domains to domain services

**Patterns**:

1. Apply Pattern 6: Create Domain Services
2. Extract services incrementally

**Milestones**:

- Week 12: First domain service extracted
- Week 16: All domain services extracted

**Deliverables**:

- Domain services deployed
- API boundaries defined
- Service documentation

Prioritized Work Plan

## Prioritized Work Plan

### High Priority (Do First)

1. **Complete Component Flattening** (Priority: 9/10)
   - Risk: Low
   - Value: High (enables domain grouping)
   - Dependencies: None
   - Effort: 2 weeks

2. **Dependency Analysis** (Priority: 8/10)
   - Risk: Low
   - Value: High (validates feasibility)
   - Dependencies: Component flattening
   - Effort: 1 week

### Medium Priority (Do Next)

3. **Domain Identification** (Priority: 7/10)
   - Risk: Medium
   - Value: High (enables service extraction)
   - Dependencies: Dependency analysis
   - Effort: 2 weeks

### Low Priority (Do Later)

4. **Service Extraction** (Priority: 5/10)
   - Risk: High
   - Value: High (final goal)
   - Dependencies: Domain identification
   - Effort: 8 weeks

Architecture Stories

## Architecture Stories

### Story 1: Flatten Ticket Components

**As an architect**, I need to flatten the Ticket component hierarchy
to support better component organization
so that components exist only as leaf nodes.

**Acceptance Criteria**:

- [ ] No orphaned classes in root namespaces
- [ ] All components are leaf nodes
- [ ] Component structure validated

**Estimate**: 5 story points
**Priority**: High
**Dependencies**: None

### Story 2: Identify Component Domains

**As an architect**, I need to group components into logical domains
to support service-based architecture
so that components can be extracted to domain services.

**Acceptance Criteria**:

- [ ] All components assigned to domains
- [ ] Domain boundaries validated with stakeholders
- [ ] Domain map created

**Estimate**: 8 story points
**Priority**: High
**Dependencies**: Component flattening complete

Progress Dashboard

## Decomposition Progress Dashboard

### Pattern Completion Status

| Pattern                    | Status         | Progress | Blocker                 |
| -------------------------- | -------------- | -------- | ----------------------- |
| Identify & Size Components | ✅ Complete    | 100%     | None                    |
| Gather Common Components   | ✅ Complete    | 100%     | None                    |
| Flatten Components         | ⚠️ In Progress | 60%      | None                    |
| Determine Dependencies     | ❌ Not Started | 0%       | Waiting on flattening   |
| Create Domains             | ❌ Not Started | 0%       | Waiting on dependencies |
| Create Domain Services     | ❌ Not Started | 0%       | Waiting on domains      |

### Story Completion Status

**Completed**: 5 stories (25%)
**In Progress**: 3 stories (15%)
**Not Started**: 12 stories (60%)

### Key Metrics

- Components Identified: 75
- Components Refactored: 45 (60%)
- Domains Created: 0
- Services Extracted: 0

Analysis Checklist

Current State Assessment:

• [ ] Reviewed component inventory
• [ ] Checked common component analysis
• [ ] Assessed component structure
• [ ] Reviewed dependency analysis
• [ ] Checked domain identification
• [ ] Assessed service extraction status

Pattern Identification:

• [ ] Identified which patterns are complete
• [ ] Identified which patterns are in progress
• [ ] Identified which patterns need to be applied
• [ ] Checked pattern dependencies

Prioritization:

• [ ] Assessed risk for each pattern
• [ ] Assessed value for each pattern
• [ ] Assessed dependencies
• [ ] Calculated priority scores

Roadmap Creation:

• [ ] Defined phases
• [ ] Assigned patterns to phases
• [ ] Set milestones
• [ ] Estimated timeline

Story Generation:

• [ ] Created architecture stories
• [ ] Added acceptance criteria
• [ ] Estimated effort
• [ ] Prioritized stories

Progress Tracking:

• [ ] Set up tracking mechanism
• [ ] Defined metrics
• [ ] Created dashboard
• [ ] Identified blockers

Implementation Notes

Roadmap Templates

Simple Roadmap (for small projects):

• Phase 1: Analysis (2-4 weeks)
• Phase 2: Refactoring (4-6 weeks)
• Phase 3: Extraction (8-12 weeks)

Detailed Roadmap (for large projects):

• Phase 1: Analysis & Preparation (4-8 weeks)
• Phase 2: Domain Organization (4-6 weeks)
• Phase 3: Service Extraction (12-16 weeks)
• Phase 4: Optimization (4-8 weeks)

Prioritization Matrix

Use a 2x2 matrix for prioritization:

High Value, Low Risk    | High Value, High Risk
(Do First)              | (Do Carefully)
────────────────────────┼──────────────────────
Low Value, Low Risk     | Low Value, High Risk
(Do Later)              | (Avoid/Defer)

Story Estimation

Use story points or time estimates:

Story Points (Fibonacci):

• 1: Trivial (few hours)
• 2: Simple (1 day)
• 3: Small (2-3 days)
• 5: Medium (1 week)
• 8: Large (2 weeks)
• 13: Very Large (3+ weeks)

Time Estimates:

• Small: 1-3 days
• Medium: 1-2 weeks
• Large: 2-4 weeks
• Very Large: 1+ month

Best Practices

Do's ✅

• Start with analysis patterns (Patterns 1-4)
• Prioritize low-risk, high-value work
• Create architecture stories for tracking
• Set clear milestones and success criteria
• Track progress regularly
• Adjust roadmap based on learnings
• Collaborate with stakeholders on priorities

Don'ts ❌

• Don't skip analysis patterns
• Don't start service extraction too early
• Don't ignore dependencies between patterns
• Don't create unrealistic timelines
• Don't skip progress tracking
• Don't forget to validate with stakeholders
• Don't proceed without feasibility assessment

Integration with Other Skills

This skill coordinates the use of other decomposition skills:

1. Component Identification & Sizing → Foundation for planning 2. Common Domain Component Detection → Identifies consolidation work 3. Component Flattening → Prepares for domain grouping 4. Component Dependency Analysis → Validates feasibility 5. Domain Identification & Grouping → Enables service extraction 6. Decomposition Planning & Roadmap (this skill) → Coordinates everything

Next Steps

After creating the roadmap:

1. Review with Stakeholders - Get buy-in on plan 2. Start Phase 1 - Begin with analysis patterns 3. Track Progress - Monitor completion and blockers 4. Adjust as Needed - Update roadmap based on learnings 5. Celebrate Milestones - Recognize progress

Notes

• Roadmaps should be living documents, updated regularly
• Prioritization may change as you learn more
• Dependencies between patterns must be respected
• Feasibility assessment is critical before proceeding
• Stakeholder collaboration is essential for success
• Progress tracking helps identify issues early

Decomposition Planning & Roadmap - Quick Reference

Pattern Sequence

1. Identify & Size Components      → Foundation
2. Gather Common Components        → Find duplicates
3. Flatten Components              → Clean structure
4. Determine Dependencies          → Assess feasibility
5. Create Component Domains        → Group components
6. Create Domain Services          → Extract services

Phased Approach

Phase 1: Analysis & Preparation

• Pattern 1: Identify & Size Components
• Pattern 2: Gather Common Components
• Pattern 3: Flatten Components
• Pattern 4: Determine Dependencies

Phase 2: Domain Organization

• Pattern 5: Create Component Domains

Phase 3: Service Extraction

• Pattern 6: Create Domain Services

Prioritization Formula

Priority = (Value × 3) - (Risk × 2) - (Dependencies × 1)

Higher score = Higher priority

Risk Levels

• Low: Infrastructure, standalone
• Medium: Domain components, some dependencies
• High: Core business logic, high coupling

Value Levels

• High: Business-critical, high impact
• Medium: Important but not critical
• Low: Nice to have, low impact

Prioritization Matrix

High Value, Low Risk    | High Value, High Risk
(Do First)              | (Do Carefully)
────────────────────────┼──────────────────────
Low Value, Low Risk     | Low Value, High Risk
(Do Later)              | (Avoid/Defer)

Roadmap Templates

Small Project (3-6 months)

• Phase 1: Analysis (1 month)
• Phase 2: Refactoring (2 months)
• Phase 3: Extraction (2-3 months)

Medium Project (6-12 months)

• Phase 1: Analysis & Preparation (2 months)
• Phase 2: Domain Organization (2 months)
• Phase 3: Service Extraction (4-6 months)
• Phase 4: Optimization (2 months)

Large Project (12+ months)

• Phase 1: Analysis & Preparation (3-4 months)
• Phase 2: Domain Organization (3-4 months)
• Phase 3: Service Extraction (6-8 months)
• Phase 4: Optimization (2-3 months)

Architecture Story Template

As an architect, I need to [apply pattern/refactor component]
to support [architectural characteristic/business need]
so that [benefit/outcome]

Acceptance Criteria:
- [ ] Criterion 1
- [ ] Criterion 2

Estimate: X story points
Priority: High/Medium/Low
Dependencies: [List]

Story Point Estimation

Progress Tracking Checklist

Pattern Status

• [ ] Pattern 1: Complete / In Progress / Not Started
• [ ] Pattern 2: Complete / In Progress / Not Started
• [ ] Pattern 3: Complete / In Progress / Not Started
• [ ] Pattern 4: Complete / In Progress / Not Started
• [ ] Pattern 5: Complete / In Progress / Not Started
• [ ] Pattern 6: Complete / In Progress / Not Started

Key Metrics

• Components Identified: X
• Components Refactored: X (Y%)
• Domains Created: X
• Services Extracted: X

Blockers

• [ ] List blockers
• [ ] Identify dependencies
• [ ] Plan mitigation

Quick Analysis Steps

1. Assess → Check current state 2. Identify → Find patterns to apply 3. Prioritize → Rank by risk/value 4. Plan → Create phased roadmap 5. Track → Monitor progress

Output Template

# Decomposition Roadmap

## Current State Assessment

- ✅ [Completed patterns]
- ⚠️ [In progress patterns]
- ❌ [Not started patterns]

## Phased Roadmap

### Phase 1: [Name] (Timeline)

- [Patterns/work items]
- Milestones: [List]
- Deliverables: [List]

### Phase 2: [Name] (Timeline)

[Similar format]

## Prioritized Work Plan

### High Priority

1. [Work item] (Priority: X/10)
   - Risk: Low/Medium/High
   - Value: High/Medium/Low
   - Effort: X weeks

## Architecture Stories

[Story list]

## Progress Dashboard

[Status tables and metrics]

Decomposition Planning and Roadmap Skill

A skill for creating structured decomposition plans and roadmaps to guide the migration from monolithic to distributed architectures.

What This Skill Does

This skill analyzes codebases and decomposition progress to:

1. Assess current state of decomposition efforts 2. Identify patterns to apply based on what's been done 3. Prioritize work by risk, value, and dependencies 4. Create phased roadmaps with milestones and timelines 5. Generate architecture stories for tracking work 6. Track progress through decomposition phases 7. Identify blockers and dependencies

When to Use This Skill

This skill is applied when you:

• Ask to create a decomposition roadmap
• Request migration planning or strategy
• Need help prioritizing decomposition work
• Want to track decomposition progress
• Ask about decomposition planning
• Discuss architectural roadmaps
• Need structured approach to decomposition

Key Features

Current State Assessment

Evaluates what's already been done:

• Checks component inventory completion
• Reviews common component analysis
• Assesses component structure
• Reviews dependency analysis
• Checks domain identification status
• Assesses service extraction progress

Pattern-Based Planning

Plans based on the six decomposition patterns:

1. Identify and Size Components 2. Gather Common Domain Components 3. Flatten Components 4. Determine Component Dependencies 5. Create Component Domains 6. Create Domain Services

Prioritization Framework

Prioritizes work using:

• Risk Assessment: Low/Medium/High risk
• Value Assessment: High/Medium/Low value
• Dependency Analysis: Independent/Dependent/Blocking
• Priority Scoring: Calculated priority scores

Phased Roadmap Creation

Creates structured roadmaps with:

• Phase Definition: Analysis, Organization, Extraction
• Milestone Setting: Clear completion markers
• Timeline Estimation: Realistic timeframes
• Deliverable Definition: Expected outputs

Files Included

SKILL.md (Main Skill)

The primary skill file containing:

• Current state assessment methodology
• Pattern identification process
• Prioritization framework
• Roadmap creation techniques
• Architecture story generation
• Progress tracking approach
• Output format templates

QUICK-REFERENCE.md (Quick Lookup)

Fast reference for common scenarios:

• Pattern sequence
• Prioritization matrix
• Roadmap templates
• Story templates
• Progress tracking checklist

README.md (This File)

Complete documentation including:

• What the skill does
• When to use it
• Usage examples
• Core concepts
• Integration with other skills

Usage Examples

Example 1: Create Complete Roadmap

User: "Create a decomposition roadmap for this codebase"

The skill will:
1. Assess current state
2. Identify patterns to apply
3. Prioritize work
4. Create phased roadmap
5. Generate architecture stories
6. Estimate timeline

Output:

# Decomposition Roadmap

## Current State Assessment

- ✅ Components identified and sized
- ⚠️ Common components detected (in progress)
- ❌ Component flattening (not started)
- ❌ Dependency analysis (not started)

## Phased Roadmap

### Phase 1: Analysis & Preparation (Weeks 1-4)

- Complete component flattening
- Perform dependency analysis
- Refactor oversized components

### Phase 2: Domain Organization (Weeks 5-8)

- Identify domains
- Group components
- Refactor namespaces

### Phase 3: Service Extraction (Weeks 9-16)

- Extract domain services
- Define API boundaries
- Deploy services

Example 2: Prioritize Work

User: "Prioritize decomposition work based on component analysis"

The skill will:
1. Review component inventory
2. Assess risk and value
3. Calculate priority scores
4. Create prioritized plan

Output:

## Prioritized Work Plan

### High Priority

1. Complete Component Flattening (Priority: 9/10)
   - Risk: Low, Value: High
   - Effort: 2 weeks

2. Dependency Analysis (Priority: 8/10)
   - Risk: Low, Value: High
   - Effort: 1 week

Example 3: Track Progress

User: "Show decomposition progress"

The skill will:
1. Check pattern completion
2. Review story status
3. Calculate metrics
4. Identify blockers

Output:

## Progress Dashboard

### Pattern Completion

- ✅ Pattern 1: Complete (100%)
- ✅ Pattern 2: Complete (100%)
- ⚠️ Pattern 3: In Progress (60%)
- ❌ Pattern 4: Not Started (0%)

### Key Metrics

- Components Identified: 75
- Components Refactored: 45 (60%)
- Domains Created: 0
- Services Extracted: 0

Core Concepts

Decomposition Pattern Sequence

The six patterns should be applied in sequence:

1. Identify and Size Components → Foundation 2. Gather Common Domain Components → Find duplicates 3. Flatten Components → Clean structure 4. Determine Component Dependencies → Assess feasibility 5. Create Component Domains → Group components 6. Create Domain Services → Extract services

Phased Approach

Decomposition follows three main phases:

Phase 1: Analysis & Preparation

• Component identification and sizing
• Common component detection
• Component flattening
• Dependency analysis

Phase 2: Domain Organization

• Domain identification
• Component grouping
• Namespace refactoring

Phase 3: Service Extraction

• Domain service creation
• Service extraction
• API boundary definition

Prioritization Factors

When prioritizing work, consider:

• Risk: How risky is this work?
• Value: How valuable is this work?
• Dependencies: What must be done first?
• Complexity: How complex is this work?

How to Use

Quick Start

Request creation of a plan:

"Create a decomposition roadmap for this codebase"
"Prioritize decomposition work based on component analysis"
"Create a phased decomposition plan"
"Show decomposition progress"

Step-by-Step Usage

1. Assess Current State

Start by understanding what's been done:

User: "What's the current state of decomposition?"

This will:

• Check what patterns are complete
• Identify what's in progress
• Find what hasn't started

2. Create Roadmap

Build a structured plan:

User: "Create a decomposition roadmap"

This will:

• Identify patterns to apply
• Prioritize work
• Create phased roadmap
• Generate architecture stories

3. Prioritize Work

Focus on high-priority items:

User: "Prioritize decomposition work"

This will:

• Assess risk and value
• Calculate priority scores
• Create prioritized plan

4. Track Progress

Monitor progress over time:

User: "Show decomposition progress"

This will:

• Check pattern completion
• Review story status
• Calculate metrics
• Identify blockers

Advanced Usage

Custom Phases

Define custom phases:

User: "Create roadmap with custom phases: Analysis, Refactoring, Extraction, Optimization"

Risk-Based Prioritization

Focus on risk:

User: "Prioritize work by risk, starting with lowest risk"

Timeline Estimation

Get time estimates:

User: "Estimate timeline for complete decomposition"

Output Format

The skill generates structured output:

Decomposition Roadmap

# Decomposition Roadmap

## Current State Assessment

[What's been done, what's remaining]

## Phased Roadmap

### Phase 1: Analysis & Preparation

[Patterns, milestones, timeline]

### Phase 2: Domain Organization

[Patterns, milestones, timeline]

### Phase 3: Service Extraction

[Patterns, milestones, timeline]

Prioritized Work Plan

## Prioritized Work Plan

### High Priority

1. [Work item] (Priority: X/10)
   - Risk: Low/Medium/High
   - Value: High/Medium/Low
   - Effort: X weeks

### Medium Priority

[Similar format]

Architecture Stories

## Architecture Stories

### Story 1: [Title]

**As an architect**, I need to [action]
to support [architectural characteristic]
so that [benefit].

**Acceptance Criteria**:

- [ ] Criterion 1
- [ ] Criterion 2

**Estimate**: X story points
**Priority**: High/Medium/Low
**Dependencies**: [List]

Progress Dashboard

## Progress Dashboard

### Pattern Completion Status

[Table showing pattern status and progress]

### Story Completion Status

[Completed/In Progress/Not Started counts]

### Key Metrics

[Components, domains, services metrics]

Integration with Other Skills

This skill coordinates the use of other decomposition skills:

1. Component Identification & Sizing → Provides foundation data 2. Common Domain Component Detection → Identifies consolidation work 3. Component Flattening → Prepares for domain grouping 4. Component Dependency Analysis → Validates feasibility 5. Domain Identification & Grouping → Enables service extraction 6. Decomposition Planning & Roadmap (this skill) → Coordinates everything

Use this skill to orchestrate the entire decomposition effort.

Installation

This skill is installed at the project level:

skills/decomposition-planning-roadmap/

This means it's:

• Shared with the repository: Anyone cloning this repo gets the skill
• Version controlled: Changes are tracked in git
• Project-specific: Can be customized for this codebase

The skill will be automatically discovered and used when appropriate based on the description in the frontmatter.

Customization

For Project-Specific Patterns

Document your project's decomposition approach:

skills/decomposition-planning-roadmap/
└── project-approach.md  # Document project-specific patterns

Custom Phases

Modify phase definitions in SKILL.md:

## Custom Phases

For this project:

- Phase 1: Analysis (2 weeks)
- Phase 2: Refactoring (4 weeks)
- Phase 3: Extraction (8 weeks)
- Phase 4: Optimization (2 weeks)

Custom Prioritization

Modify prioritization formula:

## Custom Prioritization

For this project:
Priority = (Value × 4) - (Risk × 2) - (Dependencies × 1)

Best Practices

Do's ✅

• Start with analysis patterns (Patterns 1-4)
• Prioritize low-risk, high-value work
• Create architecture stories for tracking
• Set clear milestones and success criteria
• Track progress regularly
• Adjust roadmap based on learnings
• Collaborate with stakeholders on priorities
• Respect pattern dependencies

Don'ts ❌

• Don't skip analysis patterns
• Don't start service extraction too early
• Don't ignore dependencies between patterns
• Don't create unrealistic timelines
• Don't skip progress tracking
• Don't forget to validate with stakeholders
• Don't proceed without feasibility assessment
• Don't create roadmap without current state assessment

Common Patterns

Typical Roadmap Structure

Small Project (3-6 months):

• Phase 1: Analysis (1 month)
• Phase 2: Refactoring (2 months)
• Phase 3: Extraction (2-3 months)

Medium Project (6-12 months):

• Phase 1: Analysis & Preparation (2 months)
• Phase 2: Domain Organization (2 months)
• Phase 3: Service Extraction (4-6 months)
• Phase 4: Optimization (2 months)

Large Project (12+ months):

• Phase 1: Analysis & Preparation (3-4 months)
• Phase 2: Domain Organization (3-4 months)
• Phase 3: Service Extraction (6-8 months)
• Phase 4: Optimization (2-3 months)

Prioritization Matrix

High Value, Low Risk    | High Value, High Risk
(Do First)              | (Do Carefully)
────────────────────────┼──────────────────────
Low Value, Low Risk     | Low Value, High Risk
(Do Later)              | (Avoid/Defer)

Troubleshooting

Roadmap Too Aggressive

Issue: Timeline seems unrealistic

Solution:

• Add buffer time to estimates
• Break work into smaller chunks
• Reassess complexity
• Consider dependencies more carefully

Unclear Priorities

Issue: Hard to prioritize work

Solution:

• Use prioritization matrix
• Assess risk and value objectively
• Get stakeholder input
• Consider dependencies

Progress Stalled

Issue: Not making progress

Solution:

• Identify blockers
• Reassess priorities
• Break work into smaller pieces
• Get help with blockers

References

This skill is based on:

• Software Architecture: The Hard Parts by Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani
• Component-Based Decomposition Patterns (Chapter 5)
• Fundamentals of Software Architecture by Mark Richards & Neal Ford
• Agile Project Management principles

Contributing

To improve this skill:

1. Add more roadmap templates 2. Expand prioritization frameworks 3. Add progress tracking examples 4. Document new patterns or approaches 5. Share real-world case studies

Version

Version: 1.0.0 Created: 2026-02-05 Based on: Component-Based Decomposition Patterns from "Software Architecture: The Hard Parts"

---

Quick Start

To use this skill immediately:

User: "Create a decomposition roadmap for this codebase"
User: "Prioritize decomposition work based on component analysis"
User: "Create a phased decomposition plan"
User: "Show decomposition progress"

This skill will automatically be applied to provide comprehensive decomposition planning and roadmap creation.