Skip to main content
Why a P&C starter exists at all: the headline numbers are contested by construction. “What’s our loss ratio?” isn’t one query — it depends on paid vs. incurred losses, written vs. earned premium, and accident vs. calendar year, and a naive answer silently mixes them. The starter pins one governed definition for each contested metric, externalizes the NAIC line and peril rollups so they aren’t hard-coded, makes fair-pricing and PII behavior the default, and writes down the reasoning so a stakeholder can argue with the definition, not the number.

​
The six layers

LayerWhereWhat
1 — Entity spineontology/schema.tql, ontology/relations/Policyholder, Policy, Coverage, Premium (earned), Claim, Claim transaction, Producer.
2 — Metricsontology/queries/Governed surfaces: earned premium, loss ratio, combined ratio, claim frequency, claim severity, reserve position, retention rate, new business, policies in force.
3 — Classificationontology/dimensions/, filters/, reference/terminology/The heart. NAIC line-of-business + peril/cause-of-loss grouping (with cat flag) + geography — as dimensions, filters & committed seeds.
4 — Governance & PIIontology/notes/governance-pii.md, config/org_context.mdIdentifier inventory, <5 small-cell suppression, fair-pricing/redlining, medical-claim sensitivity, reserve MNPI.
5 — Decision recordsontology/notes/Why each metric is defined the way it is — loss-ratio basis, written-vs-earned, case-vs-IBNR reserves, frequency×severity; plus the glossary, grain, and identity guides.
6 — Validationvalidation/validate_tql.py (every surface checked against your live schema + compiled), golden queries with pinned values, the dry-run prompt.
Standards alignment — STANDARDS.md maps the model to the industry standards it aligns with (ACORD, NAIC annual statement, FIBO, ISO statistical plans, SAP/GAAP). The semantic layer (metrics, routing, classification) is fully separated from the physical mapping: every physical table name lives in one file, ontology/schema.tql — re-point it and the metric logic stays put. The starter is authored against a generic policy-admin + claims model with ANSI/Spark-portable SQL; MIGRATION.md is the 8-step re-point checklist and works the same on Redshift, BigQuery, Snowflake, or Databricks (budget: about a half-day with warehouse access). For a deep technical tour, read DEEP_DIVE.md.

​
✅ Checkpoint

  • You can name the six layers and find each one in the repo
  • You know which classification ships in the box vs. needs your own licensed feed (ISO/PCS)
  • You know the default model (generic policy-admin + claims, ANSI/Spark-portable) and where re-point lives (schema.tql)
Two rules for a long, live session — 1 · Checkpoint every couple of modules. Long threads have a ceiling. After every module or two, ask Ana: “Save a handoff document summarizing what we’ve built, what we decided, and what’s next — so we can continue in a new thread.” If a thread ever maxes out, you lose nothing.

2 · Pin the scope in every prompt. Name the entity and the source-of-truth tables in each prompt (“…for [entity X], using the [base] tables, not the summary table”) — otherwise Ana may drift to a convenient summary table or query every source at once.