@arthai/agents 1.0.0

package/dist/plugins/prime/skills/roi-calculator/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: roi-calculator
+description: "Calculate ROI for AI initiatives with sensitivity analysis. Usage: /roi-calculator <client-name> [--initiative <name>]"
+user-invocable: true
+arguments: "<client-name> [--initiative <name>]"
+---
+
+# AI Initiative ROI Calculator
+
+Calculate detailed return on investment for AI initiatives with cost modeling, benefit projections, cash flow analysis, and sensitivity testing. Produces defensible financial models for inclusion in proposals and executive presentations.
+
+## Prerequisites
+
+This skill requires completed discovery and opportunity mapping. Check for files at:
+```
+consulting-toolkit/clients/<client-name>/profile.md
+consulting-toolkit/clients/<client-name>/discovery/intake.md
+consulting-toolkit/clients/<client-name>/assessment/opportunity-matrix.md
+consulting-toolkit/clients/<client-name>/assessment/roadmap.md
+```
+
+If files are missing, redirect:
+```
+Required data not found for <client-name>. Run /client-discovery and /opportunity-map first.
+```
+
+## Step 1 — Financial Inputs
+
+If `--initiative` is specified, focus on that single initiative. Otherwise, model the top 3 initiatives by weighted score from the opportunity matrix.
+
+Use AskUserQuestion to gather financial inputs. Present all questions together for efficient answering:
+
+```
+Financial Inputs for ROI Modeling — please provide the following:
+
+1. What are the current annual costs for the processes these AI initiatives would affect?
+   (e.g., manual data entry costs $200K/year in labor, customer support costs $500K/year)
+
+2. How many FTEs (full-time equivalents) are currently dedicated to these processes?
+   (e.g., 4 FTEs for data entry, 8 FTEs for customer support)
+
+3. What is the average fully-loaded cost per FTE? (salary + benefits + overhead)
+   (If unknown, we'll use industry average of $85,000/year)
+
+4. What is the company's annual revenue?
+   (Used for revenue impact calculations)
+
+5. What are the current gross and operating margins?
+   (e.g., 60% gross, 15% operating — used for incremental revenue valuation)
+
+6. What is the current error/rework rate for these processes?
+   (e.g., 5% of orders have errors requiring rework, each costing $50 on average)
+
+7. What discount rate should we use for NPV? (default: 10%)
+
+8. Are there any known infrastructure costs or constraints?
+   (e.g., current cloud spend is $5K/month, data warehouse costs $2K/month)
+```
+
+For any unanswered questions, use these defaults:
+- Fully-loaded FTE cost: $85,000/year
+- Discount rate: 10%
+- Error rate: 3-5% (industry average)
+- Margins: Use industry averages based on the client's sector
+
+## Step 2 — Cost Model
+
+Build a detailed cost model for each initiative. All costs are estimated ranges (low-high).
+
+### 2a. Implementation Costs (One-time)
+
+```
+Implementation Cost Breakdown
+═══════════════════════════════════════════════════════════════
+Category                    Low Estimate    High Estimate
+───────────────────────────────────────────────────────────────
+Solution Design & Architecture   $X,XXX          $XX,XXX
+Data Preparation & Pipeline      $X,XXX          $XX,XXX
+Model Development / API Setup    $X,XXX          $XX,XXX
+Integration & Testing            $X,XXX          $XX,XXX
+User Training & Change Mgmt      $X,XXX          $XX,XXX
+Project Management               $X,XXX          $XX,XXX
+Contingency (15%)                $X,XXX          $XX,XXX
+───────────────────────────────────────────────────────────────
+Total Implementation             $XX,XXX         $XXX,XXX
+═══════════════════════════════════════════════════════════════
+```
+
+### 2b. Infrastructure Costs (Monthly recurring)
+
+```
+Monthly Infrastructure Costs
+═══════════════════════════════════════════════════════════════
+Category                    Low Estimate    High Estimate
+───────────────────────────────────────────────────────────────
+Cloud Compute (GPU/CPU)          $XXX            $X,XXX
+Data Storage & Transfer          $XXX            $X,XXX
+AI/ML Platform Licenses          $XXX            $X,XXX
+API Costs (if using 3rd party)   $XXX            $X,XXX
+Monitoring & Observability       $XXX            $XXX
+───────────────────────────────────────────────────────────────
+Total Monthly Infrastructure     $X,XXX          $X,XXX
+Annual Infrastructure            $XX,XXX         $XX,XXX
+═══════════════════════════════════════════════════════════════
+```
+
+### 2c. Training Costs (One-time + ongoing)
+
+```
+Training & Adoption Costs
+═══════════════════════════════════════════════════════════════
+Category                    One-time        Annual Ongoing
+───────────────────────────────────────────────────────────────
+End-user Training                $X,XXX          $X,XXX
+Technical Team Upskilling        $X,XXX          $X,XXX
+Documentation & Knowledge Base   $X,XXX          $XXX
+Change Management Program        $X,XXX          $X,XXX
+───────────────────────────────────────────────────────────────
+Total Training                   $XX,XXX         $X,XXX
+═══════════════════════════════════════════════════════════════
+```
+
+### 2d. Maintenance Costs (Annual recurring)
+
+```
+Annual Maintenance Costs
+═══════════════════════════════════════════════════════════════
+Category                    Low Estimate    High Estimate
+───────────────────────────────────────────────────────────────
+Model Retraining & Updates       $X,XXX          $XX,XXX
+Bug Fixes & Enhancements         $X,XXX          $XX,XXX
+Data Pipeline Maintenance        $X,XXX          $X,XXX
+Security & Compliance            $X,XXX          $X,XXX
+Vendor Management                $XXX            $X,XXX
+───────────────────────────────────────────────────────────────
+Total Annual Maintenance         $XX,XXX         $XX,XXX
+═══════════════════════════════════════════════════════════════
+```
+
+### Total Cost of Ownership (3-Year)
+
+```
+TCO = Implementation + (Infrastructure_Annual × 3) + Training_OneTime
+      + (Training_Ongoing × 3) + (Maintenance × 3)
+```
+
+## Step 3 — Benefit Model
+
+Quantify expected benefits for each initiative across four categories.
+
+### 3a. Time Savings
+
+```
+Time Savings Calculation
+═══════════════════════════════════════════════════════════════
+Process automated/augmented: [Name]
+Current FTEs on process:     [X]
+Hours/week per FTE on task:  [X]
+Automation rate:             [X]% (what % of work AI handles)
+Hours saved per week:        FTEs × Hours × Automation_Rate
+Annual hours saved:          Weekly_Hours × 52
+Value of time saved:         Annual_Hours × (FTE_Cost / 2080)
+═══════════════════════════════════════════════════════════════
+
+Annual Time Savings Value: $XXX,XXX
+```
+
+Note: Time savings does not always equal headcount reduction. Freed time may be redirected to higher-value work. Present both scenarios:
+- Conservative: 50% of time savings translates to cost reduction
+- Optimistic: Time savings redirected to revenue-generating activities
+
+### 3b. Error Reduction
+
+```
+Error Reduction Calculation
+═══════════════════════════════════════════════════════════════
+Current error/rework rate:       [X]%
+Current volume (transactions/yr): [X]
+Current cost per error:           $[X]
+Annual cost of errors:            Volume × Error_Rate × Cost_Per_Error
+AI-enabled error rate:            [X]% (typically 50-80% reduction)
+New annual error cost:            Volume × New_Rate × Cost_Per_Error
+═══════════════════════════════════════════════════════════════
+
+Annual Error Reduction Savings: $XXX,XXX
+```
+
+### 3c. Revenue Impact
+
+```
+Revenue Impact Calculation
+═══════════════════════════════════════════════════════════════
+Mechanism: [e.g., improved lead conversion, faster time-to-market,
+            better customer retention, new product/service]
+
+Current metric:       [X] (e.g., 2% conversion rate, 15% churn)
+Expected improvement: [X]% (e.g., +0.5% conversion, -3% churn)
+Revenue per unit:     $[X] (e.g., $500 average deal size)
+Annual volume:        [X] (e.g., 10,000 leads, 5,000 customers)
+═══════════════════════════════════════════════════════════════
+
+Incremental Annual Revenue: $XXX,XXX
+Profit Impact (at margin):  Incremental_Revenue × Operating_Margin
+```
+
+### 3d. Risk Reduction
+
+```
+Risk Reduction Calculation
+═══════════════════════════════════════════════════════════════
+Risk Category:           [e.g., compliance, fraud, downtime]
+Annual expected loss:     $[X] (probability × impact)
+AI-enabled reduction:    [X]% reduction in probability or impact
+═══════════════════════════════════════════════════════════════
+
+Annual Risk Reduction Value: $XX,XXX
+```
+
+### Total Annual Benefits
+
+```
+Total Annual Benefits = Time_Savings + Error_Reduction + Revenue_Impact_Profit + Risk_Reduction
+```
+
+## Step 4 — 12-Month Cash Flow Projection
+
+Build a month-by-month cash flow projection showing costs and benefits ramping up over time.
+
+Assumptions:
+- Implementation costs spread across Months 1-3
+- Infrastructure costs begin Month 1
+- Benefits ramp: Month 1-2 at 0%, Month 3 at 25%, Month 4-6 at 50%, Month 7-9 at 75%, Month 10-12 at 100%
+- Training costs in Months 1-2
+
+```
+12-Month Cash Flow Projection
+═══════════════════════════════════════════════════════════════════════════════════════════
+Month          1       2       3       4       5       6       7       8       9      10      11      12     TOTAL
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+COSTS
+Implementation ($XX)   ($XX)   ($XX)    -       -       -       -       -       -       -       -       -    ($XXX)
+Infrastructure ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)    ($X)   ($XX)
+Training       ($X)    ($X)     -       -       -       -       -       -       -       -       -       -    ($XX)
+Maintenance     -       -       -      ($X)     -       -      ($X)     -       -      ($X)     -       -    ($XX)
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+Total Costs    ($XX)   ($XX)   ($XX)   ($XX)   ($X)    ($X)    ($XX)   ($X)    ($X)    ($XX)   ($X)    ($X)  ($XXX)
+
+BENEFITS
+Time Savings     -       -     $X      $XX     $XX     $XX     $XX     $XX     $XX     $XX     $XX     $XX   $XXX
+Error Reduction  -       -     $X      $X      $X      $X      $XX     $XX     $XX     $XX     $XX     $XX   $XXX
+Revenue Impact   -       -      -      $X      $X      $X      $XX     $XX     $XX     $XX     $XX     $XX   $XXX
+Risk Reduction   -       -     $X      $X      $X      $X      $X      $X      $X      $X      $X      $X    $XX
+─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+Total Benefits   -       -     $XX     $XX     $XX     $XX     $XXX    $XXX    $XXX    $XXX    $XXX    $XXX  $XXX
+
+NET CASH FLOW  ($XX)   ($XX)   ($XX)   $XX     $XX     $XX     $XX     $XX     $XX     $XX     $XX     $XX   $XXX
+CUMULATIVE     ($XX)   ($XXX)  ($XXX)  ($XXX)  ($XX)   ($XX)   $XX     $XX     $XXX    $XXX    $XXX    $XXX
+═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+```
+
+Populate with actual calculated values. Use the base (expected) case.
+
+## Step 5 — Key Financial Metrics
+
+Calculate and present three key financial metrics:
+
+### 5a. Payback Period
+
+```
+Payback Period Calculation
+═══════════════════════════════════════════════════════════════
+Method: Identify the month where cumulative cash flow turns positive
+
+From the 12-month projection above:
+  Cumulative turns positive in Month [X]
+
+Payback Period: [X] months
+═══════════════════════════════════════════════════════════════
+```
+
+### 5b. 3-Year Net Present Value (NPV)
+
+```
+NPV Calculation
+═══════════════════════════════════════════════════════════════
+Discount Rate (r): 10% annually (0.833% monthly)
+
+         36
+NPV = Σ  (Cash_Flow_t / (1 + r/12)^t)
+        t=1
+
+Where:
+  Year 1 cash flows: from 12-month projection above
+  Year 2 cash flows: Annual benefits at 100% - Annual costs (infra + maintenance + training ongoing)
+  Year 3 cash flows: Same as Year 2 (assume stable state)
+
+Year 1 Net Cash Flow:  $XXX,XXX (from projection)
+Year 2 Net Cash Flow:  $XXX,XXX (full benefits - recurring costs)
+Year 3 Net Cash Flow:  $XXX,XXX (full benefits - recurring costs)
+
+3-Year NPV at 10%: $XXX,XXX
+═══════════════════════════════════════════════════════════════
+```
+
+### 5c. Internal Rate of Return (IRR)
+
+```
+IRR Calculation
+═══════════════════════════════════════════════════════════════
+IRR is the discount rate that makes NPV = 0
+
+Using the 36-month cash flow series:
+  Solve for r where:
+         36
+    0 = Σ  (Cash_Flow_t / (1 + r/12)^t)
+        t=1
+
+Estimated IRR: [X]% annually
+
+Interpretation:
+  IRR > Discount Rate (10%) → Project creates value
+  IRR > WACC → Project exceeds cost of capital
+═══════════════════════════════════════════════════════════════
+```
+
+Note: Since we cannot run iterative solvers, estimate IRR by testing discount rates (15%, 25%, 50%, 75%, 100%, 150%, 200%) and interpolating where NPV crosses zero.
+
+### Summary Metrics Table
+
+```
+Financial Summary
+═══════════════════════════════════════════════════════════════
+Metric                          Value
+───────────────────────────────────────────────────────────────
+Total Investment (Year 1)       $XXX,XXX
+Annual Benefits (Steady State)  $XXX,XXX
+Payback Period                  X months
+3-Year NPV (at 10%)            $XXX,XXX
+IRR                             XX%
+3-Year ROI                      XXX%
+═══════════════════════════════════════════════════════════════
+
+3-Year ROI = (3-Year Total Benefits - 3-Year Total Costs) / 3-Year Total Costs × 100
+```
+
+## Step 6 — Sensitivity Analysis
+
+Test how results change across different assumption scenarios. Build a 3x3 matrix combining implementation scenarios with benefit scenarios.
+
+### Scenario Definitions
+
+**Cost Scenarios:**
+- **Best Case**: Implementation comes in 20% under budget, infrastructure costs 30% lower than expected
+- **Expected Case**: Base estimates from cost model
+- **Worst Case**: Implementation costs 40% over budget, infrastructure costs 50% higher, 2-month delay
+
+**Benefit Scenarios:**
+- **Optimistic**: Benefits 30% higher than base, ramp-up 2 months faster
+- **Base**: Base estimates from benefit model
+- **Pessimistic**: Benefits 40% lower than base, ramp-up 3 months slower
+
+### 3x3 Sensitivity Matrix
+
+```
+Sensitivity Analysis — 3-Year NPV
+═══════════════════════════════════════════════════════════════════════
+                    Optimistic          Base              Pessimistic
+                    Benefits            Benefits          Benefits
+───────────────────────────────────────────────────────────────────────
+Best Case       $XXX,XXX            $XXX,XXX            $XXX,XXX
+Costs           (IRR: XX%)          (IRR: XX%)          (IRR: XX%)
+                Payback: X mo       Payback: X mo       Payback: X mo
+
+Expected        $XXX,XXX            $XXX,XXX            $XXX,XXX
+Costs           (IRR: XX%)          (IRR: XX%)          (IRR: XX%)
+                Payback: X mo       Payback: X mo       Payback: X mo
+
+Worst Case      $XXX,XXX            $XXX,XXX            $XX,XXX
+Costs           (IRR: XX%)          (IRR: XX%)          (IRR: X%)
+                Payback: X mo       Payback: XX mo      Payback: XX mo
+───────────────────────────────────────────────────────────────────────
+
+Best scenario:  Best costs + Optimistic benefits  → NPV $XXX,XXX
+Base scenario:  Expected costs + Base benefits     → NPV $XXX,XXX
+Worst scenario: Worst costs + Pessimistic benefits → NPV $XX,XXX
+═══════════════════════════════════════════════════════════════════════
+```
+
+### Breakeven Analysis
+
+```
+Breakeven Analysis
+═══════════════════════════════════════════════════════════════
+Question: What is the minimum benefit level needed to break even?
+
+Total 3-Year Costs (Expected): $XXX,XXX
+Monthly benefits needed for breakeven: $XX,XXX
+This represents XX% of base case monthly benefits
+
+Conclusion: The initiative breaks even even if benefits are [X]% lower
+than projected, providing a [X]% margin of safety.
+═══════════════════════════════════════════════════════════════
+```
+
+### Key Assumptions & Risks
+
+List the top 5 assumptions that most affect the model, with the impact if the assumption is wrong:
+
+| # | Assumption | Impact if Wrong | Likelihood | Mitigation |
+|---|---|---|---|---|
+| 1 | [e.g., 70% automation rate] | NPV drops by $XX,XXX per 10% decrease | Medium | Pilot test before full rollout |
+| 2 | [e.g., data is ML-ready] | 2-month delay, $XX,XXX additional prep | High if data readiness < 3 | Data audit in Wave 1 |
+| 3 | ... | ... | ... | ... |
+
+## Step 7 — Output Files
+
+Create the following files in `consulting-toolkit/clients/<client-name>/`:
+
+### 7a. `assessment/roi-model.md`
+
+Contains:
+- Financial inputs summary (Step 1)
+- Full cost model with all categories (Step 2)
+- Full benefit model with calculations (Step 3)
+- 12-month cash flow projection table (Step 4)
+- Key financial metrics: Payback, NPV, IRR, ROI (Step 5)
+- All formulas and calculations shown transparently
+
+### 7b. `assessment/sensitivity-analysis.md`
+
+Contains:
+- Scenario definitions (Step 6)
+- 3x3 sensitivity matrix (Step 6)
+- Breakeven analysis (Step 6)
+- Key assumptions and risks table (Step 6)
+- Recommendation based on risk tolerance:
+  - Conservative recommendation (based on worst-case)
+  - Balanced recommendation (based on expected case)
+  - Aggressive recommendation (based on best case)
+
+After saving, inform the user:
+```
+ROI model generated for <client-name>.
+
+Key Results (Base Case):
+  - Total Investment: $XXX,XXX
+  - Annual Benefits:  $XXX,XXX
+  - Payback Period:   X months
+  - 3-Year NPV:      $XXX,XXX
+  - IRR:             XX%
+
+Files:
+  assessment/roi-model.md
+  assessment/sensitivity-analysis.md
+
+To include these numbers in a proposal, run:
+  /pitch-generator <client-name> --format proposal
+```
+
+## Notes
+
+- All financial projections are estimates — clearly label them as such in all outputs
+- Use conservative estimates by default — it's better to under-promise and over-deliver
+- Show all calculations transparently — the client should be able to verify every number
+- If the client hasn't provided specific financial data, use industry benchmarks and clearly mark assumptions
+- Currency format: USD with thousands separators and no decimal cents (e.g., $125,000 not $125,000.00)
+- Always present ranges rather than point estimates for key metrics
+- If IRR is negative or payback period exceeds 24 months in the expected case, flag the initiative as high-risk and recommend revisiting the scope or approach
+- The model intentionally excludes intangible benefits (brand value, employee satisfaction) — mention these qualitatively but do not assign dollar values