> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roi4srm.willowflow.group/llms.txt
> Use this file to discover all available pages before exploring further.

# Content scenarios

# Scenarios Tab Content Plan

**Version:** 1.0\
**Status:** Draft\
**Date:** 2025-10-10\
**Target Phase:** P2 (Scenario Modeling)

***

## 1. Overview

### 1.1 Purpose

This content plan defines the user-facing guidance, instructions, and help content for the upcoming **Scenarios Tab**, which will support P2 scenario modeling features including scenario CRUD operations, comparison view, sensitivity analysis, and qualitative mapping toggle.

**Target Audience:** NGO managers and security practitioners using the calculator to model different operational scenarios and perform sensitivity analyses.

### 1.2 Related Features (P2 Backlog)

* **T021:** Scenario CRUD UI (duplicate, rename, delete scenarios)
* **T022:** Comparison View (side-by-side ROI/EAL/NPV/Payback comparison)
* **T023:** Sensitivity Controls (sliders for ARO, SLE, discount rate, horizon, costs)
* **T024:** Sub-1s Update Strategy (debounce inputs, optimistic compute)
* **T025:** Qualitative Mapping Switch (toggle between shadow-price and parameter-delta)

### 1.3 Content Organization

The Scenarios Tab will include:

1. **Introduction & Overview:** What scenario modeling is and why it's useful
2. **Scenario CRUD Instructions:** How to create, duplicate, rename, and delete scenarios
3. **Comparison View Guidance:** Interpreting side-by-side comparisons
4. **Sensitivity Analysis Guide:** Using sliders to test assumptions
5. **Qualitative Mapping Toggle:** Switching between shadow-price and parameter-delta methods
6. **Example Use Cases:** 3-5 scenarios demonstrating practical applications

***

## 2. Introduction & Overview

<AccordionGroup>
  <Accordion title="What is Scenario Modeling?">
    ### 2.1 In-App Help Text

    **Section Title:** "What is Scenario Modeling?"

    **Content:**

    > Scenario modeling allows you to explore how different assumptions and interventions affect your security ROI. By creating multiple scenarios, you can:
    >
    > * **Compare baseline (do-nothing) vs. intervention cases** to justify security investments
    > * **Test sensitivity** to key assumptions (discount rate, time horizon, qualitative weights/proxies)
    > * **Model optimistic, realistic, and pessimistic outcomes** to assess risk
    > * **Evaluate different security strategies** (e.g., focus on cybersecurity vs. physical security)
    >
    > Each scenario contains its own incidents, costs, assumptions, and qualitative scores. Changes to one scenario do not affect others.
  </Accordion>

  <Accordion title="When Should I Create Comparison Scenarios?">
    ### 2.2 When to Use Scenario Modeling

    **Section Title:** "When Should I Create Comparison Scenarios?"

    **Content:**

    > Create comparison scenarios when you want to:
    >
    > 1. **Justify a security investment:** Compare baseline (current state) vs. intervention (with security program) to show ROI
    > 2. **Evaluate alternatives:** Compare different security strategies (e.g., "High-Tech Security" vs. "Community-Based Security")
    > 3. **Test assumptions:** Create optimistic, realistic, and pessimistic scenarios to assess how sensitive your ROI is to key parameters
    > 4. **Support donor reporting:** Show multiple scenarios to demonstrate due diligence and risk awareness
    > 5. **Plan for uncertainty:** Model best-case and worst-case scenarios to prepare for different futures
  </Accordion>
</AccordionGroup>

***

## 3. Scenario CRUD Instructions

### 3.1 Creating a New Scenario

**Section Title:** "How to Create a New Scenario"

**Step-by-Step Instructions:**

<Steps>
  <Step title="Click &#x22;New Scenario&#x22; button">
    1. **Click "New Scenario" button** in the Scenarios tab
  </Step>

  <Step title="Choose a starting point">
    2. **Choose a starting point:**
       * **Blank Scenario:** Start from scratch with no data
       * **Duplicate Existing Scenario:** Copy an existing scenario to modify
  </Step>

  <Step title="Name your scenario">
    3. **Name your scenario** (e.g., "Intervention: Comprehensive Security Program")
  </Step>

  <Step title="Input data">
    4. **Input data:**
       * Incidents (≥3 types recommended)
       * Costs (≥3 line items across multiple periods)
       * Assumptions (discount rate, time horizon)
       * Qualitative scores (weights, anchors, optional proxies)
  </Step>

  <Step title="Save scenario">
    5. **Save scenario** and proceed to comparison view
  </Step>
