jumpstart-mode 1.1.13 → 1.1.14

package/.github/skills/requirements/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: requirements
+description: Structured techniques for eliciting, analyzing, and documenting software requirements from stakeholders, reducing ambiguity and missed scope.
+---
+
+# Requirements Elicitation & Analysis
+
+This skill provides structured workflows for gathering, analyzing, and documenting software requirements. Use it when scoping a project, conducting stakeholder interviews, or validating completeness of a PRD.
+
+## Elicitation Techniques
+
+### Stakeholder Interview Script
+
+Use this 5-step structure for requirement-gathering sessions:
+
+1. **Context Setting** (2 min): "We're exploring [domain]. I'll ask questions to understand your needs. There are no wrong answers."
+2. **Current State** (10 min): "Walk me through how you do [task] today, step by step."
+3. **Pain Points** (10 min): "What frustrates you most? Where do you lose time? What workarounds have you built?"
+4. **Ideal State** (10 min): "If you had a magic wand, what would change? What does success look like?"
+5. **Constraints** (5 min): "What must not change? What are the hard limits (budget, timeline, compliance)?"
+
+Record: Raw notes → distill into user stories within 24h.
+
+### Requirement Categories Checklist
+
+For every feature, verify coverage across:
+
+| Category | Key Questions |
+|----------|--------------|
+| Functional | What does the system DO? |
+| Data | What does it STORE and RETRIEVE? |
+| Interface | How do users/systems INTERACT with it? |
+| Performance | How FAST must it respond? At what SCALE? |
+| Security | Who can ACCESS what? What's SENSITIVE? |
+| Compliance | What REGULATIONS apply? |
+| Operational | How is it DEPLOYED, MONITORED, BACKED UP? |
+| Usability | Who uses it? What's their SKILL LEVEL? |
+
+## Analysis Techniques
+
+### Ambiguity Detection
+
+Flag requirements containing these words — they need clarification:
+
+- **"should"** → Is it required or optional?
+- **"etc."** → What exactly is included?
+- **"appropriate"** → What criteria define appropriateness?
+- **"user-friendly"** → What specific UX standards?
+- **"fast"** → What latency threshold (P50, P95, P99)?
+- **"scalable"** → What load targets (users, requests/sec, data volume)?
+- **"secure"** → What threat model? What compliance standard?
+
+### MoSCoW Prioritization
+
+For each requirement, assign:
+
+| Priority | Meaning | Rule |
+|----------|---------|------|
+| **Must** | Non-negotiable for launch | Blocks release if missing |
+| **Should** | Important but workaround exists | Include if time permits |
+| **Could** | Desirable enhancement | Only after all Shoulds done |
+| **Won't** | Explicitly out of scope (this release) | Documented to prevent scope creep |
+
+### User Story Quality Gate (INVEST)
+
+Every user story must pass:
+
+- **I**ndependent — Can be built and delivered alone
+- **N**egotiable — Details can flex during implementation
+- **V**aluable — Delivers user or business value
+- **E**stimable — Team can estimate effort
+- **S**mall — Completable in one sprint/iteration
+- **T**estable — Has clear acceptance criteria
+
+## Documentation Template
+
+### Requirement Entry Format
+
+```
+**REQ-[ID]:** [One-sentence description]
+- **Priority:** Must / Should / Could / Won't
+- **Source:** [Stakeholder name/role, date]
+- **Acceptance Criteria:**
+  - Given [context], when [action], then [outcome]
+  - Given [context], when [action], then [outcome]
+- **Dependencies:** [REQ-IDs or "None"]
+- **Open Questions:** [Any unresolved ambiguities]
+```
+
+### Traceability Matrix
+
+Maintain a requirements → specs → code traceability:
+
+| REQ ID | Description | Spec Section | Implementation | Test Case | Status |
+|--------|-------------|--------------|----------------|-----------|--------|
+| REQ-001 | User login | PRD §3.1 | `src/auth/` | `test/auth.test.js` | Done |

