Recipe: Financial modelling and calculator construction with project-state
April 28, 2026recipefinancial-modellingtutorialdecision-logip-tracking
# 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
| Financial modelling concept | project-state concept |
|---|---|
| Model build phases (scoping, structure, population, validation, delivery) | Phase preset |
| Model versions, scenario variants | Milestones + document index |
| Key assumptions, methodology choices | Decision log |
| Client, reviewers, auditors | Stakeholder groups |
| Review cycles, client updates | Reporting matrix |
| Scope changes (new scenarios, new line items) | Change register |
| Proprietary methodology, custom formulas | IP tracker |
## 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:
```yaml
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
```yaml
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.