/financial-model - Database-Driven Financial Model Engine

Full-featured SaaS financial model engine backed by SQLite (ADR-177). Create scenarios, edit assumptions (pricing, growth, funding, headcount, expenses), build outputs in 4 formats (static XLSX, formula XLSX, JSON, CSV), compare scenarios side-by-side, and maintain a complete audit trail.

Usage

/financial-model <subcommand> [options]

# Aliases
/fm <subcommand> [options]
/fin <subcommand> [options]

Subcommands

Subcommand	Purpose	Example
`seed-defaults`	Create scenario with CODITECT defaults	`/fm seed-defaults base`
`scenario`	CRUD operations on scenarios	`/fm scenario list`
`funding`	Manage funding rounds	`/fm funding add base seed 2M M6`
`pricing`	Set tier pricing assumptions	`/fm pricing base --tier enterprise --price 1500 ...`
`growth`	Set monthly growth rates	`/fm growth base --range M1-M6 --rate 0.50`
`build`	Generate output files	`/fm build base --format all`
`compare`	Side-by-side scenario comparison	`/fm compare base aggressive`
`export`	Export scenario to JSON	`/fm export base`
`import`	Import scenario from JSON	`/fm import scenario.json`
`history`	View audit trail	`/fm history base`

System Prompt

EXECUTION DIRECTIVE: When the user invokes /financial-model (or /fm, /fin), you MUST:

Locate the engine — find coditect_fm.py in the project
Ensure xlsxwriter is installed — self-provision if missing
Parse the subcommand and map to the engine CLI
Execute via python3 <engine_path> <subcommand> [args]
Display results — format output for readability
Log to session if significant (build, compare, scenario create/clone)

Engine Detection (Step 1)

# Priority 1: Protected products installation (ADR-180)
ENGINE="$HOME/Library/Application Support/CODITECT/products/coditect-financial-model/src/coditect_fm.py"

# Priority 2: Product submodule (development — ADR-179)
if [ ! -f "$ENGINE" ]; then
    ROLLOUT_ROOT="$(cd "$CODITECT_CORE/../.." && pwd)"
    ENGINE="$ROLLOUT_ROOT/submodules/products/coditect-financial-model/src/coditect_fm.py"
fi

# Priority 3: Legacy location
if [ ! -f "$ENGINE" ]; then
    ENGINE="$CODITECT_CORE/analyze-new-artifacts/coditect-financial-model-2026-02-04/coditect_fm.py"
fi

# Priority 4: Search
if [ ! -f "$ENGINE" ]; then
    ENGINE=$(find . -name "coditect_fm.py" -path "*/financial-model*" 2>/dev/null | head -1)
fi

Self-Provisioning (Step 2)

python3 -c "import xlsxwriter" 2>/dev/null || pip3 install xlsxwriter

Execution (Steps 3-4)

# All subcommands dispatch to the engine CLI
python3 "$ENGINE" <subcommand> [args]

# Custom database path (optional)
python3 "$ENGINE" --db /path/to/custom.db <subcommand> [args]

Subcommand Reference

`seed-defaults` — Create Scenario with Defaults

Load CODITECT default assumptions from CODITECT_Model_Export.json.

/fm seed-defaults <scenario_id>

What it loads:

3 pricing tiers (individual $15/mo, team $250/mo, enterprise $1,300/mo)
8 growth rate periods (100% → 0.5% over 60 months)
5 expense ratio categories × 3 stages (pre_revenue, growth, scale)
5 headcount periods (2 → 18 employees)
4 working capital parameters (DSO/DPO by tier)
6 SaaS comparables for valuation

Example:

/fm seed-defaults base
# Creates "base" scenario with all CODITECT defaults
# Output: 3 tiers, 8 growth periods, 15 expense ratios, 5 headcount periods, 6 comparables

`scenario` — Manage Scenarios

/fm scenario list                        # List all scenarios
/fm scenario create <id> <name> [months] # Create empty scenario (default 60 months)
/fm scenario clone <source> <dest>       # Clone with all assumptions
/fm scenario delete <id>                 # Delete scenario and all data
/fm scenario show <id>                   # Show scenario details

Examples:

/fm scenario list
# ID          Name         Months  Start       NRR(M24)  Created
# base        Base         60      2026-02-12  1.06      2026-02-12T03:51:41Z
# aggressive  Aggressive   60      2026-02-12  1.06      2026-02-12T03:52:10Z

/fm scenario clone base conservative
# Cloned: base → conservative (all assumptions copied)

`funding` — Manage Funding Rounds

/fm funding add <scenario> <name> <amount> <month>   # Add round
/fm funding remove <scenario> <name>                  # Remove round
/fm funding list <scenario>                           # List rounds

Amount syntax: 2M = $2,000,000 | 500K = $500,000 | 2000000 = raw number Month syntax: M6 = month 6 | 6 = month 6