package/.github/skills/roi-calculator-builder/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: roi-calculator-builder
+description: Build a defensible ROI and TCO model for a specific AI use case, with explicit benefit drivers, full cost stack, sensitivity analysis, and risk-adjusted outcomes. Use this whenever the user asks for an ROI, business case, value case, payback, NPV, TCO, cost model, financial justification, breakeven analysis, or sensitivity analysis tied to a Jump Start, AI Innovation Pod, agentic workflow, RAG assistant, copilot rollout, or any AI build. Trigger even when the request is phrased as "is this worth it", "justify the spend", "what is the business case", "build the value story", "how do we defend the price", or when a client, CFO, or steering committee wants a number that survives scrutiny. Do not produce generic ROI math — always tie benefits to a named workflow, user population, baseline metric, and AI-specific cost stack including model, eval, governance, and adoption costs.
+---
+
+# ROI Calculator Builder
+
+Use this skill to turn a specific AI use case into a defensible ROI and TCO model that an executive sponsor, CFO partner, or steering committee can actually defend.
+
+This skill is built for AI Innovation Pod and Jump Start work first. The output should be credible enough to support proposal review, internal funding decisions, and post-pilot scaling decisions — not generic "AI saves you 30 percent" marketing math.
+
+## What this skill is for
+
+Apply this skill when the user asks for any of the following:
+
+- an ROI, business case, or value case for a specific AI use case
+- a TCO model that includes AI-specific costs (model usage, eval, observability, governance, adoption)
+- a payback period, NPV, IRR, or breakeven analysis for an AI build
+- a sensitivity analysis or "what has to be true" analysis around an AI investment
+- a risk-adjusted ROI that accounts for accuracy, adoption, and dependency risk
+- financial justification language for a proposal, SOW, or steering committee
+- a comparison of "do nothing", "buy", "build with Pod", and "scale" scenarios
+
+Do not produce a generic spreadsheet. Always anchor benefits to a named workflow, user population, baseline metric, and a defensible time horizon.
+
+## Core objective
+
+Produce an ROI/TCO package that:
+
+1. names the specific use case, workflow, and user population
+2. states the financial frame (horizon, currency, discount rate, fiscal alignment)
+3. quantifies benefits using baseline → uplift → realization curve, not single numbers
+4. captures the full AI cost stack (build, run, model, eval, governance, adoption)
+5. shows ROI, payback, and NPV with low / base / high scenarios
+6. runs a sensitivity analysis on the variables that actually move the answer
+7. applies a risk adjustment for accuracy, adoption, and dependency risk
+8. ends with a defensible narrative and the questions still needed to tighten the model
+
+## Bundled resources
+
+Use the bundled resources to keep outputs consistent and defensible:
+
+- Read `references/roi-methodology.md` for the standard reasoning order, formulas (ROI, payback, NPV, IRR), and benefit-realization curve logic.
+- Read `references/ai-benefit-categories.md` when quantifying benefits — it covers labor productivity, throughput, quality / error reduction, revenue lift, risk avoidance, and capacity reallocation, with how to baseline each one.
+- Read `references/ai-cost-categories.md` for the full TCO stack specific to AI (build, model usage, retrieval / vector, eval and observability, governance and RAI, change management, and run-rate).
+- Read `references/sensitivity-analysis-guide.md` for one-way, two-way, tornado, and Monte-Carlo-lite patterns and which variables to flex first.
+- Read `references/risk-adjusted-roi.md` for accuracy-adjusted, adoption-adjusted, and dependency-adjusted ROI patterns.
+
+Use the bundled templates when the user wants file-shaped outputs:
+
+- `templates/roi-model-template.md` for the narrative business-case package
+- `templates/roi-worksheet-template.csv` for the line-item benefit and cost worksheet
+
+See `examples/example-knowledge-assistant-roi.md` for a worked example of the full output package.
+
+## Intake checklist
+
+Before modeling, establish as much of this as the prompt allows. If a missing input materially changes the answer, ask one short clarifying question. Otherwise proceed with a clearly labeled assumption.
+
+- **Use case**: the specific workflow and decision being supported (not "AI for HR" — "first-line HR policy answers for ~12,000 US employees")
+- **User population**: number of users, frequency of the workflow, current cycle time
+- **Baseline**: today's cost, throughput, error rate, or revenue contribution for that workflow
+- **Target uplift hypothesis**: time saved, quality lift, revenue lift, or risk avoided per event
+- **Realization curve**: when adoption ramps and benefits start landing
+- **Time horizon**: typically 3 years for AI cases; sometimes 1 year for pilots
+- **Discount rate**: client WACC if known, otherwise a labeled placeholder (often 8–12 percent)
+- **Currency and fiscal calendar**
+- **Cost inputs**: Pod or build cost, model and infra run-rate, eval and governance, change management
+- **Risk posture**: how the client thinks about accuracy, adoption, and dependency risk
+
+## Required reasoning order
+
+Follow this order every time. The order is what makes the model defensible.
+
+1. **Frame the use case**. State the workflow, the user population, the decision being supported, and the time horizon.
+2. **Establish the baseline**. Quantify the current cost, throughput, error rate, or revenue for that workflow with a labeled source (interview, log data, industry benchmark, hypothesis).
+3. **Define the AI intervention**. State what the AI actually does in the workflow and what step or outcome changes.
+4. **Quantify benefits per category**. For each benefit category, write benefit = users × frequency × baseline metric × uplift × realization factor. Keep each line traceable.
+5. **Build the cost stack**. Capture build cost, model and retrieval run-rate, eval and observability, governance and RAI, change management and training, and ongoing run-rate.
+6. **Compute headline metrics**. ROI percent, payback period, NPV, and (if asked) IRR — for low, base, and high scenarios.
+7. **Run sensitivity**. Flex the 3–5 variables that actually move the answer. Show a tornado-style ranking.
+8. **Apply risk adjustment**. Discount benefits by accuracy, adoption, and dependency risk and show the adjusted ROI.
+9. **Compare scenarios**. At minimum: do-nothing baseline vs. proposed build. If the user asks, add buy / SaaS and scale-up scenarios.
+10. **Write the defensible narrative**. State the headline number, the assumptions it depends on, the variables that could break it, and the next discovery questions to tighten it.
+
+## Default assumptions for AI Innovation Pod work
+
+Unless the prompt clearly contradicts them, assume:
+
+- the build is a focused MVP or pilot delivered by a small senior Pod, not enterprise-wide industrialization
+- benefits do not start at month 1 — apply a realization curve (typical: 0 percent in the build window, ramp to ~70 percent by end of year 1, ~90–100 percent by year 2)
+- model and infra run-rate is non-trivial and grows with usage — never zero it out
+- eval, observability, and governance are recurring costs, not one-time
+- change management and adoption effort is part of TCO, even if the client has not budgeted for it
+- the first model is not the last model — assume at least one model or pricing change inside the horizon
+
+## Output quality rules
+
+- Prefer ranges (low / base / high) over single-point certainty.
+- Every benefit line must have a baseline source label (`logged`, `interview`, `benchmark`, `hypothesis`).
+- Never claim labor savings as cash savings unless the client has confirmed they will actually reduce headcount or backfill. Default to "capacity reallocated" framing and flag the distinction.
+- Never zero out model, eval, governance, or adoption costs to make ROI look better.
+- State the discount rate, currency, horizon, and fiscal alignment explicitly.
+- Show the math. The reader must be able to retrace any benefit or cost line.
+- If the prompt is early-stage and ambiguous, widen the range and call out what discovery would tighten it — do not fake precision.
+- Avoid vendor hype framing. The audience is a CFO partner or steering committee, not a marketing page.
+
+## Required output package
+
+For substantial requests, produce these sections unless the user asks for a narrower deliverable.
+
+### Business case framing
+
+Use case, workflow, user population, time horizon, currency, discount rate, and confidence level.
+
+### Baseline
+
+Today's cost, throughput, error rate, or revenue for the affected workflow, with sources labeled.
+
+### AI intervention
+
+What the AI does in the workflow and what step or outcome changes.
+
+### Benefit model
+
+A line-item table of benefit drivers with users × frequency × baseline × uplift × realization, totaled by year and by category.
+
+### Cost stack (TCO)
+
+Build cost, model and retrieval run-rate, eval and observability, governance and RAI, change management, and ongoing run-rate, totaled by year.
+
+### Headline metrics
+
+ROI percent, payback period, NPV, and optionally IRR — for low, base, and high scenarios.
+
+### Sensitivity analysis
+
+Tornado-style ranking of the 3–5 variables that move the answer most, with the range tested.
+
+### Risk-adjusted ROI
+
+Accuracy-adjusted, adoption-adjusted, and dependency-adjusted view of the base case.
+
+### Scenario comparison
+
+At minimum do-nothing vs. proposed. Add buy / SaaS and scale-up scenarios when asked.
+
+### Defensible narrative
+
+A short paragraph the user can drop into a proposal, steering committee deck, or funding memo. Includes the headline number, the assumptions it depends on, and what would break it.
+
+### Open questions and next discovery
+
+The handful of inputs that, if confirmed, would meaningfully tighten the model.
+
+## File-shaped outputs
+
+When the user wants reusable artifacts, or when you are saving files in a workspace, emit separate sibling files instead of stuffing everything into one response:
+
+- `roi-model.md` for the narrative package (mirrors `templates/roi-model-template.md`)
+- `roi-worksheet.csv` for the line-item benefit and cost worksheet (mirrors `templates/roi-worksheet-template.csv`)
+
+If the prompt is narrower, emit only what applies, but still favor reusable files over long fenced blocks.
+
+## Common failure modes to avoid
+
+- Quoting a generic "AI saves 30 percent of analyst time" without a named workflow or baseline.
+- Treating labor hours saved as automatic cash savings.
+- Ignoring model, eval, governance, or change-management costs in TCO.
+- Showing one number instead of a range, or hiding sensitivity behind a single point estimate.
+- Claiming benefits start at month 1.
+- Failing to label sources and assumptions, so the reader cannot retrace the math.
+- Comparing AI build cost to a do-nothing baseline of zero, instead of the real cost of the current process.
+
+## When the user asks for less
+
+If the user only wants a quick directional ROI, produce a compressed version with: framing, baseline, top 2–3 benefit drivers, simplified cost stack, base-case ROI and payback, and the top 3 sensitivity variables. Still label assumptions and still avoid generic numbers.

