Give every AI financial model a convention contract

The costly errors start before the formula

Ask three analysts to “update the forecast” and they may use three different meanings of revenue, cost sign, FX rate, actual/forecast cutover, or management EBITDA. An AI agent is faster at applying whichever interpretation enters context. Speed turns ambiguity into a wider, cleaner-looking error.

A new open-source project called FINANCE.md proposes a compact Markdown and YAML file for financial-model conventions. Its analogy is familiar to developers: a repository can carry standing instructions such as AGENTS.md; a model workspace can carry purpose, currency, sign, calendar, source, owner, glossary, and policy context. The idea is useful because these rules often live in an analyst's memory, a hidden “Read me” tab, old emails, or repeated prompts.

The evidence boundary matters. The focused September 9 scan found the project at two GitHub stars and no exact practitioner adoption cluster. It is a new pattern, not an established finance standard. This guide does not copy its file or claim market momentum. It combines the pattern with established professional guidance. ICAEW emphasizes consistent units and signs, clear documentation, version control, and review. The Government Actuary's Department checks calculations, data, assumptions, methodology, documentation, challenge, and communicated uncertainty. The AQuA Book applies proportionate assurance to analytical work, including black-box and AI analysis.

The resulting control is straightforward: compile one effective convention contract, freeze it with the model and inputs, verify the model against it, challenge the outputs independently, and release only the exact reviewed artifacts. The contract reduces ambiguity. It does not replace modelling competence, accounting policy, data ownership, or professional judgment.

Make model meaning machine-readable and reviewer-readable

The file should begin with a narrow identity block, then explain the conventions in plain language. Use stable IDs and explicit versions. State the model's purpose and prohibited uses before listing mechanics. A liquidity forecast for weekly treasury decisions is not automatically fit for covenant reporting, valuation, or audited financial statements, even when the formulas overlap.

---
model_id: subscription-plan-fy27
contract_version: 1.4.0
model_version: FY27-v12
owner: fpanda:planning-lead
purpose: Board-approved annual plan and monthly reforecast
prohibited_uses: [statutory_reporting, tax_filing, lender_certificate]
presentation_currency: USD
scale: thousands
fiscal_year_end: "2027-01-31"
actuals_through: "2026-08-31"
sign_convention:
  revenue: positive
  opex: negative
  assets: positive
  liabilities: positive_on_balance_sheet
accounting_basis: management_reporting
source_snapshot: erp-close-2026-08-final
scenario: base
review_due: "2026-10-05"
---

The body should define the scope, glossary, calendar, FX policy, unit and sign rules, accounting or management basis, consolidation perimeter, assumption register, scenario mechanics, model structure, output precision, controls, owners, and override procedure. It should point to sources rather than embedding sensitive extracts. Each material assumption needs a value, dimension, effective period, rationale, source, owner, sensitivity, and expiry.

Do not ask the AI to infer meaning from colors. Formatting may communicate intent to a human, but it is not a durable contract. A blue font may mean hardcode in one team and imported data in another. A negative number may mean cost in a calculation sheet and credit on an accounting input. The contract names the convention; validation checks the model location against it.

Compile inherited rules into one effective contract

Large organizations already have layers of convention. The group may define fiscal calendar and data classification. A business unit may define management metrics. A transaction team may set a presentation currency. A specific model may need a different unit scale or scenario. Letting the agent read four files and “apply common sense” creates hidden precedence.

Use an explicit hierarchy and compile it before model work begins. Organization controls outrank local convenience. Domain policy can override a general modelling preference only within its authority. Model-specific exceptions need a reason, owner, effective period, and approval. The compiled result should contain no unresolved duplicate keys. Preserve the source layer of every final rule.

Version the source contracts and the compiled contract. A reviewer should be able to answer: Which inherited rules applied? Which values changed? Which overrides were approved? Which outputs were affected? If a group calendar changes after a model is released, the old release must remain reproducible while the active model is marked for review.