</Steps>

**Best Practice Tip:**

> **Start with Baseline:** Create a baseline (do-nothing) scenario first to establish the counterfactual. Then duplicate it and modify to create intervention scenarios.

<AccordionGroup>
  <Accordion title="How to Duplicate a Scenario">
    ### 3.2 Duplicating a Scenario

    **Section Title:** "How to Duplicate a Scenario"

    **Content:**

    > Duplicating a scenario is the fastest way to create comparison scenarios with similar data.
    >
    > **Steps:**
    >
    > 1. Find the scenario you want to copy in the scenario list
    > 2. Click the **"Duplicate"** icon (📋) next to the scenario name
    > 3. A new scenario will be created with the same data, named "\[Original Name] (Copy)"
    > 4. Rename the new scenario and modify as needed
    >
    > **Example Use Case:** Duplicate your baseline scenario to create "Optimistic" and "Pessimistic" variants by adjusting ARO/SLE values.
  </Accordion>

  <Accordion title="How to Rename a Scenario">
    ### 3.3 Renaming a Scenario

    **Section Title:** "How to Rename a Scenario"

    **Content:**

    > **Steps:**
    >
    > 1. Click the scenario name in the scenario list
    > 2. Type a new name (e.g., "Baseline 2023" → "Baseline 2024")
    > 3. Press Enter or click outside the field to save
    >
    > **Naming Conventions:**
    >
    > * Use descriptive names that identify the scenario's purpose (e.g., "Baseline: Current State", "Intervention: Comprehensive SRM")
    > * Include dates for time-bound scenarios (e.g., "Budget Plan 2024-2026")
    > * Use prefixes for scenario types (e.g., "Optimistic:", "Pessimistic:", "Realistic:")
  </Accordion>

  <Accordion title="How to Delete a Scenario">
    ### 3.4 Deleting a Scenario

    **Section Title:** "How to Delete a Scenario"

    **Content:**

    > **Steps:**
    >
    > 1. Find the scenario you want to delete in the scenario list
    > 2. Click the **"Delete"** icon (🗑️) next to the scenario name
    > 3. Confirm deletion in the popup dialog
    >
    > **⚠️ Warning:** Deletion is permanent and cannot be undone. Export scenarios before deleting if you may need them later.
  </Accordion>
</AccordionGroup>

***

## 4. Comparison View Guidance

### 4.1 Understanding Comparison View

**Section Title:** "How to Compare Scenarios Side-by-Side"

**Content:**

> The comparison view displays key metrics for multiple scenarios side-by-side, enabling quick evaluation of different strategies.
>
> **Displayed Metrics:**
>
> * **Expected Annual Loss (EAL):** Average annual financial risk
> * **Net Present Value (NPV):** Present value of costs
> * **Return on Investment (ROI %):** Financial return as percentage
> * **Payback Period (years):** Time to recover investment
>
> **How to Use:**
>
> 1. Select 2-5 scenarios to compare using checkboxes in the scenario list
> 2. View side-by-side metrics in the comparison table
> 3. Sort by any metric (click column header) to identify best/worst performers
> 4. Export comparison table to Excel for further analysis

### 4.2 Key Drivers Analysis

**Section Title:** "Understanding What Drives Differences in ROI"

**Content:**

> The **Key Drivers** section shows which factors account for differences between scenarios:
>
> * **EAL Reduction:** How much did risk decrease?
> * **Cost Differences:** Did one scenario cost more upfront?
> * **Qualitative Benefits:** How much qualitative value was assigned?
> * **Discount Rate Impact:** Did different discount rates affect NPV significantly?
>
> **Example:**
>
> * **Scenario A (Financial ROI −11%; QII 3.0/5.0):** Moderate financial benefits but strong qualitative improvements in access and continuity.
> * **Scenario B (Financial ROI −5%; QII 1.8/5.0):** Smaller qualitative gains and similar costs reduce the business case.
> * **Key Driver:** Qualitative impact scores, weights, and recorded evidence notes explain most of the difference.

***

## 5. Sensitivity Analysis Guide

### 5.1 Using Sensitivity Controls

**Section Title:** "How to Test Sensitivity to Key Assumptions"

**Content:**