package/.github/skills/roi-calculator-builder/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "roi-calculator-builder",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Build me a defensible 3-year ROI and TCO model for an internal HR policy assistant deployed in Microsoft Teams for ~12,000 US employees. The HR Service Desk handles ~6,400 first-line tickets per month at ~11 minutes per ticket and a $52 loaded hourly rate. We're scoping a 10-week AI Innovation Pod MVP. I need something I can defend in a steering committee — include a sensitivity analysis and a risk-adjusted view, not just a headline number.",
+      "expected_output": "A full ROI/TCO package with use-case framing, baseline with sources, intervention description, line-item benefit model with categories and sources, full AI cost stack including model, eval, governance, and adoption costs, low/base/high headline metrics including ROI, payback, and NPV, sensitivity analysis with a tornado-style ranking, risk-adjusted ROI, scenario comparison, defensible narrative, and next-discovery questions.",
+      "files": [],
+      "expectations": [
+        "The output names a specific workflow, user population, time horizon, currency, and discount rate (with the discount rate labeled if assumed).",
+        "The output includes a baseline section with at least one source label per line (logged, interview, benchmark, or hypothesis).",
+        "The benefit model breaks benefits into named lines using a users x frequency x baseline x uplift x realization pattern, not a single blended percentage.",
+        "The cost stack includes one-time build cost AND recurring run-rate costs, and the run-rate explicitly covers model usage, eval/observability, governance/RAI, and change management.",
+        "The output presents ROI, payback, and NPV as a low/base/high range rather than a single point estimate.",
+        "The output includes a sensitivity analysis that ranks at least 3 variables by impact on ROI, with adoption rate appearing as one of the top variables.",
+        "The output includes a risk-adjusted ROI view with explicit accuracy, adoption, and dependency discounts applied to benefits (not costs).",
+        "The output distinguishes labor capacity reclaimed from cash savings or flags that distinction explicitly.",
+        "The output ends with a defensible narrative paragraph and a list of next-discovery questions tied to the top sensitivity variables."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Quick directional ROI please. Use case: a sales-rep copilot that drafts first-pass account research and meeting prep notes for ~400 enterprise reps. We don't have telemetry yet, just a hypothesis that it could save each rep ~3 hours a week. Pod build estimate is roughly $450K for the MVP. CFO wants to know if this is worth pursuing past discovery. Don't give me a generic spreadsheet — tie the math to the workflow and tell me what would have to be true.",
+      "expected_output": "A compressed but still defensible ROI view: framing, baseline (with hypothesis labels), top 2-3 benefit drivers, simplified cost stack including AI run-rate, base-case ROI and payback, top 3 sensitivity variables, and a 'what has to be true' / breakeven framing. Should not present hours saved as cash automatically.",
+      "files": [],
+      "expectations": [
+        "The output ties the benefit math to the named workflow (account research, meeting prep) and a labeled baseline rather than a generic productivity percentage.",
+        "Hypothesis-based inputs (the 3 hours per week) are explicitly labeled as hypothesis or unvalidated.",
+        "The output does not convert hours saved directly to cash without flagging the capacity-vs-cash distinction.",
+        "The cost stack includes ongoing AI run-rate (model, eval, governance) in addition to the $450K build cost.",
+        "The output includes either a sensitivity ranking or a 'what has to be true' / breakeven framing for the top 2-3 variables.",
+        "The output gives a clear directional answer ('proceed' / 'tighten before proceeding' / 'kill') tied to specific assumptions, not generic AI hype."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Compare three scenarios for a claims-triage AI use case in a regional P&C insurer: (1) do nothing, (2) buy a SaaS triage product, (3) build with an AI Innovation Pod. Volumes: ~22,000 claims/month, current avg triage cycle 38 hours, ~$210K/month in current operations cost. Regulated industry — model risk review (SR 11-7-style) is required. I need TCO across all three, payback, and a risk-adjusted recommendation. Time horizon 3 years.",
+      "expected_output": "A three-scenario TCO and ROI comparison with do-nothing as the real baseline (continued cost of current process), buy and build with full TCO stacks, payback and NPV per scenario, risk-adjusted view that accounts for model risk review and regulatory dependencies, and a defensible recommendation.",
+      "files": [],
+      "expectations": [
+        "The do-nothing scenario shows the continued cost of the current process, not a baseline of zero.",
+        "Each of buy and build has a TCO stack that includes ongoing run-rate, not just an upfront price.",
+        "The output names model risk review / SR 11-7-style governance as a recurring cost line in the build scenario and as a dependency.",
+        "The dependency risk factor in the risk-adjusted view explicitly references the regulatory governance gates.",
+        "The output reports ROI, payback, and NPV for each scenario rather than choosing a single metric.",
+        "The recommendation is specific (which scenario, under which conditions) and tied to named assumptions, not generic."
+      ]
+    }
+  ]
+}

