// Generate phased implementation roadmaps from Architecture Decision Records
| title | adr-roadmap: Generate phased implementation roadmaps from Architecture Decision Records |
| name | adr-roadmap |
| description | Generate phased implementation roadmaps from Architecture Decision Records |
| tags | ["sdd-workflow","shared-architecture"] |
| custom_fields | {"layer":null,"artifact_type":null,"architecture_approaches":["ai-agent-based","traditional-8layer"],"priority":"shared","development_status":"active","skill_category":"utility","upstream_artifacts":["ADR"],"downstream_artifacts":["TASKS","IPLAN"]} |
Analyze Architecture Decision Records (ADRs) and generate phased implementation roadmaps with timelines, dependencies, resource allocation, and risk assessment for any project type.
Key Capabilities:
project-mngt skill insteaddoc-flow skill insteadcharts-flow skill instead| Input | Description | Example |
|---|---|---|
| adr_directory | Absolute path to ADR markdown files | {project_root}/docs/ADR/ |
| project_context | Project type, team size, timeline constraints | "Trading platform, 5 FTE, 6-month timeline" |
| Input | Description | Default |
|---|---|---|
| output_file | Roadmap destination path | {adr_directory}/ADR-000_IMPLEMENTATION-ROADMAP.md |
| max_phase_duration | Maximum weeks per phase | 8 weeks |
| prioritize_adr | Force specific ADR ID first (e.g., "ADR-002") | None |
| phase_model | Phasing approach: poc-mvp-prod, iterative, waterfall | poc-mvp-prod |
| team_size | Number of FTE engineers | 3 |
| target_phases | Desired number of phases | Auto-calculate |
Actions:
ADR-*.md files from specified directoryADR-000_index.md) if presentValidation:
Output: ADR inventory with metadata
Actions:
Dependency Classification:
Output:
Actions:
Effort Estimation Formula:
Total Effort = Σ(ADR Complexity × Base Effort) × Risk Buffer
Base Effort (1=1d, 2=2d, 3=4d, 4=10d, 5=20d)
Risk Buffer = 1.2 (20% contingency)
Output:
Phasing Algorithm:
Apply selected phase model:
Phase 1: POC (Proof of Concept)
- Minimal ADRs to validate technical feasibility
- Target: 2-3 weeks
- Criteria: Core integration working end-to-end
Phase 2: MVP (Minimum Viable Product)
- Add multi-user, persistence, basic security
- Target: 4-6 weeks
- Criteria: Production-ready for limited users
Phase 3: Production
- Cloud deployment, full security, monitoring
- Target: 6-8 weeks
- Criteria: Enterprise-grade reliability
Phase 4: Scale & Optimize
- Performance tuning, advanced patterns
- Target: 4-6 weeks
- Criteria: Performance targets met
Phase 5: Advanced Features
- Extended capabilities, continuous improvement
- Target: Ongoing
- Criteria: Feature backlog prioritized
Each iteration (2-4 weeks):
- Select ADR cluster (low dependency)
- Implement and validate
- Integrate with existing system
- Deploy incrementally
Phase by ADR category:
- Infrastructure ADRs
- Core business logic ADRs
- Integration ADRs
- Optimization ADRs
Phase Assignment Rules:
Output:
Actions:
Phase Duration = (Σ ADR Effort in Phase) / (Team Size × Efficiency Factor)
Efficiency Factor = 0.7 (account for meetings, context switching)
gantt
title ADR Implementation Timeline
dateFormat YYYY-MM-DD
section Phase 1
POC: p1, 2025-01-15, 3w
section Phase 2
MVP: p2, after p1, 6w
Output:
Generate comprehensive roadmap at {output_file}:
Document Structure:
# ADR Implementation Roadmap
## Document Control
| Item | Details |
|------|---------|
| **Project Name** | [Enter project name] |
| **Document Version** | [e.g., 1.0] |
| **Date** | [Current date] |
| **Document Owner** | [Name and title] |
| **Prepared By** | [Technical Lead/Architect name] |
| **Status** | [Draft / In Review / Approved] |
### Document Revision History
| Version | Date | Author | Changes Made | Approver |
|---------|------|--------|--------------|----------|
| 1.0 | [Date] | [Name] | Initial roadmap | |
| | | | | |
## Executive Summary
- Project overview
- Total ADRs: N
- Total phases: M
- Timeline: X weeks
- Team size: Y FTE
- Key milestones
## Phase 1: [Phase Name]
### Objectives
### Duration
### ADRs to Implement
#### ADR-XXX: Title
- Complexity: N/5
- Effort: X hours
- Scope: What to implement
- Deferred: What to skip
- Acceptance Criteria
### System Architecture
- Mermaid diagram
### Implementation Order
- Week-by-week breakdown
### Deliverables
### Success Criteria
### Risk Assessment
### Exit Criteria
## Phase 2: [Phase Name]
[Same structure]
...
## ADR Dependency Matrix
- Mermaid flowchart
- Critical path highlighted
- Parallel opportunities
## Technical Debt Management
- POC shortcuts (acceptable)
- MVP shortcuts (acceptable)
- Production standards (zero tolerance)
- Debt remediation timeline
## Risk Assessment
- Phase 1 risks
- Phase 2 risks
- Go/no-go thresholds
## Testing Strategy
- Phase 1: Manual testing only
- Phase 2: Automated unit/integration
- Phase 3: Security, performance, compliance
- Phase 4: Load testing, chaos engineering
## Acceptance Criteria
- Phase 1 acceptance
- Phase 2 acceptance
- [Per phase]
## Traceability
- ADR to Phase mapping table
- Phase to Timeline mapping
- Upstream sources (BRD, PRD)
- Downstream artifacts (SYS, REQ, SPEC)
Document Formatting:
Output: Complete roadmap markdown file
Characteristics:
Phasing Strategy:
Example Phase Structure:
Phase 1: Foundation (Tech stack, cloud, database)
Phase 2: Core Features (Business logic ADRs)
Phase 3: Integration (External services, APIs)
Phase 4: Polish (Performance, UX, advanced features)
Characteristics:
Phasing Strategy:
Example Phase Structure:
Phase 1: Infrastructure Prep (Observability, feature flags)
Phase 2: Low-Risk Migration (Read-only endpoints)
Phase 3: Medium-Risk Migration (Write endpoints with rollback)
Phase 4: High-Risk Migration (Core business logic)
Phase 5: Decommission Legacy (Remove old system)
Migration-Specific Sections to Add:
Characteristics:
Phasing Strategy:
Example Phase Structure:
Phase 1: Test Infrastructure (Add missing tests)
Phase 2: Module A Refactor (Database layer)
Phase 3: Module B Refactor (API layer)
Phase 4: Module C Refactor (Business logic)
Phase 5: Cleanup (Remove deprecated code)
When to create a new phase?
Decision tree:
1. Check dependencies:
- New ADRs have no dependencies on current phase? → New phase
- All dependencies in current/prior phases? → Same phase
2. Check complexity threshold:
- Current phase exceeds max_phase_duration (8 weeks)? → New phase
- Under threshold? → Same phase
3. Check risk isolation:
- ADR is high-risk (complexity 4-5)? → Consider separate phase for POC
- Low-medium risk? → Group with similar ADRs
4. Check milestone boundary:
- Natural project milestone (POC, MVP, Beta, GA)? → Phase boundary
- Mid-milestone? → Same phase
Output: Phase boundary decision
Order ADRs by:
Priority ranking (highest to lowest):
Algorithm:
def sequence_adrs(adrs_in_phase):
# Step 1: Topological sort by dependencies (must respect)
sorted_by_deps = topological_sort(adrs_in_phase)
# Step 2: Within each dependency level, sort by risk/value
for level in sorted_by_deps:
if phase == "POC":
level.sort(key=lambda adr: adr.risk, reverse=True) # High-risk first
else:
level.sort(key=lambda adr: adr.value, reverse=True) # High-value first
return flatten(sorted_by_deps)
Output: Ordered ADR sequence per phase
Aggregate ADR complexity when explicit ratings not available:
Estimation heuristics:
Complexity 1 (Trivial):
- Simple configuration change
- Library upgrade (no breaking changes)
- Documentation update
- Effort: 1 day
Complexity 2 (Simple):
- Add logging/monitoring
- Simple API endpoint
- Basic CRUD operation
- Effort: 2 days
Complexity 3 (Moderate):
- New authentication provider
- Database schema change
- Third-party integration
- Effort: 3-5 days
Complexity 4 (Complex):
- New deployment architecture
- Real-time data processing
- Multi-service integration
- Effort: 1-2 weeks
Complexity 5 (Architectural):
- Cloud provider migration
- Event-driven architecture
- Major technology swap
- Effort: 3-4 weeks
Output: Complexity rating per ADR
Acceptable shortcuts per phase:
| Phase | Acceptable Shortcuts | Must Have | Remediation Phase |
|---|---|---|---|
| POC | Hardcoded credentials, in-memory data, print logging, no tests, local deployment | Working integration | MVP |
| MVP | Basic error handling, simple caching, minimal monitoring | Multi-user auth, persistence, unit tests | Production |
| Production | Partial optimization | Full security, monitoring, HA, compliance | Scale |
| Scale | Some manual processes | Performance targets, auto-scaling | Advanced |
| Advanced | None (continuous improvement) | All features production-grade | N/A |
Output: Technical debt tracking table
User Invocation:
Use the adr-roadmap skill to create implementation roadmap.
Inputs:
- ADR directory: {project_root}/docs/ADR/
- Project context: Interactive Brokers MCP server, 3 developers, POC in 3 weeks
- Phase model: poc-mvp-prod
- Team size: 3
Generate roadmap in {project_root}/docs/ADR/ADR-000_IMPLEMENTATION-ROADMAP.md
Skill Actions:
{project_root}/docs/ADR/Generated Output: ADR-000_IMPLEMENTATION-ROADMAP.md (~1,400 lines)
User Invocation:
Use adr-roadmap skill for microservices migration roadmap.
Inputs:
- ADR directory: {example_project_a}/architecture/decisions/
- Project context: Monolith to microservices migration, 8 developers, 9-month timeline
- Phase model: iterative
- Team size: 8
Generate roadmap in {example_project_a}/architecture/decisions/ADR-000_IMPLEMENTATION-ROADMAP.md
Skill Actions:
Generated Output: Migration roadmap with rollback plans
User Invocation:
Create 6-month data platform roadmap.
Inputs:
- ADR directory: {example_project_b}/docs/ADR/
- Project context: Real-time analytics platform, 10 engineers, 6-month timeline
- Phase model: waterfall
- Team size: 10
- Target phases: 6
Generate roadmap in {example_project_b}/docs/ADR/ADR-000_IMPLEMENTATION-ROADMAP.md
Skill Actions:
Generated Output: Resource-aware roadmap with 6 phases
User Invocation:
Create roadmap for IoT device firmware.
Inputs:
- ADR directory: /firmware/docs/adr/
- Project context: IoT sensor firmware, 2 embedded engineers, hardware prototype ready
- Phase model: poc-mvp-prod
- Team size: 2
- Constraints: Hardware prototype available Week 4
Generate roadmap in /firmware/docs/adr/ADR-000_IMPLEMENTATION-ROADMAP.md
Skill Actions:
Generated Output: Hardware-aware roadmap with gated phases
Roadmap document must satisfy:
Missing ADR metadata:
Circular dependencies:
Zero ADRs found:
Conflicting constraints:
File: {project}/docs/ADR/ADR-000_IMPLEMENTATION-ROADMAP.md
Size: 1,000-2,000 lines (varies by ADR count)
Token Limit: <100,000 tokens
Sections (in order):
Document Header:
# ADR Implementation Roadmap
Document Control:
Table of Contents: Links to all sections
Executive Summary:
Phase Definitions (1 section per phase):
ADR Dependency Matrix:
Technical Debt Management:
Risk Assessment:
Testing Strategy:
Acceptance Criteria:
Traceability:
project-mngt Skill Instead When:doc-flow Skill Instead When:adr-roadmap + charts-flow When:adr-roadmap + project-mngt When:| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2025-01-08 | Initial skill creation with comprehensive methodology |
End of Skill Definition