> Sensitivity analysis helps you understand how robust your ROI estimate is to changes in key assumptions.
>
> **Available Controls:**
>
> * **Annualized Rate of Occurrence (ARO):** Adjust incident frequencies (0.00-1.00)
> * **Single Loss Expectancy (SLE):** Adjust incident costs (\$)
> * **Discount Rate:** Adjust time value of money (3%-15%)
> * **Time Horizon:** Adjust analysis period (1-10 years)
> * **Costs:** Adjust cost amounts and periods
>
> **How to Use:**
>
> <Steps>
>   <Step title="Select a scenario">
>     1. Select a scenario
>   </Step>
>
>   <Step title="Click &#x22;Sensitivity Analysis&#x22; button">
>     2. Click "Sensitivity Analysis" button
>   </Step>
>
>   <Step title="Use sliders or input fields">
>     3. Use sliders or input fields to adjust parameters
>   </Step>
>
>   <Step title="Observe real-time updates">
>     4. Observe real-time updates to ROI, EAL, NPV, Payback (less than 1s response time)
>   </Step>
>
>   <Step title="Save adjusted scenario">
>     5. Save adjusted scenario as a new variant (e.g., "Optimistic" or "Pessimistic")
>   </Step>
> </Steps>

### 5.2 Performance Expectations

**Section Title:** "Real-Time Updates and Performance"

**Content:**

> The calculator is designed to provide **sub-1 second updates** when you adjust sensitivity controls.
>
> * **Optimistic UI:** Changes appear instantly in the interface
> * **Background Calculation:** Full recalculation happens in less than 1s
> * **Debounced Inputs:** Rapid slider movements are batched to avoid overwhelming the system
>
> **Tip:** If updates feel slow, wait 1-2 seconds after adjusting a slider before making further changes.

### 5.3 Example Use Cases

**Section Title:** "Example Sensitivity Scenarios"

<Tabs>
  <Tab title="Use Case 1: Optimistic, Realistic, Pessimistic">
    **Use Case 1: Optimistic, Realistic, Pessimistic**

    > **Purpose:** Assess how the financial ROI changes with different risk reduction assumptions
    >
    > | Scenario        | ARO Adjustment     | Financial ROI | QII |
    > | --------------- | ------------------ | ------------- | --- |
    > | **Pessimistic** | ARO reduced by 20% | −25%          | 2.3 |
    > | **Realistic**   | ARO reduced by 50% | −11%          | 3.0 |
    > | **Optimistic**  | ARO reduced by 80% | 6%            | 3.4 |
    >
    > **Insight:** Financial ROI swings significantly with risk reduction assumptions, while the QII stabilises around 3.0. Use both metrics when discussing investment value.
  </Tab>

  <Tab title="Use Case 2: Discount Rate Requests">
    **Use Case 2: Discount Rate Requests**

    > **Purpose:** Respond when stakeholders ask for alternate discount rates even though the calculator fixes r = 0%.
    >
    > | Scenario                 | How to Handle                                           | Notes                                                         |
    > | ------------------------ | ------------------------------------------------------- | ------------------------------------------------------------- |
    > | **Default (0%)**         | Use calculator output                                   | NPV \$166k; Financial ROI −11%                                |
    > | **Donor insists on 5%**  | Export results and recompute offline                    | Document assumption; compare against 0% baseline              |
    > | **High discount (10%+)** | Provide qualitative rationale against heavy discounting | Emphasise humanitarian ethics and present sensitivity caveats |
    >
    > **Insight:** Keep 0% discounting as the documented baseline. If alternative rates are required, treat them as separate scenarios with clear justification and retain qualitative metrics alongside the recalculated ROI.
  </Tab>

  <Tab title="Use Case 3: Time Horizon Extension">
    **Use Case 3: Time Horizon Extension**

    > **Purpose:** Evaluate long-term financial performance by extending the time horizon
    >
    > | Time Horizon | Payback Period | Financial ROI |
    > | ------------ | -------------- | ------------- |
    > | 3 years      | N/A            | −11%          |
    > | 5 years      | 4.8 years      | 7%            |
    > | 10 years     | 4.8 years      | 38%           |
    >
    > **Insight:** Extending the horizon can reveal delayed payback and positive financial ROI; ensure the chosen horizon aligns with programme lifecycle and donor expectations.
  </Tab>
</Tabs>

***

## 6. Communicating Qualitative Value

### 6.1 Communicating Qualitative Results

