Recipe: Financial modelling and calculator construction with project-state

Financial modelling has a project management problem that spreadsheet tools can't solve. The model itself lives in Excel or Python, but the project surrounding it — who commissioned what, what assumptions were signed off, which version is current, who reviewed what — lives in email threads, chat messages, and version-named files like model_v3_FINAL_ACTUALLY_FINAL.xlsx.

project-state doesn't replace the modelling tool. It wraps the modelling work in a governed, traceable project structure so the model's history and the decisions behind it are captured alongside the outputs.

The core insight: a financial model is a sequence of assumption decisions

Financial models are only as trustworthy as the decisions that built them. Growth rate assumptions. Discount rates. Cost structure. Revenue recognition methodology. Sensitivity ranges. These decisions are made during the build, often in conversations, and are rarely systematically documented.

project-state's decision log is the right tool for this. Every material assumption gets logged as a decision: what was assumed, why, who approved it, what the alternative was, what the sensitivity to that assumption is. When the client comes back six months later asking "why did you use 8% growth?", you have the answer and the reasoning.

How financial modelling maps to project-state concepts

Step 1: Scaffold with a financial modelling phase preset

ask claude: "scaffold a new v2 project, kind: client, phases: scoping, model-structure, data-population, validation, sensitivity-analysis, delivery"

Gate criteria for financial modelling phases:

phases:
  - name: scoping
    gate_criteria:
      - model scope document approved by client
      - key assumptions list agreed (document index: status=approved)
      - data requirements list signed off
      - timeline and milestone dates confirmed

  - name: model-structure
    gate_criteria:
      - model architecture decision logged
      - tab structure documented
      - version control approach agreed

  - name: data-population
    gate_criteria:
      - all data sources received
      - data provenance documented for each input
      - spot-check validation complete

  - name: validation
    gate_criteria:
      - independent review conducted
      - all review comments resolved or escalated
      - validation sign-off recorded (meeting record: outcome=approved)

  - name: sensitivity-analysis
    gate_criteria:
      - sensitivity ranges agreed with client
      - scenario documentation complete

  - name: delivery
    gate_criteria:
      - final model version in document index (status=delivered)
      - client acceptance recorded
      - handover documentation complete

Step 2: Reporting matrix for a financial modelling engagement

entries:
  - stakeholder_group: modelling_team
    report_type: internal_status
    cadence: weekly
    format: slack_message
    surface: slack

  - stakeholder_group: client
    report_type: model_progress_update
    cadence: weekly
    format: email_draft
    surface: gmail
    notes: "include: current version status, decisions pending client input, next delivery date"

  - stakeholder_group: reviewers
    report_type: review_request
    cadence: on_milestone
    trigger_milestones: ["model-v1-complete", "post-validation-v1"]
    format: email_draft
    surface: gmail

  - stakeholder_group: client_executive
    report_type: model_summary
    cadence: on_milestone
    trigger_milestones: ["validation-complete", "final-delivery"]
    format: email_draft
    surface: gmail

Step 3: Version milestones, not saves

Financial models are versioned constantly but milestones should mark meaningful states, not every file save:

ask claude: "add milestones:
  - Model structure v1, due [date], owner: lead modeller, definition of done: tab structure built, no data populated yet, reviewed by team
  - Model v1 (data populated), due [date], owner: lead modeller, definition of done: all inputs populated from agreed data sources, formulas complete
  - Model v1 (post internal review), due [date], owner: lead modeller, definition of done: internal review complete, all issues resolved
  - Model v1 (post client review), due [date], owner: project lead, definition of done: client review cycle complete, all comments addressed or escalated
  - Validated model, due [date], owner: project lead, definition of done: independent validation sign-off obtained
  - Final model delivery, due [date], owner: project lead, definition of done: final version delivered and accepted"

The technical_progress note on each milestone captures the current model state in plain language:

ask claude: "update milestone model-v1-data-populated: 65% complete, technical progress: revenue side complete and reviewed, cost structure being finalized, waiting on [client] to confirm capex assumptions for years 3-5"

Step 4: Log every material assumption as a decision

This is the single highest-value practice for financial modelling projects:

ask claude: "log a decision: using 8% revenue growth for years 1-3, stepping down to 5% for years 4-5, rationale: in line with management guidance and supported by comparable market data from [source], alternative considered: 6% flat, approved by: CFO, date: [date]"

ask claude: "log a decision: WACC of 10.5% based on CAPM with market risk premium of 5.5% and beta of 1.2, rationale: beta sourced from peer set of [n] comparable companies, approved by: client, date: [date]"

ask claude: "log a decision: terminal value via Gordon Growth Model at 2% long-term growth, rationale: conservative approach consistent with client's industry long-term outlook, alternative considered: exit multiple method, decision: GGM preferred by client for conservatism"

When auditors, board members, or regulators ask about model assumptions, the answer is a structured log with full rationale, not a memory exercise.

Step 5: IP tracking for proprietary methodology

If your modelling firm uses a proprietary valuation methodology, scenario generation approach, or custom formula set, log it:

ask claude: "log an IP disclosure: [Firm]'s Three-Driver Revenue Attribution Model used in this engagement, disclosed to: [Client], disclosed by: [Firm], disclosure date: [date], nature: methodology-in-use, not transferred"

The IP tracker records what was disclosed, to whom, when, and under what terms. This is particularly important in engagements where methodology might be replicated by the client post-engagement.

Step 6: Handle scenario and sensitivity requests as changes

Clients always ask for additional scenarios mid-engagement. "Can you also run it at 6% growth?" is not a small request — it requires new inputs, new documentation, potentially new validation. Log it:

ask claude: "log a change: client requests bear-case scenario at 4% growth and elevated cost assumptions, classify it"

The change register classifies it as material (scope expansion), creates a record, and the next client update email references it as a pending change with timeline impact. Nothing is done informally.

Step 7: Building calculators alongside models

For calculator-style deliverables (interactive tools the client operates themselves after delivery), the project structure handles the handover:

Calculator versions become milestones:

• Calculator prototype, Calculator v1 (internal review), Calculator v1 (client acceptance test), Calculator v1 final

User documentation gets indexed:

ask claude: "add document: calculator-user-guide-v1.pdf, type: user-documentation, status: draft"

Training delivery gets a meeting record:

ask claude: "log a meeting: calculator handover and training, date: [date], attendees: [list], outcome: training delivered, follow-up: client to complete acceptance testing by [date]"

Post-delivery support gets its own phase or a dedicated support-period milestone.

The result

A financial modelling project running on project-state has:

• Every material assumption documented with rationale and approval
• A clean version history tied to meaningful milestones, not file saves
• Scope change protection via the change register
• Stakeholder-appropriate reporting: team briefs, client progress updates, exec summaries at delivery
• IP disclosure records
• A full audit trail from scoping to final delivery

The modellers model. The system governs.