A useful compiler fails closed. It rejects ambiguous date formats, missing dimensions, incompatible accounting bases, duplicate metric definitions, expired sources, unauthorized overrides, and circular inheritance. It should not choose the “most specific” rule when the parent explicitly forbids override.

Turn conventions into deterministic tests

A contract creates value when it changes review behavior. Map each consequential rule to a model location and test. Check that imported values share the declared period and scale. Reperform FX conversions. Trace sign transitions through statements and cash flow. Confirm the actual/forecast boundary. Recalculate material formulas independently. Test that each scenario changes only approved drivers and returns to base without residue.

for rule in effective_contract.rules:
    targets = locate_model_targets(rule.applies_to)
    if targets.is_empty():
        record_exception(rule, "No model target")
        continue

    result = run_deterministic_check(rule, targets, input_snapshot)
    record_receipt(rule.id, result.expected, result.observed,
                   result.tolerance, result.evidence)

require(balance_sheet_check == 0)
require(cash_roll_forward_check == 0)
require(actual_forecast_overlap_count == 0)
require(unresolved_material_exceptions == 0)

A zero balance check is necessary but weak. A model can balance with a wrong currency, duplicated source extract, stale forecast boundary, or assumption entered in the wrong unit. Layer the review: source completeness, dimensional consistency, formula integrity, statement and schedule tie-outs, scenario behavior, historical reasonableness, independent challenge, and communicated uncertainty.

The AQuA Book's proportionate approach is useful here. A small internal sensitivity may need documented peer review. A model driving investment, liquidity, pricing, covenant, public reporting, or workforce decisions may need independent model assurance, policy specialists, change control, and governance committee approval. The AI tool does not decide the assurance level.

Keep generated narrative downstream of verified numbers. If the model changes, invalidate the commentary. If the contract changes, rerun affected tests. If the source snapshot changes, reperform the transformations and tie-outs. Every output should carry the exact model, contract, source, and scenario identifiers that produced it.

Worked example: one forecast, three silent convention conflicts

A regional team asks an AI agent to update a twelve-month cash forecast. The group template uses USD thousands and treats operating costs as negative. The regional source file is in EUR units with costs positive. August actuals closed on September 6, but the model contract still says actuals through July. A local scenario sheet uses calendar months while the group model follows a 4-4-5 fiscal calendar.

A prompt-only workflow says “update the forecast using the new file.” The agent imports EUR values as USD thousands, reverses some costs twice, appends August as forecast even though it is now actual, and aligns scenario volumes to calendar month-end. The cash curve looks plausible because the errors offset. The balance sheet still balances.

The convention workflow freezes the artifacts and compiles the hierarchy. It detects that the source currency and scale conflict with the presentation rule, the actual/forecast boundary is stale, and the scenario calendar has no authorized mapping. It opens three exceptions instead of guessing. Treasury approves the period FX source and method. FP&A refreshes the actuals boundary. The model owner supplies a reviewed 4-4-5 mapping for the local volume plan.

Tests reperform the EUR-unit to USD-thousand conversion, check cost signs at import and output, prove that August appears exactly once as actual, and reconcile scenario volume across fiscal weeks. An independent reviewer compares the revised cash path with bank statements, prior forecast, known payment terms, and a simple challenger model. The release receipt binds the contract, source files, model, scenario, outputs, exceptions, and approvals. The original files remain unchanged for reproduction.

Assign meaning to qualified owners

The model owner coordinates the artifact but should not own every fact. Treasury owns FX and liquidity policy. The Controller or accounting-policy group owns reporting basis and treatment. FP&A owns planning definitions and business assumptions within its mandate. Data owners attest source extracts. Tax, Legal, model-risk, internal audit, or external assurance may be required for specific uses.

AI can make the ownership gap visible. It can produce a precedence table, highlight an assumption without a source, show which formulas depend on a changed sign rule, draft reviewer questions, and compare the output with supplied history. It must not turn “unresolved” into a confident default or manufacture an owner.

