| name | compare-architectures |
| description | Generate and compare multiple architecture options (minimal, moderate, full modernization) with comprehensive trade-offs analysis across cost, timeline, risk, performance, and maintainability dimensions. Use when evaluating multiple architectural approaches or deciding between modernization strategies with different cost/risk trade-offs. |
| acceptance | [{"three_options_generated":"Three distinct architecture options created (minimal, moderate, full)"},{"trade_offs_analyzed":"Each option includes cost, timeline, risk, performance, maintainability analysis"},{"recommendation_provided":"Clear recommendation based on user constraints with justification"},{"comparison_matrix":"Side-by-side comparison matrix for easy evaluation"},{"next_steps_defined":"Implementation roadmap outlined for recommended option"}] |
| inputs | {"current_architecture":{"type":"string","required":false,"description":"Path to current architecture document or textual description of existing system"},"new_requirements":{"type":"string","required":true,"description":"User's goals, ideas, and new requirements to be incorporated"},"constraints":{"type":"object","required":false,"description":"Timeline, budget, team size, expertise constraints","default":{}},"comparison_dimensions":{"type":"array","required":false,"description":"Dimensions to compare (cost, timeline, risk, performance, maintainability, scalability, security)","default":["cost","timeline","risk","maintainability"]},"project_type":{"type":"string","required":false,"description":"frontend | backend | fullstack (auto-detected if not provided)"}} |
| outputs | {"comparison_created":{"type":"boolean","description":"Whether comparison document was successfully created"},"comparison_location":{"type":"string","description":"File path to comparison document (docs/architecture-comparison-{timestamp}.md)"},"options_count":{"type":"number","description":"Number of architecture options generated (always 3)"},"recommended_option":{"type":"string","description":"Which option is recommended (minimal | moderate | full)"},"recommendation_confidence":{"type":"number","description":"Confidence in recommendation (0-100)"}} |
| telemetry | {"emit":"skill.compare-architectures.completed","track":["project_type","options_count","recommended_option","recommendation_confidence","comparison_dimensions","duration_ms","comparison_location"]} |
Compare Architectures Skill
Purpose
Generate three distinct architecture options with comprehensive trade-offs analysis to help users make informed decisions about system modernization or design. Each option represents a different investment level (minimal, moderate, full) with detailed cost, timeline, risk, and quality analysis.
Core Principles:
- Present 3 viable options (not 1 perfect solution)
- Honest trade-offs analysis (no "best" option without context)
- Evidence-based estimates (cost, timeline, risk)
- Clear recommendation with justification
- Actionable next steps for chosen option
Prerequisites
- Understanding of current system (if brownfield)
- Clear new requirements or goals
- User constraints known (timeline, budget, team)
- workspace/ directory exists for output storage
Workflow
Step 1: Analyze Current State & Requirements
Action: Understand current architecture and new requirements to create meaningful options.
Key Activities:
-
Load Current Architecture (if brownfield)
python .claude/skills/bmad-commands/scripts/read_file.py \
--path {current_architecture} \
--output json
If current architecture is textual description, parse for:
- Technology stack (languages, frameworks, databases)
- Architecture type (monolith, microservices, etc.)
- Scale indicators (users, data volume, traffic)
- Pain points mentioned
-
Parse New Requirements
Extract from new_requirements:
- Functional changes: New features, capabilities, integrations
- Non-functional changes: Performance, scalability, security needs
- Business goals: Why these changes matter, expected outcomes
- Success criteria: How to measure success
Example parsing:
Input: "Add real-time chat, support 10K concurrent users, mobile app needed"
Parsed:
- Functional: Real-time chat feature, mobile support
- Non-functional: Scale to 10K concurrent (performance requirement)
- Technical implications: Need WebSocket/SSE, mobile framework
-
Identify Constraints
From constraints parameter:
- Timeline: How soon is this needed? (weeks, months, year)
- Budget: Cost sensitivity (low, moderate, high)
- Team size: How many developers available?
- Team expertise: Current skill set, willingness to learn new tech
- Risk tolerance: Conservative (low risk) vs. aggressive (innovation)
Default assumptions if not provided:
- Timeline: Moderate (3-6 months)
- Budget: Moderate
- Team: Small (2-5 developers)
- Expertise: Moderate (willing to learn)
- Risk tolerance: Moderate
-
Detect Project Type (if not provided)
Based on current architecture and requirements:
- Frontend: UI/UX dominant, client-side changes
- Backend: API/services/data dominant
- Fullstack: Both frontend and backend changes
Output: Comprehensive context for option generation
See: references/requirement-analysis.md for detailed parsing techniques
Step 2: Generate Three Architecture Options
Action: Create three distinct options representing different investment/change levels.
Option Generation Strategy:
Option A: Minimal Changes (Lowest Risk, Fastest)
Philosophy: Keep what works, fix what's broken, add minimally.
Approach:
- Technology: Stick with current stack, upgrade versions
- Architecture: Minimal pattern changes, targeted fixes
- Scope: Address critical pain points only, defer nice-to-haves
- Integration: Bolt-on new features to existing architecture
- Migration: No migration, incremental additions
Typical Characteristics:
- Timeline: 2-6 weeks
- Cost: $ (1x baseline)
- Risk: Low (minimal changes, proven tech)
- Team impact: Minimal learning curve
- Technical debt: May increase slightly (tactical over strategic)
Example (Real-time Chat Requirement):
## Option A: Minimal Changes - Bolt-on Chat
**Approach:** Add Socket.IO to existing Express backend, embed chat widget in current UI.
**Technology Stack:**
- Keep: Current React frontend, Express backend, PostgreSQL
- Add: Socket.IO (WebSocket), Redis (pub/sub)
**Architecture:**
- Chat service as separate Express route
- Shared PostgreSQL for messages
- Redis for pub/sub between server instances
**Changes Required:**
- Add Socket.IO endpoints to Express (~500 LOC)
- Add chat UI component to React (~300 LOC)
- Add Redis for horizontal scaling (~100 LOC)
**Pros:**
✅ Fast implementation (3-4 weeks)
✅ Low risk (minimal changes)
✅ No migration needed
✅ Team knows the stack
**Cons:**
❌ Not optimal architecture for real-time
❌ May have scaling challenges >5K users
❌ Technical debt increases
❌ Shared database could become bottleneck
**Cost:** $15K-$25K (developer time)
**Timeline:** 3-4 weeks
**Risk:** Low
Option B: Moderate Refactor (Balanced Approach)
Philosophy: Strategic improvements, selective modernization, set up for future.
Approach:
- Technology: Mix of current + modern (gradual migration)
- Architecture: Improve patterns, introduce new where needed
- Scope: Address current needs + position for future growth
- Integration: Refactor key areas, new services for new features
- Migration: Incremental (strangler fig pattern)
Typical Characteristics:
- Timeline: 2-4 months
- Cost: $$ (2-3x baseline)
- Risk: Medium (some new tech, planned migration)
- Team impact: Moderate learning (new patterns/tools)
- Technical debt: Reduced overall (strategic improvements)
Example (Real-time Chat Requirement):
## Option B: Moderate Refactor - Dedicated Chat Service
**Approach:** Extract chat as microservice with modern real-time stack, keep core app.
**Technology Stack:**
- Keep: React frontend, Express API, PostgreSQL (core)
- New: Node.js + Socket.IO (chat service), MongoDB (chat messages), Redis (caching)
**Architecture:**
- Chat microservice (separate deployment)
- Event-driven communication (message bus)
- Dedicated database for chat (MongoDB)
- API gateway pattern for routing
**Changes Required:**
- Build chat microservice (~2K LOC)
- Integrate with existing auth (JWT sharing)
- Update frontend to connect to chat service
- Set up API gateway (Kong/Express Gateway)
**Pros:**
✅ Scales well (dedicated service)
✅ Better real-time performance
✅ Reduces technical debt
✅ Positions for future microservices
✅ Team learns modern patterns
**Cons:**
❌ More complex deployment
❌ Need to learn microservices patterns
❌ Operational overhead (monitoring, debugging)
⚠️ Migration period (running both)
**Cost:** $40K-$60K (developer time + infrastructure)
**Timeline:** 2-3 months
**Risk:** Medium
Option C: Full Modernization (Highest Quality, Longest Timeline)
Philosophy: Do it right, invest for long-term, modern best practices.
Approach:
- Technology: Modern stack, latest frameworks and tools
- Architecture: Best practices, scalable patterns from day 1
- Scope: Solve current needs + future-proof for 3-5 years
- Integration: Complete redesign, greenfield opportunity
- Migration: Phased complete migration or parallel run
Typical Characteristics:
- Timeline: 4-8 months
- Cost: $$$ (4-6x baseline)
- Risk: High (major changes, new tech, migration complexity)
- Team impact: Significant learning (new ecosystem)
- Technical debt: Near zero (clean slate)
Example (Real-time Chat Requirement):
## Option C: Full Modernization - Real-time First Architecture
**Approach:** Rebuild as real-time-first app with modern fullstack framework.
**Technology Stack:**
- Frontend: Next.js 15 (React 19, server components)
- Backend: tRPC + WebSocket, serverless functions
- Database: PostgreSQL (main) + Redis (cache/pub-sub)
- Real-time: Ably or Pusher (managed real-time infrastructure)
- Mobile: React Native (shared components with web)
**Architecture:**
- Fullstack monorepo (Turborepo)
- Real-time-first design (WebSocket primary, HTTP fallback)
- Serverless functions (auto-scaling)
- CDN edge functions for global performance
- Mobile + web from single codebase
**Changes Required:**
- Complete rebuild of frontend in Next.js (~8K LOC)
- Backend as tRPC API + WebSocket (~4K LOC)
- Real-time infrastructure setup (Ably/Pusher)
- Mobile app (React Native, ~3K LOC)
- Data migration from old to new system
**Pros:**
✅ Modern, maintainable codebase
✅ Excellent real-time performance
✅ Scales to 100K+ users easily
✅ Mobile + web unified
✅ Easy to hire developers (popular stack)
✅ Near-zero technical debt
**Cons:**
❌ Long timeline (4-6 months)
❌ High cost (significant investment)
❌ Team needs to learn new stack
❌ Complex migration from old system
❌ Risk of over-engineering
**Cost:** $120K-$180K (developer time + services)
**Timeline:** 4-6 months
**Risk:** High
Step 3: Perform Trade-offs Analysis
Action: Compare options across key dimensions to enable informed decision.
Key Dimensions:
1. Cost Analysis
Components:
- Development time: Developer hours × hourly rate
- Infrastructure: Hosting, services, licenses
- Migration: Data migration, parallel running, cutover
- Training: Team learning curve, external training
- Opportunity cost: What else could team work on?
Comparison Matrix:
| Dimension | Option A: Minimal | Option B: Moderate | Option C: Full |
|---|
| Development | 2-3 dev-weeks | 8-12 dev-weeks | 20-26 dev-weeks |
| Infrastructure | +$50/mo | +$200/mo | +$500/mo |
| Migration | None | $5K-$10K | $15K-$25K |
| Training | None | Moderate | Significant |
| Total Cost | $15K-$25K | $40K-$60K | $120K-$180K |
2. Timeline Analysis
Factors:
- Planning: Requirements, design, architecture
- Development: Implementation time
- Testing: QA, performance, security
- Migration: Data migration, cutover, validation
- Stabilization: Bug fixes, monitoring, optimization
Comparison Matrix:
| Phase | Option A: Minimal | Option B: Moderate | Option C: Full |
|---|
| Planning | 1 week | 2 weeks | 3 weeks |
| Development | 2-3 weeks | 8-10 weeks | 16-20 weeks |
| Testing | 1 week | 2 weeks | 4 weeks |
| Migration | None | 1 week | 2-3 weeks |
| Stabilization | 1 week | 2 weeks | 3 weeks |
| Total Timeline | 3-4 weeks | 2-3 months | 4-6 months |
3. Risk Analysis
Risk Categories:
- Technical risk: New tech, complex patterns, unknowns
- Migration risk: Data loss, downtime, bugs
- Team risk: Skill gaps, learning curve, velocity drop
- Business risk: Opportunity cost, market timing, competition
Scoring (0-100, higher = riskier):
| Risk Type | Option A: Minimal | Option B: Moderate | Option C: Full |
|---|
| Technical | 20 (known tech) | 50 (some new) | 75 (major changes) |
| Migration | 10 (no migration) | 40 (incremental) | 70 (big bang) |
| Team | 15 (no learning) | 45 (moderate learn) | 65 (steep curve) |
| Business | 25 (low impact) | 35 (moderate) | 55 (high impact) |
| Overall Risk | Low (18) | Medium (43) | High (66) |
4. Performance & Scalability
Metrics:
- Latency: Response time (p50, p95, p99)
- Throughput: Requests per second
- Concurrency: Concurrent users supported
- Scalability: Horizontal/vertical scaling capability
Comparison:
| Metric | Option A: Minimal | Option B: Moderate | Option C: Full |
|---|
| Latency | Good (<200ms) | Very Good (<100ms) | Excellent (<50ms) |
| Concurrency | ~5K users | ~25K users | ~100K+ users |
| Scalability | Limited (vertical) | Good (horizontal) | Excellent (elastic) |
| Score | 60/100 | 80/100 | 95/100 |
5. Maintainability & Technical Debt
Factors:
- Code quality: Readability, structure, patterns
- Technical debt: Shortcuts, compromises, legacy code
- Team velocity: How fast can team add features later?
- Hiring: How easy to find developers?
Comparison:
| Factor | Option A: Minimal | Option B: Moderate | Option C: Full |
|---|
| Code Quality | Fair (adds debt) | Good (improves) | Excellent (clean) |
| Tech Debt | +10% increase | -20% reduction | -90% reduction |
| Future Velocity | Slows over time | Maintains | Accelerates |
| Hiring | Moderate | Good | Excellent |
| Score | 50/100 | 75/100 | 95/100 |
Step 4: Generate Recommendation
Action: Recommend the best option based on user constraints and provide justification.
Recommendation Logic:
def recommend_option(constraints, user_priorities):
scores = {
"minimal": 0,
"moderate": 0,
"full": 0
}
if constraints.timeline == "urgent" (<2 months):
scores["minimal"] += 40
scores["moderate"] += 20
scores["full"] += 0
elif constraints.timeline == "moderate" (2-6 months):
scores["minimal"] += 20
scores["moderate"] += 40
scores["full"] += 20
else:
scores["minimal"] += 10
scores["moderate"] += 30
scores["full"] += 40
if constraints.budget == "tight":
scores["minimal"] += 40
scores["moderate"] += 15
scores["full"] += 0
elif constraints.budget == "moderate":
scores["minimal"] += 20
scores["moderate"] += 40
scores["full"] += 15
else:
scores["minimal"] += 10
scores["moderate"] += 25
scores["full"] += 40
if constraints.risk_tolerance == "conservative":
scores["minimal"] += 30
scores["moderate"] += 20
scores["full"] += 5
elif constraints.risk_tolerance == "moderate":
scores["minimal"] += 15
scores["moderate"] += 35
scores["full"] += 20
else:
scores["minimal"] += 5
scores["moderate"] += 20
scores["full"] += 40
if user_priorities.includes("long_term_quality"):
scores["full"] += 20
scores["moderate"] += 10
if user_priorities.includes("speed_to_market"):
scores["minimal"] += 20
scores["moderate"] += 10
if user_priorities.includes("scale_for_growth"):
scores["full"] += 15
scores["moderate"] += 10
return max(scores, key=scores.get)
Recommendation Format:
## My Recommendation: Option B - Moderate Refactor
**Confidence:** 85% (High)
**Why This Option:**
Given the constraints:
- Timeline: 3-4 months (moderate)
- Budget: $40K-$60K (moderate)
- Risk tolerance: Medium (willing to invest strategically)
- Priorities: Scale for growth + reduce technical debt
**Option B (Moderate Refactor) is the best fit because:**
1. **Balanced Investment:**
- Not too fast/cheap (Option A would hit limits soon)
- Not too slow/expensive (Option C might be over-engineering)
- $40K-$60K is reasonable for 2-3 month project
2. **Addresses Core Needs:**
- Solves real-time chat requirement properly (dedicated service)
- Scales to 25K users (covers the 10K + growth trajectory)
- Sets up for future microservices (if needed)
3. **Manageable Risk:**
- Team can learn gradually (not all at once like Option C)
- Incremental migration (lower risk than big bang)
- Proven patterns (microservices, event-driven)
4. **Future-Proof:**
- Reduces technical debt (20% improvement)
- Easier to hire (modern but not bleeding edge)
- Positions for growth (can add more services later)
**When to Consider Alternatives:**
- **Choose Option A if:** Timeline is critical (<6 weeks), budget is very tight (<$30K)
- **Choose Option C if:** Planning for 100K+ users, have 6+ months, budget >$120K
Confidence Scoring:
- High (80-100%): Clear constraints, obvious best choice
- Medium (60-79%): Trade-offs close, depends on priorities
- Low (<60%): Need more information, similar options
Step 5: Create Comparison Document
Action: Generate comprehensive comparison document with all options, trade-offs, and recommendation.
Document Structure:
# Architecture Options Comparison: [Project Name]
**Date:** [YYYY-MM-DD]
**Prepared For:** [User/Stakeholder]
**Current State:** [Brief summary of existing architecture]
**New Requirements:** [What's being added/changed]
---
## Executive Summary
**Recommendation:** Option B - Moderate Refactor
**Confidence:** 85% (High)
**Why:** Balanced approach that meets the requirements, fits timeline/budget, and positions for future growth without over-engineering.
**Quick Comparison:**
| Factor | Option A | Option B ✅ | Option C |
|--------|----------|------------|----------|
| **Timeline** | 3-4 weeks | 2-3 months | 4-6 months |
| **Cost** | $15K-$25K | $40K-$60K | $120K-$180K |
| **Risk** | Low (18) | Medium (43) | High (66) |
| **Scale** | ~5K users | ~25K users | ~100K+ users |
| **Tech Debt** | +10% | -20% | -90% |
---
## Option A: Minimal Changes
[Detailed description from Step 2]
**Architecture Diagram:**
[ASCII or reference to diagram]
**Technology Stack:**
- [List with justifications]
**Implementation Plan:**
1. [High-level steps]
2. ...
**Pros & Cons:**
✅ [Pros]
❌ [Cons]
**Trade-offs Analysis:**
[Cost, timeline, risk, performance, maintainability details]
---
## Option B: Moderate Refactor ✅ RECOMMENDED
[Detailed description from Step 2]
[Same sections as Option A]
**Why This is Recommended:**
[Recommendation justification from Step 4]
---
## Option C: Full Modernization
[Detailed description from Step 2]
[Same sections as Option A]
---
## Side-by-Side Comparison
### Cost Comparison
[Detailed cost breakdown table]
### Timeline Comparison
[Gantt chart or timeline visualization]
### Risk Comparison
[Risk matrix or scoring table]
### Performance Comparison
[Performance metrics table]
### Maintainability Comparison
[Technical debt and code quality comparison]
---
## Recommendation Details
### Primary Recommendation: Option B
[Full justification from Step 4]
### Alternative Scenarios
**If timeline is critical (<6 weeks):**
→ Choose Option A, plan for Option B later
**If budget is generous (>$120K):**
→ Consider Option C for long-term investment
**If team is risk-averse:**
→ Start with Option A, evaluate results, then consider Option B
---
## Next Steps
### If You Choose Option A (Minimal):
1. [Implementation roadmap]
2. [Key decisions needed]
3. [Timeline with milestones]
### If You Choose Option B (Moderate) ✅:
1. **Week 1-2:** Architecture design finalization
2. **Week 3-4:** Chat microservice development
3. **Week 5-6:** API gateway setup + integration
4. **Week 7-8:** Frontend integration + testing
5. **Week 9-10:** Migration + stabilization
**Key Decisions Needed:**
- Message bus choice (RabbitMQ vs. Kafka vs. AWS SQS)
- API gateway (Kong vs. Express Gateway vs. AWS API Gateway)
- MongoDB hosting (self-managed vs. MongoDB Atlas)
**Success Criteria:**
- Chat supports 10K concurrent users
- p95 latency <100ms
- Zero downtime migration
- No data loss during migration
### If You Choose Option C (Full):
1. [Implementation roadmap]
2. [Key decisions needed]
3. [Timeline with milestones]
---
## Appendices
### Appendix A: Assumptions
- [List all assumptions made]
### Appendix B: Technology Comparison
- [Detailed tech stack comparison]
### Appendix C: Migration Strategy
- [For Option B and C, detailed migration approach]
### Appendix D: Risk Mitigation
- [For each identified risk, mitigation strategies]
---
**Prepared by:** Winston (Architecture Subagent)
**Review Status:** Ready for Stakeholder Review
**Next Action:** Decision on preferred option
File Location: docs/architecture-comparison-[timestamp].md
Reference Files
references/requirement-analysis.md - How to parse and analyze requirementsreferences/option-generation-patterns.md - Strategies for creating optionsreferences/cost-estimation.md - How to estimate costs accuratelyreferences/risk-assessment-framework.md - Risk scoring methodologyreferences/trade-offs-analysis.md - Comprehensive trade-offs evaluation
When to Escalate
Escalate to user when:
- Requirements are vague or contradictory
- Constraints are unrealistic (timeline too short for scope)
- All options have critical risks
- User priorities conflict (e.g., "fastest AND highest quality")
Escalate to architects when:
- Complex architecture patterns needed
- Novel technology choices required
- Compliance/regulatory requirements unclear
- Performance requirements extremely stringent
Success Criteria
A comparison is successful when:
✅ Three viable options generated:
- Each option is realistic and implementable
- Clear differentiation between options
- All options address core requirements
✅ Comprehensive trade-offs:
- All key dimensions analyzed (cost, timeline, risk, etc.)
- Honest assessment (no "perfect" option)
- Evidence-based estimates
✅ Clear recommendation:
- Based on user constraints and priorities
- Well-justified with reasoning
- Confidence level stated
✅ Actionable next steps:
- Implementation roadmap for each option
- Key decisions identified
- Success criteria defined
Part of BMAD Enhanced Planning Suite