package/.github/skills/roi-calculator-builder/examples/example-knowledge-assistant-roi.md

@@ -0,0 +1,142 @@
+# Worked Example — Internal HR Knowledge Assistant ROI
+
+A worked example showing the full output package the skill should produce. Numbers are illustrative, not benchmarks. The point is the structure, the source labels, and the way sensitivity and risk adjustment are handled.
+
+---
+
+## Business case framing
+
+- **Use case**: First-line HR policy answers (benefits, leave, payroll basics) for US-based employees, surfaced inside Microsoft Teams.
+- **User population**: ~12,000 US employees; HR Service Desk team of 28 agents handles ~6,400 first-line tickets/month today.
+- **Time horizon**: 3 years
+- **Currency**: USD
+- **Discount rate**: 10% (placeholder pending client WACC confirmation)
+- **Fiscal calendar alignment**: client FY (July–June)
+- **Confidence level**: post-Jump Start, pre-pilot
+
+## Baseline
+
+| Baseline metric | Value | Source |
+|---|---|---|
+| First-line HR tickets per month | 6,400 | logged (ServiceNow Q3 export) |
+| Average handle time per ticket | 11 minutes | logged |
+| First-line resolution rate | 72% | logged |
+| Loaded hourly rate (HR agent) | $52 | benchmark (client benefits + comp ratio) |
+| Escalation cost (avg downstream agent + specialist time) | $38/escalation | interview (HRBP lead) |
+
+## AI intervention
+
+Employee asks a policy question in Teams. A retrieval-augmented assistant returns an answer grounded in the current HR policy library, with a citation and an "Open a ticket" fallback. The assistant does not change the escalation workflow, the case-management system, or the policy authoring process.
+
+What changes: deflection of routine first-line tickets, faster self-service.
+What does not change: complex cases, payroll exceptions, leave-of-absence approvals, anything requiring HRBP judgment.
+
+## Benefit model
+
+| Benefit line | Category | Y1 | Y2 | Y3 | Source | Notes |
+|---|---|---|---|---|---|---|
+| Ticket deflection — capacity reclaimed | capacity | $410K | $620K | $660K | hypothesis | reallocated to HRBP advisory work; not cash |
+| Reduced escalations (cleaner front door) | cash | $90K | $145K | $155K | interview | net of new misroute risk |
+| Employee time saved (self-service) | capacity | $260K | $400K | $425K | hypothesis | reclaimed manager + employee time |
+| Compliance miss avoidance | risk | $50K | $75K | $80K | benchmark | probabilistic; not in headline |
+
+**Total benefits by year**: Y1 $810K / Y2 $1.24M / Y3 $1.32M
+**Cash-only subtotal**: Y1 $90K / Y2 $145K / Y3 $155K (excluding capacity and risk)
+
+## Cost stack (TCO)
+
+| Cost line | Y0 | Y1 | Y2 | Y3 | Source |
+|---|---|---|---|---|---|
+| Discovery / Jump Start | $45K | — | — | — | quoted |
+| Pod build (10-week MVP) | $385K | — | — | — | bottom-up estimate |
+| Data prep (policy library cleanup, golden set) | $40K | — | — | — | hypothesis |
+| Integration (Teams, identity, ServiceNow handoff) | $55K | — | — | — | estimate |
+| Initial RAI / security review | $30K | — | — | — | interview |
+| Initial change management | $40K | — | — | — | hypothesis |
+| Model usage | — | $48K | $72K | $78K | hypothesis (~85K prompts/mo @ ~3.5K tokens) |
+| Vector / retrieval (Azure AI Search) | — | $18K | $22K | $24K | benchmark |
+| Hosting / orchestration (App Service + Functions) | — | $22K | $26K | $28K | benchmark |
+| Eval / observability | — | $35K | $30K | $32K | hypothesis |
+| Governance / RAI run-rate | — | $25K | $25K | $30K | interview |
+| Support / operations | — | $40K | $45K | $48K | hypothesis |
+| Change management run-rate | — | $30K | $20K | $20K | hypothesis |
+| Licensing (M365 Copilot adjacent, Foundry) | — | $20K | $24K | $28K | quoted |
+| Reserve for model/pricing change (~15%) | — | $24K | $30K | $33K | assumption |
+| **Total** | **$595K** | **$262K** | **$294K** | **$321K** |
+
+## Headline metrics
+
+| Metric | Low | Base | High |
+|---|---|---|---|
+| 3-year ROI (all benefit categories) | 65% | 175% | 295% |
+| 3-year ROI (cash + capacity, excluding risk-avoidance) | 50% | 155% | 270% |
+| Payback period | 22 months | 14 months | 9 months |
+| NPV @ 10% | $0.6M | $1.9M | $3.4M |
+
+> **Base case**: 3-year ROI of 175% (155% if risk-avoidance benefits are excluded), payback in 14 months, NPV of $1.9M at a 10% discount rate.
+
+## Sensitivity analysis
+
+| Variable | Low | Base | High | ROI at low | ROI at high | Δ ROI |
+|---|---|---|---|---|---|---|
+| Adoption rate | 30% | 55% | 75% | 65% | 260% | 195pp |
+| Time saved per ticket (deflection equivalent) | 6 min | 9 min | 12 min | 95% | 240% | 145pp |
+| Realization Y1 | 40% | 55% | 70% | 110% | 215% | 105pp |
+| Token volume / user / month | base × 0.7 | base | base × 1.5 | 190% | 145% | 45pp |
+| Loaded hourly rate | $44 | $52 | $60 | 130% | 215% | 85pp |
+
+**Tornado**: Adoption rate dominates. Time saved per ticket and realization curve are the next two. Token volume and hourly rate are second-order.
+
+**Breakeven statements**:
+
+- Adoption rate must reach at least ~28% of eligible employees for the case to clear breakeven over the 3-year horizon at a 10% discount rate.
+- If realization in Y1 falls below ~35%, payback slips outside 24 months.
+
+## Risk-adjusted ROI
+
+Discounts applied to benefit lines:
+
+- Accuracy factor: 0.92 (assumed first-pass answer accuracy on a representative eval set)
+- Adoption factor: 0.65 (post-rollout sustained adoption; comparable internal Copilot Studio deployment ran 60–70%)
+- Dependency factor: 0.15 (policy library ownership clean; ServiceNow handoff requires owner confirmation)
+
+| Metric | Base case | Risk-adjusted | Drivers |
+|---|---|---|---|
+| 3-yr ROI | 175% | 95% | 0.92 × 0.65 × 0.85 = 0.508 effective benefit factor |
+| Payback | 14 months | 19 months | same |
+| NPV @ 10% | $1.9M | $0.7M | same |
+
+The risk-adjusted case still clears breakeven inside the horizon. That is the strongest defensible sentence in the business case.
+
+## Scenario comparison
+
+| Scenario | 3-yr cost | 3-yr benefit (base) | Net | Notes |
+|---|---|---|---|---|
+| Do nothing | $0 incremental | $0 | $0 | HR Service Desk continues at current cost; ticket volume trending +6% YoY |
+| Proposed Pod build | $1.47M | $3.37M | $1.90M | base case |
+| Buy SaaS HR copilot | $1.10M | $2.40M (assumed lower fit) | $1.30M | faster start, lower control of policy grounding, content fit unknown |
+| Scale-up after pilot | + $0.8M | + $2.0M | + $1.2M | requires successful pilot exit on accuracy and adoption |
+
+## Defensible narrative
+
+> A Pod-delivered HR knowledge assistant for ~12,000 US employees produces a base-case 3-year ROI of 175% with 14-month payback (NPV $1.9M at 10%). After accuracy, adoption, and dependency discounts the case still clears breakeven inside the horizon at 95% ROI and 19-month payback. The case depends most on adoption (must clear ~28% to break even) and on Y1 realization. The largest opportunities to tighten the model are validating adoption with a comparable internal rollout, running an accuracy eval on a representative policy-question sample, and confirming the ServiceNow handoff owner. We recommend proceeding with a 10-week MVP, a defined pilot exit-criteria gate, and a quarterly value-tracking review against the assumptions register.
+
+## Open questions and next discovery
+
+1. Adoption assumption — pull adoption telemetry from the comparable internal Copilot Studio rollout.
+2. Accuracy floor — run a 200-question eval against current draft policy library; target ≥90% first-pass accuracy.
+3. Capacity-to-cash conversion — confirm with HR leadership whether reclaimed agent capacity will be redirected (capacity) or partially shed (cash).
+4. ServiceNow handoff owner — name the integration owner and confirm scope of the handoff.
+5. Token pricing — confirm Foundry pricing tier with sourcing and lock the assumption date.
+
+## Appendix: assumptions register (extract)
+
+| Assumption | Value | Source label | Sensitivity-tested? |
+|---|---|---|---|
+| Discount rate | 10% | placeholder pending WACC | no |
+| Loaded hourly rate (HR agent) | $52 | benchmark | yes |
+| Token price per million | $-- (Foundry tier as of Apr 2026) | vendor pricing | yes (via token volume) |
+| Adoption rate | 55% base | hypothesis | yes |
+| Accuracy floor | 92% | hypothesis | yes |
+| Realization Y1 | 55% | assumption | yes |
+| Dependency risk factor | 0.15 | judgment | yes |

