Phoenix Advanced Forecasting

You are the architectural and implementation guide for Phoenix's probabilistic "living model" layer, built on top of a validated deterministic fund engine.

The deterministic core (Phase 1) handles:

• Fees / XIRR / Waterfalls / Capital allocation / Recycling
• 6-decimal precision and JSON truth-case validation

The probabilistic layer (Phase 2) adds:

• Graduation & exit models
• Multi-MOIC analysis
• Reserves ranking and optimization
• Scenario management
• Monte Carlo simulation

1. When to Use

Use this skill when:

• Designing or modifying:
  • Graduation rate / exit / failure rate models
  • MOIC variants (current, exit, initial vs follow-on, MOIC on reserves, opportunity cost)
  • Portfolio ranking and reserve optimization
  • Construction vs Current scenarios
  • Monte Carlo simulations over the deterministic engine
• Adding "living model" features that ingest deterministic outputs and produce distributions or optimized decisions.

Do not use this skill:

• For fixing deterministic math bugs (hand off to the relevant deterministic skill).
• For precision or type-safety work (hand off to phoenix-precision-guard).

2. Architecture Overview

User Inputs
  └─► Deterministic Engine (Phase 1)
        • Fees / XIRR / Waterfall / Capital Allocation / Recycling
        • 6-decimal precision / JSON truth cases / Excel parity
          ↓
  Probabilistic Layer (Phase 2)
        • Graduation & exit engines
        • MOIC calculation suite (multiple types)
        • Portfolio ranking & reserves optimization
        • Scenario builder (Construction vs Current)
        • Monte Carlo orchestrator
          ↓
  Outputs
        • Distributions (TVPI, DPI, MOIC, IRR)
        • Optimal reserves ranking ("next dollar" decisions)
        • Scenario comparisons & dashboards

Principles:

• Never inject randomness into Phase 1 modules.
• Treat Phase 1 outputs as pure building blocks.
• Allow deterministic "Expectation Mode" for every probabilistic component.

3. Graduation Rate Engine

For each stage:

• Inputs:
  • graduationRate, exitRate, failureRate
  • avgMonthsToEvent
• Constraint:
  • graduationRate + exitRate + failureRate = 1.0
• Provide:
  • expectedTransition(params) – deterministic expectation for testing
  • sampleTransition(params, rng) – stochastic draws for Monte Carlo

Expected use:

• Drive:
  • Stage counts over time
  • Follow-on demand based on graduations
  • Exit timing distributions

4. MOIC Calculation Suite

Implement MOIC variants as pure deterministic functions:

Recommended variants:

1. Current MOIC (mark-to-market on total invested capital)
2. Exit MOIC (projected)
3. Initial-only MOIC
4. Follow-on-only MOIC
5. Blended MOIC (initial + follow-on)
6. Exit MOIC on planned reserves (core "next dollar" metric)
7. Opportunity cost MOIC (this dollar vs alternatives)

These should:

• Decompose performance between initial and follow-on checks.
• Handle partial exits and convertibles where applicable.
• Use the same decimal precision conventions as Phase 1.

5. Portfolio Ranking & Reserves Optimization

Design ranking as:

• Inputs:
  • MOIC breakdowns
  • Planned reserves per company
  • Graduation/exit expectations
• Outputs:
  • Ranked list of companies by "Exit MOIC on planned reserves" (or chosen metric)
  • Suggested reserve allocation subject to a total reserves constraint

Guidelines:

• Avoid mutating core capital allocation; treat this as a "decision support" layer.
• Make ranking criteria explicit and user-configurable.

6. Scenario Management & Monte Carlo

Scenario types:

• Construction forecast – original plan
• Current forecast – plan + actuals/remaining capital

Scenario management should:

• Allow toggling individual deals/assumptions on/off
• Compare multiple scenarios side-by-side
• Export/import scenario configs to/from JSON or CSV

Monte Carlo:

• Wrap deterministic forecast calls in a loop.
• Use configurable:
  • iterations
  • seed
  • scenario set
• Aggregate results into:
  • Distributions (means, percentiles) for TVPI, DPI, MOIC, IRR

7. Validation

For every probabilistic feature:

• Provide a deterministic "Expectation Mode":
  • No randomness, just expectations.
• Validate expectation mode against:
  • Analytical calculations
  • Excel/Sheets model where applicable
• Add tests for:
  • Distribution means ≈ expectations
  • Valid ranges and normalization of probabilities
  • No negative or impossible metrics

8. Invariants

• Phase 2 must never degrade Phase 1 truth-case pass rates.
• All probabilistic modules must be seedable and testable.
• Scenario and Monte Carlo outputs must be explainable to LPs in plain language.