Separate builder and reviewer where consequence warrants it. A reviewer needs the effective contract, model map, change diff, source register, test receipts, exception register, challenger results, and output pack. Review comments should reference exact cells, ranges, functions, contract keys, and versions. “Looks reasonable” is not an auditable conclusion.

Failure modes the contract must expose

A 30-day pilot that tests the control, not the novelty

Days 1-5: choose one recurring, decision-relevant model with a clear owner. Inventory existing instructions, units, signs, calendars, policy references, sources, assumptions, scenarios, checks, outputs, and reviewers. Record current defects and review effort before adding AI.

Days 6-12: draft the layered convention files and compile one effective contract. Run conflict detection. Have domain owners approve definitions and exceptions. Map material rules to deterministic tests. Keep AI in read-only analysis mode.

Days 13-20: let the AI prepare a controlled update on a copy. Test mixed currencies, wrong scales, sign flips, stale actuals, leap periods, broken links, hardcodes, copied formulas, scenario residue, expired assumptions, and output invalidation. Require independent recalculation of material paths.

Days 21-30: compare defects found, accepted rework, reviewer time, exception age, model reproducibility, and decision quality with baseline. Expand only if the contract stays current, tests catch seeded failures, reviewers understand the evidence, and ownership is staffed. Approval attaches to the exact tool, workflow, model class, contract, and control set.

Frequently asked questions

What is a FINANCE.md convention contract?

It is a versioned, human-readable file that states how one model interprets purpose, scope, currency, units, signs, periods, policy basis, sources, owners, scenarios, outputs, and overrides. The name comes from a new open-source proposal; the control pattern works with another filename or schema.

Does it replace the model's instructions tab?

It can complement it. Keep user-facing instructions in the workbook, but use a diffable contract as the review and automation source. Generate or reconcile the workbook notes from the approved contract rather than maintaining two conflicting truths.

Does a convention contract replace model review?

No. It makes intended behavior explicit and testable. Reviewers still verify sources, assumptions, formulas, scenarios, outputs, uncertainty, limitations, and exact release artifacts.

Can AI approve a financial model?

AI can prepare evidence and flag exceptions. A named Finance owner and any required independent, policy, data, tax, treasury, legal, audit, or model-risk reviewer must approve within their authority.

Should every model have its own contract?

Consequential or reused models should have one effective contract. They may inherit approved organization rules, but model-specific values and overrides must be explicit, justified, versioned, and frozen at release.

Sources and evidence notes

1. FINANCE.md repository - first-party proposal for a financial-convention file; observed at two stars on September 9, 2026 and treated here as an emerging pattern, not an industry standard.
2. ICAEW Financial Modelling Code - professional guidance on robust, understandable, reviewable models.
3. ICAEW: clarity, units and sign convention - detailed treatment of units, signs, consistency, and labelling.
4. ICAEW Best Practice Guideline: Financial Modelling - version control, assumption ownership, documentation, and model handling.
5. Government Actuary's Department: model quality assurance - verification of calculations, data, assumptions, methodology, documentation, challenge, and uncertainty.
6. UK Government Analysis Function: The AQuA Book - proportionate assurance, black-box and AI analysis, maintenance, continuous review, and third parties.
7. UK Government Growth Hub: Financial Model Essentials - transparent, defensible, source-backed assumptions and sensitivity analysis.
8. FAST Standard Organisation - independent framework for flexible, appropriate, structured, and transparent financial models.
9. UK Government: Service Costing in Government - current guidance on assumptions, unit costs, version control, validation, uncertainty, and proportionate review.
10. Finance Skills for AI Agents - public finance-skill project with provenance, deterministic tooling, fixtures, and evaluation controls; used as a workflow reference, not copied.

This is operating guidance, not accounting, audit, investment, tax, or legal advice. Applicable standards, assurance requirements, materiality, and sign-off depend on the entity, jurisdiction, model use, policy, contract, and decision consequence.