Examples:

/fm funding add base seed 2M M6
/fm funding add base series-a 15M M18
/fm funding list base
# Name       Amount          Month  Tranche1  Tranche2  Tranche3
# seed       $2,000,000      M6     70%       20%       10%
# series-a   $15,000,000     M18    70%       20%       10%

/fm funding remove base seed

`pricing` — Set Tier Pricing

/fm pricing <scenario> --tier <tier> --price <N> --cac <N> --churn <N> --mix <N>

Tiers: individual, team, enterprise

Examples:

/fm pricing base --tier enterprise --price 1500 --cac 1200 --churn 0.08 --mix 0.15
/fm pricing base --tier individual --price 20 --cac 12 --churn 0.30 --mix 0.55

`growth` — Set Growth Rates

/fm growth <scenario> --range <M_start-M_end> --rate <rate>

Range syntax: M1-M6 = months 1 through 6

Examples:

/fm growth base --range M1-M3 --rate 1.00      # 100% MoM growth months 1-3
/fm growth base --range M4-M6 --rate 0.50      # 50% MoM growth months 4-6
/fm growth base --range M7-M12 --rate 0.20     # 20% MoM growth months 7-12
/fm growth aggressive --range M1-M3 --rate 1.50 # 150% for aggressive scenario

`build` — Generate Output Files

/fm build <scenario> [--format <format>] [--output <dir>]

Formats:

Format	Flag	Output	Use Case
Static XLSX	`--format xlsx`	10-sheet workbook (Cover, Engine, P&L, Revenue, Expenses, Cash Flow, Dashboard, Unit Econ, Comparables, Assumptions)	Investor presentations, board decks
Formula XLSX	`--format formula`	10-sheet workbook (Inputs, Engine, P&L, Revenue, Expenses, Cash Flow, Dashboard, Unit Economics, Comparables, Instructions) — all live formulas	What-if analysis — change inputs, everything recalculates
JSON	`--format json`	Structured JSON with metadata, summary, assumptions, monthly_data	API consumption, BI tool ingestion
CSV	`--format csv`	Flat monthly data	pandas/R analysis, spreadsheet import
All	`--format all`	All 4 formats simultaneously	Complete export

Examples:

/fm build base --format all
# Computing model for scenario: base...
#   Breakeven: M11
#   M60 ARR: $128,602,620
#   M60 Cash: $69,449,056
#   Peak Burn: $69,514
#   xlsx:    CODITECT_FM_base.xlsx
#   formula: CODITECT_FM_base_FORMULA.xlsx
#   json:    CODITECT_FM_base.json
#   csv:     CODITECT_FM_base.csv

/fm build base --format formula --output /tmp/investor

`compare` — Side-by-Side Scenario Comparison

/fm compare <scenario_a> <scenario_b> [--metrics <list>]

Example:

/fm compare base aggressive
# Metric               base            aggressive      Delta
# ─────────────────────────────────────────────────────────────
# M60 ARR              $128,602,620    $403,728,450    +$275,125,830
# M60 Cash             $69,449,056     $249,183,200    +$179,734,144
# Breakeven Month      M11             M8              -3 months
# Peak Monthly Burn    $69,514         $69,514         $0
# M24 NRR              106.0%          106.0%          +0.0%

`export` / `import` — Scenario Portability

/fm export <scenario> [--output <file>]     # Export all assumptions to JSON
/fm import <json_file>                       # Import scenario from JSON

Export includes: scenario config, pricing (all tiers), growth rates, funding rounds, expense ratios, headcount periods, working capital, comparables.

Example:

/fm export base --output base_assumptions.json
/fm import base_assumptions.json
# Imported scenario: base (60 months, 3 tiers, 2 funding rounds)

`history` — Audit Trail

/fm history <scenario> [--limit <N>]

Example:

/fm history base --limit 5
# Time                  Table      Field          Old → New
# 2026-02-12T03:52:10  growth     rate (M1-M3)   1.00 → 1.50
# 2026-02-12T03:52:05  funding    seed           - → $2,000,000@M6
# 2026-02-12T03:51:55  pricing    enterprise     - → $1,300/mo
# 2026-02-12T03:51:50  scenario   base           - → created

Workflows

Quick Start — Build from Defaults

/fm seed-defaults mycompany
/fm funding add mycompany seed 2M M6
/fm build mycompany --format all

Scenario Analysis — Compare Strategies

/fm seed-defaults base
/fm funding add base seed 2M M6
/fm funding add base series-a 15M M18
/fm scenario clone base aggressive
/fm growth aggressive --range M1-M3 --rate 1.50
/fm growth aggressive --range M4-M6 --rate 0.80
/fm compare base aggressive
/fm build aggressive --format formula

Investor Deck — Generate Materials

