# Activity: Run Monte Carlo Simulation

**Activity ID**: 72
**Order**: 7
**Phase**: Elaboration
**Dependencies**: None

## Description

Run Monte Carlo Simulation

## Guidance

## Purpose
Execute Monte Carlo simulation (10,000 iterations, triangular distributions) over the scenario-level PERT triplets to produce probabilistic delivery forecasts. The simulation produces two types of output:

- **Internal:** P50/P80/P95 for token budget and calendar duration. Used for sprint planning and AI cost control.
- **Client-facing:** P50/P80/P95 expressed in AFP and $ (AFP × $/FP). Used for delivery commitment communication.

The EBS (Evidence-Based Scheduling) diagrams remain internal — the client quote shows AFP bands, not token S-curves.

## Prerequisites
- EST-05 complete (Rough Estimates tab with min/expected/max per scenario and per sprint; AFP in Client Quote tab)
- OR EST-06 complete for Level 2 (WBS with work-package-level PERT triplets)
- Monte Carlo VBS script present in the Monte Carlo tab of ESTIMATION_TEMPLATE.xlsx

## Steps

### Step 1: Verify Simulation Inputs

Before running, confirm in the Monte Carlo tab:
- Each scenario row has: scenario ID, sprint, min tokens, expected tokens, max tokens
- Sprint dependency order is correct
- Internal combined multiplier from Setup tab is referenced
- Daily throughput (tokens/day) is set in Setup tab

If using Level 2 data from EST-06, aggregate work-package PERT triplets to scenario level first (sum of WP min → scenario min, etc.).

### Step 2: Run the VBS Simulation

In the Monte Carlo tab, run the VBS macro (Alt+F8 → RunMonteCarloSimulation):

The macro performs 10,000 iterations. In each iteration:
1. For every scenario, draw a random token sample from Triangular(min, expected, max)
2. Apply sprint dependency graph (sequential unless flagged parallelizable)
3. Compute total tokens for the iteration
4. Compute total duration (tokens / daily throughput, respecting sprint boundaries)
5. Record [total_tokens, total_duration] to results array

Output columns populated by macro:
- Column A: iteration token totals (sorted ascending)
- Column B: iteration duration totals (sorted ascending)
- Column C: cumulative probability (0.0 → 1.0)

### Step 3: Read Internal Simulation Results (Token Budget + Duration)

| Percentile | Meaning | Token Budget (K) | Duration (days) |
|---|---|---|---|
| P10 | Only 10% chance of finishing within this | ___ K | ___ days |
| P50 | Median — 50/50 chance | ___ K | ___ days |
| P80 | 80% confidence — recommended for planning | ___ K | ___ days |
| P95 | Conservative commitment | ___ K | ___ days |

**Recommended internal planning budget: P80** (ACM SAC 2021 — Monte Carlo achieves MMRE 20% vs 134% for developer estimates; P80 absorbs most residual error).

Record these values in the Monte Carlo tab summary section. These are internal and inform sprint budget allocation.

### Step 4: Convert to AFP Bands (Client-Facing)

Using AFP and $/FP from the Client Quote tab, compute AFP-equivalent ranges:

```
AFP_P50 = Feature AFP  (baseline from EST-05)
AFP_P80 = AFP_P50 × (P80_tokens / P50_tokens)   ← scale AFP by same ratio as token bands
AFP_P95 = AFP_P50 × (P95_tokens / P50_tokens)
```

Then compute $ ranges:
```
Quote_P50 = AFP_P50 × $/FP
Quote_P80 = AFP_P80 × $/FP
Quote_P95 = AFP_P95 × $/FP
```

Record in the Client Quote tab. This gives the client a defensible range without exposing tokens.

### Step 5: Produce EBS Diagrams (Internal)

The EBS (Evidence-Based Scheduling) diagrams show cumulative probability curves — internal planning tools:

**Curve 1: Token Budget Certainty**
- X-axis: token budget (K tokens) from P10 to P95
- Y-axis: probability of completing within that budget (0% → 100%)
- Mark calibration points: P50, P80, P95

**Curve 2: Duration Certainty**
- X-axis: calendar date (from today to P95 completion date)
- Y-axis: probability of completing by that date (0% → 100%)
- Mark specific dates: P10, P50 (expected), P80 (planning), P95 (conservative)

Both curves are generated by the VBS macro and embedded in the Monte Carlo tab.

### Step 6: Prepare Client Delivery Commitment

From the AFP band computation:

```
Delivery Commitment — {Project Name} — {Date}

Scope: {N} features, {total FP} FP, Sprint 0 setup included

AFP (Adjusted Function Points):
  P50 (median):    AFP = ___   →  $___
  P80 (planning):  AFP = ___   →  $___   ← recommended commitment
  P95 (committed): AFP = ___   →  $___

Duration:
  P50 (median):    ___ working days  (by ___ date)
  P80 (planning):  ___ working days  (by ___ date)
  P95 (committed): ___ working days  (by ___ date)

Stack Factor: ___    Org Factor: ___    $/FP: $___ (SEED/CALIBRATED)
```

### Step 7: Document Simulation Snapshot

Save `docs/plans/MC_SNAPSHOT_{DATE}.md` with:
- Date, input (total scenarios, total SP, total FP, convergence phase)
- ECF/TCF combined multiplier, K-token calibration status
- P50/P80/P95 internal (tokens + duration)
- P50/P80/P95 client (AFP + $)
- Sprint plan summary

## Rules to Follow

### I. Simulation Requires Min ≠ Max
If any scenario has min = expected = max, expand: min = expected × 0.7, max = expected × 1.5.

### II. P80 Is the Planning Commitment
Never commit to P50. P50 means 50% chance of missing. P80 is the minimum defensible planning target.

### III. Client Sees AFP Bands — Not Token Curves
The EBS S-curve is an internal tool. The client communication uses AFP ranges and $ totals.

### IV. Simulate After Each Sprint Close
Re-run EST-07 after each EST-08. The simulation updates with actuals replacing estimates for completed scenarios.

### V. Token Cost Is Computable but Internal
Tokens × API rate = internal cost of delivery. This informs margin analysis and $/FP calibration. It is never on the client quote.

## Success Criteria
- VBS simulation executed (10,000 iterations)
- P10/P50/P80/P95 extracted for token budget and duration (internal)
- AFP band and $ range computed for P50/P80/P95 (client-facing)
- EBS diagrams generated (internal — Monte Carlo tab)
- Client delivery commitment prepared (AFP + $ ranges)
- MC_SNAPSHOT saved to `docs/plans/`
- Monte Carlo tab and Client Quote tab updated

## Agent

None

## Skill

**Title**: Generate Estimation XLS
**Capability Domain**: ESTIMATION
**Technology Stack**: Python+openpyxl

## Rules

None

## Artifacts Produced

None

## Artifacts Consumed

- **Estimation Template (Excel)** (Document) - Required

## Notes

No additional notes.
