Practitioner guide
Documenting model assumptions — a practical guide
Why this matters: A model can calculate perfectly and still be undefendable if nobody can tell which inputs were deliberate, which were inherited, and which were placeholders.
Good documentation is not bureaucracy. It is how you — and anyone reviewing your work — know what the model assumes about the world.
What counts as an assumption
In practice, an assumption is any input or rule that could reasonably have been different and would change an output someone cares about:
- Discount rates, growth rates, margins
- Timing flags, conversion factors, indexation rules
- Contractual floors and caps
- Scenario selectors and case definitions
- Hard-coded literals sitting inside formulas
If changing it would change a decision, treat it as an assumption even if the cell looks innocuous.
Minimum viable documentation
You do not need a novel. You need traceability:
| Element | Good enough |
|---|---|
| Label | Plain English on the same row or a linked input sheet |
| Source | Management, market data, contract, prior model — one phrase |
| Unit / basis | %, currency, per annum, nominal vs real |
| Owner | Who last changed it (optional but valuable in teams) |
| Status | Base / downside / sensitised — if scenarios apply |
If a driver has no label anywhere on its row, treat that as a defect to fix before external review.
Common patterns that create risk
- Constants embedded in formulas — fast to build, hard to audit later.
- Ghost inputs — values that nothing references (orphans) or references nothing uses.
- Scenario ambiguity — unclear which case is active when the file is saved.
- Inherited tabs — old assumptions still feeding totals under new labels.
A verification pass is designed to surface these patterns so you fix them while context is fresh.
How to read an assumptions summary
When a tool reports "documentation coverage," read it as a map, not a grade:
- High coverage — most drivers have identifiable labels; remaining gaps are worth a short sprint.
- Low coverage — expect more back-and-forth in external review; prioritise labels on material drivers first.
Improve documentation on the top ten drivers by impact before polishing immaterial cells.
Workflow suggestion
- Freeze a scenario case you intend to present.
- Label material drivers on the input sheet.
- Run a verification pass; fix Critical/High documentation and logic issues.
- Export or summarise what changed for your reviewer.
- Re-run after material edits.
Synergy with external review
External reviewers spend less time reconstructing your intent when assumptions are visible. That can mean shorter review cycles, more attention on judgement calls instead of archaeology, and clearer sign-off scope — what was in scope vs what you fixed pre-review.
Kalc is designed to help you prepare that pack — not to replace the reviewer.
Next step
Request beta access at kalc.tech.