calculate-roi

name	calculate-roi
description	Calculate ROI and Cost Savings methodology and workflow
agent	architect
subtask	false

Calculate ROI and Cost Savings

1. YOLO Mode - Fast, Autonomous (0-1 prompts)

• Autonomous decision making with logging
• Minimal user interaction
• Best for:* Simple, deterministic tasks

2. Interactive Mode - Balanced, Educational (5-10 prompts) [DEFAULT]

• Explicit decision checkpoints
• Educational explanations
• Best for:* Learning, complex decisions

3. Pre-Flight Planning - Comprehensive Upfront Planning

• Task analysis phase (identify all ambiguities)
• Zero ambiguity execution
• Best for:* Ambiguous requirements, critical work

Parameter:* mode (optional, default: interactive)

---

Acceptance Criteria

Purpose:* Definitive pass/fail criteria for task completion

Checklist:*

acceptance-criteria:
  - [ ] Task completed as expected; side effects documented
    type: acceptance-criterion
    blocker: true
    validation: |
      Assert task completed as expected; side effects documented
    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"

---

Error Handling

Strategy:* fallback

Common Errors:*

1. Error:* Task Not Found

   • Cause:* Specified task not registered in system
   • Resolution:* Verify task name and registration
   • Recovery:* List available tasks, suggest similar

2. Error:* Invalid Parameters

   • Cause:* Task parameters do not match expected schema
   • Resolution:* Validate parameters against task definition
   • Recovery:* Provide parameter template, reject execution

3. Error:* Execution Timeout

   • Cause:* Task exceeds maximum execution time
   • Resolution:* Optimize task or increase timeout
   • Recovery:* Kill task, cleanup resources, log state

---

Description

Calculate real cost savings from pattern consolidation with hard numbers. Estimates monthly/annual maintenance costs before and after, projects ROI timeline, shows when investment breaks even.

Prerequisites

• Consolidation completed (consolidate command run successfully)
• .state.yaml contains pattern reduction metrics
• Optional: Team salary data for accurate calculations

Interactive Elicitation

This task uses interactive elicitation to gather cost parameters.

1. Gather Team Context*

   • Team size (number of developers)
   • Average developer hourly rate (default: $150/hr)
   • Monthly hours spent on UI maintenance (estimate if unknown)
   • Implementation cost estimate

2. Review Pattern Metrics*

   • Show consolidation metrics (patterns before/after)
   • Confirm reduction percentages
   • Identify highest-impact reductions

3. Configure Calculation*

   • Ask for conservative vs aggressive estimates
   • Include or exclude training costs
   • Set ROI calculation period (1 year default)

Steps

1. Load Consolidation Metrics*

   • Read .state.yaml for pattern reduction data
   • Extract before/after counts for all pattern types
   • Calculate reduction percentages
   • Validation: Consolidation data exists

2. Calculate Maintenance Cost (Before)*

   • Formula: patterns × hours_per_pattern_monthly × hourly_rate × 12
   • Default: 2 hours/month per pattern for maintenance
   • Include debugging, updates, consistency fixes
   • Validation: Reasonable cost estimate generated

3. Calculate Maintenance Cost (After)*

   • Same formula with consolidated pattern count
   • Factor in design system overhead (small)
   • Validation: Post-consolidation cost calculated

4. Calculate Monthly and Annual Savings*

   • Monthly savings = cost_before - cost_after
   • Annual savings = monthly_savings × 12
   • Validation: Positive savings or explain why not

5. Estimate Implementation Cost*

   • Developer time to create design system
   • Migration effort (from migration strategy)
   • Training time
   • Default: $10,000-15,000 for medium teams
   • Validation: Implementation cost estimated

6. Calculate ROI Metrics*

   • ROI ratio = annual_savings / implementation_cost
   • Breakeven point = implementation_cost / monthly_savings (in months)
   • 3-year projection = (annual_savings × 3) - implementation_cost
   • Validation: ROI calculations complete

7. Calculate Velocity Impact*

   • Estimate time saved per feature (fewer component decisions)
   • Project velocity multiplier (3-6x typical)
   • Convert to dollar value (time = money)
   • Validation: Velocity impact quantified