**Section Title:** "Sharing the Qualitative Story"

**Content:**

> * **Qualitative Impact Index (QII):** Always produced. Shows a weighted 0–5 score that summarises access, continuity, acceptance, and wellbeing improvements.
> * **Evidence notes:** Capture one or two sentences explaining the change so reviewers understand the rationale.
> * **Suggested approach:** Present Financial ROI alongside QII and the key notes; this keeps the story transparent even when quantitative ROI is negative.

### 6.2 Documenting Assumptions

**Content:**

> * Record anchors, weights, and evidence notes in the assumption log or export.
> * Include indicator values when available to support future reviews.
> * Use the results narrative (summary card + action items) to highlight qualitative wins even when financial ROI is modest.

### 6.3 When to Use Parameter Delta

**Content:**

> **Use Parameter Delta Method when:**
>
> * Shadow prices feel arbitrary or lack organizational precedent
> * You want to ground qualitative benefits in quantitative risk parameters
> * Conducting sensitivity analysis to test method robustness
> * Stakeholders may ask how qualitative improvements support mission delivery; use the QII narrative to answer that question.
>
> **Example Parameter Deltas:**
>
> * 1-point improvement in Access → 5% reduction in ARO for conflict-related incidents
> * 1-point improvement in Continuity → 10% reduction in downtime costs
> * 1-point improvement in Acceptance → 15% reduction in community-related incidents

**⚠️ Note:** Parameter delta method requires additional configuration (specify which parameters to adjust and by how much). This feature is simplified in the current version; full implementation planned for future release.

***

## 7. Example Use Cases (3-5 Scenarios)

### 7.1 Use Case 1: Baseline vs. Intervention

**Scenario Name:** "Justifying a Security Investment"

**Purpose:** Demonstrate ROI of a proposed comprehensive security program

**Scenarios:**

1. **Baseline (Do-Nothing):** Current state with no SRM investment
   * Incidents: 5 types, EAL = \$49,250
   * Costs: \$0 (no intervention)
   * Qualitative: Low scores (1-2 range)
   * Financial ROI: N/A (no costs to compare); QII: 1.3 / 5.0

2. **Intervention (Comprehensive SRM):** With security program
   * Incidents: Same 5 types, but reduced ARO (50% reduction)
   * Costs: \$166,000 NPV (training, upgrades, personnel)
   * Qualitative: Improved scores (Access 4, Continuity 3, Acceptance 3, Wellbeing 2), QII: 3.0 / 5.0 (adjusted 2.2)
   * Financial ROI: −11%

**Comparison Result:** Financial ROI alone remains negative, but qualitative outcomes improve strongly across access, continuity, acceptance, and wellbeing. Communicate these improvements alongside the quantitative ROI so stakeholders see the full picture.

**Use in Reporting:** "While quantified risk reduction does not fully recover the investment within three years, the programme unlocks strong qualitative gains (QII 3.0/5.0). Use the evidence notes to illustrate how access and continuity improved."

### 7.2 Use Case 2: Optimistic vs. Pessimistic

**Scenario Name:** "Risk-Aware Planning"

**Purpose:** Assess ROI under different risk reduction effectiveness assumptions

**Scenarios:**

1. **Optimistic (80% Risk Reduction):** Security program highly effective
   * ARO reduced by 80% across all incidents
   * Financial ROI: 6%
   * QII: 3.4 / 5.0

2. **Realistic (50% Risk Reduction):** Baseline assumption
   * ARO reduced by 50%
   * Financial ROI: −11%
   * QII: 3.0 / 5.0

3. **Pessimistic (20% Risk Reduction):** Security program less effective
   * ARO reduced by 20%
   * Financial ROI: −25%
   * QII: 2.3 / 5.0

**Comparison Result:** Financial ROI is sensitive to risk reduction assumptions, whereas QII remains in the strong range (≈3.0). Use both metrics to communicate benefits and uncertainty.

### 7.3 Use Case 3: High-Tech vs. Community-Based Security

**Scenario Name:** "Comparing Security Strategies"

**Purpose:** Evaluate different security approaches

**Scenarios:**

1. **High-Tech Security:** Focus on technology and physical infrastructure
   * Costs: High CAPEX ($150k+), lower OPEX ($30k/year)
   * Qualitative: Lower community acceptance (CA scores 1-2), moderate continuity
   * Financial ROI: −8%; QII: 1.9 / 5.0