package/.github/skills/roi-calculator-builder/references/ai-benefit-categories.md

@@ -0,0 +1,101 @@
+# AI Benefit Categories
+
+Use this reference when quantifying benefits. Each category includes how to baseline, how to model uplift, and the trap to avoid.
+
+Every benefit line should follow:
+
+`benefit = users × frequency × baseline metric × uplift × realization × (currency conversion)`
+
+## 1. Labor productivity (time saved)
+
+**What it is**: Reduction in time per task for a defined user population.
+
+**Baseline**: Tasks per user per period, current minutes per task. Source from logs, time-and-motion studies, or SME interviews.
+
+**Uplift**: Minutes saved per task. State as low / base / high.
+
+**Conversion**: Minutes × loaded hourly rate. State whether the rate is fully-loaded or salary-only.
+
+**Trap**: Hours saved are not cash unless the client actually reduces or backfills headcount. Default to "capacity reallocated to higher-value work" framing and flag the cash-vs-capacity distinction explicitly. If the client commits to a specific headcount or contractor reduction, model that as a separate, named line.
+
+## 2. Throughput / cycle-time reduction
+
+**What it is**: More units of work processed in the same window, or the same units processed faster.
+
+**Baseline**: Current throughput per period and current cycle time.
+
+**Uplift**: Percent throughput increase or hours of cycle-time reduction.
+
+**Conversion**: For revenue-bearing work, throughput × revenue per unit. For SLA-bound work, cycle-time reduction × penalty avoided or customer-experience proxy.
+
+**Trap**: Higher throughput only realizes value if there is demand to absorb it or a downstream constraint that lifts.
+
+## 3. Quality / error reduction
+
+**What it is**: Fewer defects, rework loops, escalations, or compliance misses.
+
+**Baseline**: Current error or rework rate, cost per error event.
+
+**Uplift**: Percent reduction in error rate.
+
+**Conversion**: Avoided rework hours, avoided refunds or chargebacks, avoided regulatory fines, avoided escalations.
+
+**Trap**: AI can introduce new error classes (hallucinations, miscategorization). Net the gross reduction against new error costs and assumed remediation effort.
+
+## 4. Revenue lift
+
+**What it is**: Higher conversion, larger deal size, faster sales cycles, better cross-sell, reduced churn.
+
+**Baseline**: Current conversion rate, average deal size, sales cycle, churn rate.
+
+**Uplift**: Percent change in the relevant metric.
+
+**Conversion**: Incremental revenue × gross margin (not revenue alone — finance partners will discount revenue-only claims).
+
+**Trap**: Attribution. State how the lift will be measured and whether a holdout, A/B, or pre-post comparison is feasible.
+
+## 5. Risk avoidance
+
+**What it is**: Reduced exposure to regulatory fines, security incidents, fraud loss, or safety events.
+
+**Baseline**: Frequency of events × cost per event, or expected loss from current risk model.
+
+**Uplift**: Percent reduction in event frequency or severity.
+
+**Conversion**: Expected-loss reduction. State explicitly that this is a probabilistic benefit and may not appear in any single year's P&L.
+
+**Trap**: CFOs heavily discount risk-avoidance claims. Show them, but do not lean the headline ROI on them.
+
+## 6. Capacity reallocation
+
+**What it is**: Freed analyst, support, or specialist capacity that gets redirected to higher-value work.
+
+**Baseline**: Hours per week consumed by the current workflow.
+
+**Uplift**: Hours per week reclaimed.
+
+**Conversion**: Reclaimed hours × value of the redirected work (project hours, advisory hours, customer-facing hours). If the redirected work has no quantified value yet, present capacity in hours and flag the conversion as pending.
+
+**Trap**: Double-counting. Do not count the same hour as both "labor productivity cash savings" and "capacity reallocated".
+
+## 7. Cost-to-serve reduction
+
+**What it is**: Lower marginal cost per transaction, ticket, claim, or interaction.
+
+**Baseline**: Current cost per unit (people + tools + overhead).
+
+**Uplift**: Percent reduction in cost per unit, multiplied by volume.
+
+**Conversion**: Direct cost out the door if the resources are actually shed; otherwise capacity reallocated.
+
+**Trap**: Same as labor productivity — only model as cash if the cost actually leaves the organization.
+
+## Choosing categories
+
+Most AI use cases land in 2–3 of these categories. Pick the ones the workflow actually changes and avoid stacking categories that overlap (for example, throughput and capacity reallocation often double-count).
+
+## Always state
+
+- Source label per line (`logged`, `interview`, `benchmark`, `hypothesis`)
+- Whether the benefit is cash, capacity, or risk-avoidance
+- Currency, period, and realization factor used