Skip to main content

​
7.1 · Reconcile against a number someone already trusts

Trust in insurance analytics is earned on the first matching number — and lost the first time a loss ratio is quoted on the wrong basis. The starter’s golden values are already pinned and verified against the synthetic warehouse (see validation/golden-queries.md — loss ratio 0.5469, combined 0.7969, reserve ratio 0.7143, retention 0.5004). Against your warehouse, reconcile each governed surface to a number an actuary or finance lead already trusts:
Prompt
You’ll see: accuracy checked, not asserted — and a triage of any mismatch into data vs. definition vs. basis. The decisive moment is the first time the accident-year loss ratio lands exactly where the actuary expected.

​
7.2 · Assert the invariants

Even before you have an external reference, some numbers must agree with each other. The golden queries assert these:
Prompt
You’ll see: internal consistency proven — if combined ≠ loss + expense, or PIF disagrees between two surfaces, something is wrong before a stakeholder ever sees the number.

​
7.3 · Customize a definition — the written-vs-earned premium lesson

Your carrier inevitably defines something differently — a loss-ratio basis (net vs. gross, with or without LAE), a retention basis, an in-force definition. But the starter’s flagship field lesson is one every carrier hits, and it makes the perfect worked example because it’s a real bug that was found and fixed in this very repo:
The ~12× premium-inflation bug — The reference model pre-earns premium into a monthly premium_earned fact — one row per policy per month. Written premium is booked once at inception for the whole term, so it repeats across every one of those monthly rows. An early version of earned_premium did SUM(written_premium) off that monthly series — which inflated written premium ~12× (roughly one duplicate per month of term). The fix: report earned premium (sum the monthly earned series — that is correct, it recognizes over time) and pull written premium from the policy grain, never the earned series. Documented in notes/premium-definition.md and validation/golden-queries.md → Issue found & fixed.
Prompt
You’ll see: the most expensive ratio bug in P&C demonstrated on your own data and then guarded against — the earned-vs-written discipline confirmed in the surface, and any carrier-specific basis change landing as a reviewable PR in your repo with a pinned golden value. The template stays pristine upstream; your adaptations are yours.

​
7.4 · Localize the vocabulary

ontology/notes/glossary.md holds the canonical insurance terms — policy, policyholder, coverage, written vs. earned premium, loss/combined ratio, incurred/case/IBNR/ultimate, frequency/severity, retention, PIF, line of business, peril — each with a variance column flagging where your carrier or line of business diverges (life “policy ≈ contract on a life” vs. P&C term policy; gross vs. net of reinsurance; renewal-as-flag vs. successor-policy link; PIF as bound vs. issued vs. paid).
Prompt
You’ll see: the vocabulary localized in one reviewable pass — so “earned premium,” “incurred,” and “in force” mean your carrier’s thing, everywhere, from now on.
Two habits as you make it yours — 1 · Write for the search box. As you extend the kit, keep a short README per folder and repeat the phrases your teams actually use (metric names, synonyms, team names) in the prose — future threads find context by search, not browsing.

2 · Let usage drive the roadmap. Stand up a weekly gap-review playbook: mine repeated questions, manual SQL, and mid-thread corrections; have Ana draft small reviewable patches; a named owner approves. The kit is the seed — usage is what grows it. (See Ontology Operations Module 4.)

​
✅ Checkpoint

  • Governed surfaces reconciled to a trusted reference; any drift triaged (data / definition / basis)
  • The written-vs-earned trap demonstrated and guarded against on your data
  • One definition is now yours — PR’d, noted, and pinned with a golden-query test