2. **Community-Based Security:** Focus on relationships and acceptance
   * Costs: Lower CAPEX ($50k), higher OPEX ($60k/year)
   * Qualitative: Higher community acceptance (CA scores 4-5), stronger access gains
   * Financial ROI: −5%; QII: 3.3 / 5.0

**Comparison Result:** While both strategies show modest financial ROI, the community-based approach delivers substantially higher qualitative impact. Present the qualitative improvements alongside the financial metrics so decision-makers understand the trade-offs.

### 7.5 Use Case 5: Time Horizon Extension

**Scenario Name:** "Long-Term Payback Analysis"

**Purpose:** Assess payback over extended time horizons

| Time Horizon | Payback Period | Financial ROI | QII Outlook                                               |
| ------------ | -------------- | ------------- | --------------------------------------------------------- |
| **3 years**  | N/A            | −11%          | Strong qualitative gains (QII 3.0)                        |
| **5 years**  | 3.4 years      | +48%          | Qualitative gains sustained; financial ROI turns positive |
| **10 years** | 3.4 years      | +197%         | Sustained benefits deliver very strong financial returns  |

**Comparison Result:** Once the horizon extends beyond \~3.4 years, the investment pays for itself. Align analysis windows with asset/programme lifecycles so multi-year benefits are captured.

***

## 8. UI/UX Considerations (For P2 Implementation)

### 8.1 Scenario List View

**Layout:**

* Sidebar with scenario names (expandable/collapsible)
* Checkboxes for selecting scenarios to compare
* Icons for Duplicate (📋), Rename (✏️), Delete (🗑️)
* Color-coded labels (Baseline = blue, Intervention = green, Sensitivity = orange)

**Interactions:**

* Click scenario name to load in main view
* Drag-and-drop to reorder scenarios (optional)
* Search/filter scenarios by name or tag

### 8.2 Comparison View Layout

**Layout:**

* Table with scenarios as columns, metrics as rows
* Sortable columns (click header to sort by ROI, EAL, etc.)
* Visual indicators for best/worst values (green/red highlighting)
* "Export to Excel" button for further analysis

### 8.3 Sensitivity Controls Layout

**Layout:**

* Sliders for ARO, SLE, discount rate, and time horizon
* Input fields for precise numeric entry
* Text fields for proxy scenario inputs (documented separately)
* "Reset to Baseline" button to undo changes
* Real-time ROI display updating less than 1s after input

### 8.4 Accessibility

**WCAG 2.1 AA Compliance:**

* Keyboard navigation for all controls (Tab, Enter, Arrow keys)
* Screen reader labels for sliders and buttons
* High-contrast color scheme (minimum 4.5:1 ratio)
* Focus indicators for active controls

***

## 9. Implementation Notes for UI Team

### 9.1 Content Placement

* **Inline Help:** Brief explanations next to controls (e.g., "What is ARO?" tooltip)
* **Contextual Panels:** Expandable panels for detailed guidance (e.g., "When to Create Scenarios")
* **Help Modal:** Full-page help accessible via "?" icon in header
* **Example Scenarios:** Pre-loaded example data accessible via "Load Example" button

### 9.2 Performance Targets

* **Scenario Load Time:** less than 200ms from click to display
* **Calculation Update:** less than 1s from input change to results display
* **Comparison View Rendering:** less than 500ms for 5 scenarios
* **Export Generation:** less than 3s for Excel export with 10 scenarios

### 9.3 Error Handling

* **Validation Errors:** Display inline next to offending field (e.g., "ARO must be between 0 and 1")
* **Calculation Errors:** Display modal with actionable guidance (e.g., "Cannot calculate payback: no annual benefits")
* **Network Errors:** Retry with exponential backoff; display "Unable to save scenario" message after 3 failed attempts

***

## Document Control

**Version:** 1.0\
**Status:** Draft\
**Date:** 2025-10-10\
**Next Review:** Upon P2 implementation kickoff

**Change Log:**

| Date       | Version | Changes                                           | Author        |
| ---------- | ------- | ------------------------------------------------- | ------------- |
| 2025-10-10 | 1.0     | Initial draft - Scenarios tab content plan for P2 | Shayan Seyedi |

***

**End of Scenarios Tab Content Plan**

For calculation methodologies, see the Methods Note. For data preparation, see the Pilot Pack & Data Readiness Guide.