8. Generate ROI Report*

   • Create roi-analysis.md with executive summary
   • Include detailed calculations with formulas
   • Generate charts (text-based or recommend tools)
   • Show sensitivity analysis (best/worst case)
   • Validation: Comprehensive ROI document created

9. Create Stakeholder Summary*

   • One-page executive summary
   • Key numbers only (investment, savings, breakeven)
   • Visual comparison (before/after costs)
   • Validation: Stakeholder-ready summary

10. Update State File*

    • Add ROI section to .state.yaml
    • Record all cost calculations
    • Update phase to "roi_calculated"
    • Validation: State updated with financial data

Output

• roi-analysis.md*: Detailed ROI analysis with calculations
• executive-summary.md*: One-page stakeholder summary
• cost-breakdown.yaml*: Structured cost data
• .state.yaml: Updated with ROI metrics

Output Format

# roi section in .state.yaml
roi:
  calculated_at: "2025-10-27T14:00:00Z"

  before:
    patterns: 176
    monthly_cost: $38,100
    annual_cost: $457,200
    hours_per_month: 352

  after:
    patterns: 32
    monthly_cost: $6,900
    annual_cost: $82,800
    hours_per_month: 64

  savings:
    monthly: $31,200
    annual: $374,400
    hours_saved_monthly: 288

  implementation:
    estimated_cost: $12,000
    developer_weeks: 4

  roi_metrics:
    ratio: 31.2
    breakeven_months: 0.38
    year_1_net: $362,400
    year_3_cumulative: $1,111,200

  velocity_impact:
    multiplier: "4-6x"
    time_savings: "70% reduction in UI decisions"

Success Criteria

• Realistic cost estimates based on team context
• Both pre and post-consolidation costs calculated
• ROI ratio shows positive return (>2x minimum)
• Breakeven point calculated (typically <1 year)
• Velocity impact quantified
• Executive summary is stakeholder-ready
• All calculations show formulas used

Error Handling

• No consolidation data*: Exit with message to run consolidate first
• Unrealistic costs*: Warn user, suggest reviewing inputs
• Negative ROI*: Explain why, suggest higher-impact consolidation
• Missing team data*: Use industry defaults, flag estimates as rough

Security Considerations

• Salary data is sensitive - only used for calculations, not logged
• Cost reports stored securely
• No external data transmission
• User can review before sharing with stakeholders

Example 1: ROI Calculation

calculate-roi

Output:

💰 Brad: Calculating ROI from pattern consolidation...

Team Context:
  - Developers: 8
  - Hourly rate: $150/hr
  - Patterns maintained: 176 → 32

📊 COST ANALYSIS:

BEFORE consolidation:
  176 patterns × 2 hrs/month × $150/hr = $52,800/month
  Annual cost: $633,600

AFTER consolidation:
  32 patterns × 2 hrs/month × $150/hr = $9,600/month
  Annual cost: $115,200

💵 SAVINGS:
  Monthly: $43,200
  Annual: $518,400
  3-year total: $1,555,200

🎯 ROI METRICS:
  Implementation cost: $15,000
  ROI ratio: 34.6x
  Breakeven: 0.35 months (10 days!)
  Year 1 net profit: $503,400

⚡ VELOCITY IMPACT:
  Estimated 5x faster feature development
  288 hours/month saved = 1.8 FTE equivalent

✅ Report saved: outputs/design-system/my-app/roi/roi-analysis.md
✅ Executive summary: outputs/design-system/my-app/roi/executive-summary.md

Brad says: Numbers don't lie. Show this to your boss.

Example 2: Executive Summary

# Design System ROI - Executive Summary

## Investment

**$15,000** (4 developer-weeks)

## Return

**$518,400/year** savings

## ROI

*34.6x return** on investment

## Breakeven

*10 days**

## Impact

- 81.8% pattern reduction (176 → 32)
- 5x velocity improvement
- 1.8 FTE equivalent time savings

*Recommendation**: Immediate approval. Payback in under 2 weeks.

Notes

• Default 2 hours/month per pattern for maintenance (conservative)
• Includes: debugging, updates, consistency fixes, code reviews
• Velocity multiplier (3-6x) based on industry research
• Implementation cost varies by team size and existing tech debt
• ROI improves over time as system matures
• Brad's estimates are conservative (actual savings often higher)
• Use this report to justify design system to stakeholders
• Recalculate ROI after Phase 2 migration to validate projections