/fm seed-defaults pitch
/fm funding add pitch seed 2M M6
/fm funding add pitch series-a 15M M18
/fm build pitch --format xlsx       # Static for embedding in slides
/fm build pitch --format formula    # Interactive for due diligence
/fm export pitch                    # JSON for data room

Architecture

ADR-177: Database-Driven Financial Model Engine

┌──────────────────────────────────────────┐
│         /financial-model CLI             │
│    (this command → coditect_fm.py)       │
├──────────────────────────────────────────┤
│         Calculation Engine               │
│  compute_model() → 60-month projection  │
│  cached in computed_months table         │
├──────────────────────────────────────────┤
│         SQLite Database                  │
│  10 tables, 13 cache invalidation       │
│  triggers, full audit trail             │
├──────────────────────────────────────────┤
│         Output Formatters               │
│  StaticXlsx │ FormulaXlsx │ Json │ Csv  │
└──────────────────────────────────────────┘

Database tables: scenarios, pricing, growth_rates, funding_rounds, expense_ratios, headcount, working_capital, comparables, computed_months, scenario_history

Cache invalidation: Any assumption change auto-invalidates computed results via SQLite triggers (13 triggers: INSERT + UPDATE per assumption table).

File Locations

File	Path
Product Submodule	`submodules/products/coditect-financial-model/` (ADR-179)
Engine	`submodules/products/coditect-financial-model/src/coditect_fm.py`
Seed data	`submodules/products/coditect-financial-model/data/CODITECT_Model_Export.json`
Database	`submodules/products/coditect-financial-model/src/coditect_fm.db` (auto-created)
ADR-177	`internal/architecture/adrs/ADR-177-database-driven-financial-model-engine.md`
ADR-179	`internal/architecture/adrs/ADR-179-hybrid-financial-model-distribution.md`
TRACK	`internal/project/plans/pilot-tracks/TRACK-N-GTM-LAUNCH.md` (N.6.15)

Command	Purpose
`/pitch-deck`	Generate investor pitch deck
`/business-plan`	Generate business plan document
`/finance-review`	Financial review and analysis
`/finance-build`	Build financial dashboards

financial-model — Financial model generation skill
financial-analytics — Financial data analysis
saas-metrics — SaaS metric tracking

Success Output

COMMAND COMPLETE: /financial-model build base --format all
  Breakeven: M11
  M60 ARR: $128,602,620
  M60 Cash: $69,449,056
  Outputs: 4 files generated

Completion Checklist

Failure Indicators

Engine file not found
Database locked or corrupted
Missing xlsxwriter dependency
Invalid scenario ID
Invalid amount/month/range syntax

Command Version: 2.0.0 Engine Version: 1.0.0 (ADR-177) Created: 2026-01-26 Updated: 2026-02-12 Author: CODITECT Core Team ADR: ADR-177

Changelog:

v2.0.0 - N.6.11: Complete rewrite. Wraps coditect_fm.py DB engine (ADR-177) with 10 subcommands: scenario, seed-defaults, funding, pricing, growth, build, compare, export, import, history. Replaces generic DOC-005 template wrapper. 4 output formats (static XLSX, formula XLSX, JSON, CSV). Scenario comparison, audit trail, self-provisioning.
v1.0.0 - Initial release. Generic DOC-005 template wrapper for financial projections.

Usage​

Subcommands​

System Prompt​

Engine Detection (Step 1)​

Self-Provisioning (Step 2)​

Execution (Steps 3-4)​

Subcommand Reference​

seed-defaults — Create Scenario with Defaults​

scenario — Manage Scenarios​

funding — Manage Funding Rounds​

pricing — Set Tier Pricing​

growth — Set Growth Rates​

build — Generate Output Files​

compare — Side-by-Side Scenario Comparison​

export / import — Scenario Portability​

history — Audit Trail​

Workflows​

Quick Start — Build from Defaults​

Scenario Analysis — Compare Strategies​

Investor Deck — Generate Materials​

Architecture​

File Locations​

Related Commands​

Related Skills​

Success Output​

Completion Checklist​

Failure Indicators​

Usage

Subcommands

System Prompt

Engine Detection (Step 1)

Self-Provisioning (Step 2)

Execution (Steps 3-4)

Subcommand Reference

`seed-defaults` — Create Scenario with Defaults

`scenario` — Manage Scenarios

`funding` — Manage Funding Rounds

`pricing` — Set Tier Pricing

`growth` — Set Growth Rates

`build` — Generate Output Files

`compare` — Side-by-Side Scenario Comparison

`export` / `import` — Scenario Portability

`history` — Audit Trail

Workflows

Quick Start — Build from Defaults

Scenario Analysis — Compare Strategies

Investor Deck — Generate Materials

Architecture

File Locations

Related Commands

Related Skills

Success Output

Completion Checklist

Failure Indicators