> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 5 · Ask Governed Questions

> In every question below, name the entity and the source-of-truth tables. A plausible answer from the wrong (summary) table is worse than no answer — if two sources could answer,… (~20 min)

> [!WARNING]
>
> **Pin the scope** — In every question below, name the **entity** and the **source-of-truth tables**. A plausible answer from the wrong (summary) table is worse than no answer — if two sources could answer, run both and let your SME rule which is truth.

Run each of these against your validated warehouse. For every answer, note that Ana cites the governed surface, names the **basis** (incurred / earned / accident-year, by LOB), and shows the rendered SQL. The golden values below are pinned against the synthetic P\&C warehouse (window 2024, horizon 2024-12-31) in `validation/golden-queries.md` — your numbers will differ, but the *shape* and the invariants should hold.

## 5.1 · Loss ratio (the headline metric)

```text Prompt theme={null}
What's our loss ratio for accident year 2024? Use the governed definition (loss_ratio.tql) and tell me the basis — incurred or paid, earned or written premium, accident or calendar year — and why.
```

> [!TIP]
>
> **You'll see:** the governed surface return incurred losses (paid + case reserve) over earned premium, accident-year — the synthetic book pins **$94,860,400 / $173,458,746 = 0.5469**. Ana names the basis instead of silently picking one; the paid basis runs separately and comes in lower (it excludes case reserves).

## 5.2 · Combined ratio

```text Prompt theme={null}
Decompose our combined ratio for 2024 into loss ratio + expense ratio, and tell me whether we're underwriting at a profit. Use combined_ratio.tql.
```

> [!TIP]
>
> **You'll see:** the combined ratio as loss + expense — synthetic **0.5469 + 0.2500 = 0.7969**, comfortably under 100% (an underwriting profit). The invariant `combined == loss + expense` is asserted in the golden queries.

## 5.3 · Frequency and severity (the two levers)

```text Prompt theme={null}
Show me claim frequency (claims per 1,000 policies) and average claim severity (incurred per claim) for 2024. Use claim_frequency.tql and claim_severity.tql, report them together, and tell me which lever is driving the loss ratio.
```

> [!TIP]
>
> **You'll see:** frequency **521.17 / 1,000** (13,000 claims / 24,944 PIF) and severity \*\*$7,296.95** ($94,860,400 / 13,000) — paired, because the loss ratio alone hides which lever moved. Note frequency × severity ≈ pure premium (loss cost).

> [!WARNING]
>
> **Know the exposure basis** — The governed `claim_frequency` surface uses **policies-in-force** as the denominator. The actuarially correct base is **earned exposure** (car-years, house-years, payroll) — PIF is an approximation. If your warehouse carries an earned-exposure fact, re-point the denominator; Ana will say which it used rather than imply it's earned exposure. See `notes/frequency-severity.md`.

## 5.4 · Reserve position

```text Prompt theme={null}
Show our reserve position for the open book — case reserves, paid-to-date, incurred, and the reserve ratio. Use reserve_position.tql and tell me explicitly whether this is case-incurred or ultimate.
```

> [!TIP]
>
> **You'll see:** the open book at case **$32,340,903** · paid **$12,936,361** · incurred **\$45,277,264** · reserve ratio **0.7143** — with Ana stating plainly that this is **case-incurred, not ultimate**.

> [!WARNING]
>
> **Where's IBNR?** — The governed surface computes **case-incurred** (paid + case reserve) from the claim snapshot. **IBNR is not in raw claims** — it's a reserving-study output — so case-incurred *understates* ultimate for recent accident periods. Ana will say so rather than fabricate IBNR; the decision record in `notes/reserve-definition.md` documents the scope. If you have an actuarial ultimate/IBNR table, add it as a backing.

> [!NOTE]
>
> **Why everyone gets the same number** — Loss ratio, combined ratio, and reserves can each be computed several ways. The ontology pins one governed definition — incurred / earned / accident-year, with the decision recorded in `ontology/notes/` — so Actuarial, Underwriting, and Finance stop disagreeing about which number is "the" number.

## 5.5 · When the answer isn't governed yet — watch the model grow

Now ask something from your shortlist that the starter **doesn't** already cover — your earned-exposure fact, a reinsurance treaty structure, a loss-development triangle, the actuarial ultimate/IBNR table. This is the important beat: a starter pack is a head start, not the finished model.

```text Prompt theme={null}
Here's a question from our shortlist that isn't in the governed surfaces yet: [your question]. Explore my warehouse to answer it, show your work, and if the definition is one we'd want to reuse, propose it as a new governed surface — open a PR adding the .tql and a notes file recording the decision and the basis.
```

> [!TIP]
>
> **You'll see:** Ana explore only the *frontier* (not re-derive the whole warehouse), answer, and propose a **write-back** — a new metric committed to your repo with provenance. Review and merge it, and the next person who asks gets the governed answer for free. That's the malleable loop: the ontology you ship is the one you grow, and it gets more complete every time you use it.

> [!WARNING]
>
> **You ratify; high-stakes definitions get review** — Ana proposes; humans ratify via normal git review. Anything in `governance-pii.md` scope (fair pricing, reserve MNPI, medical-claim sensitivity) or a core ratio surface should require review before merge (CODEOWNERS-style) — see `STANDARDS.md`. The point isn't to let an agent rewrite your model unsupervised; it's that discovered knowledge is *captured* instead of re-discovered next time.

### ✅ Checkpoint

* [ ] Loss ratio, combined ratio, frequency/severity, and reserves all answered through governed surfaces, SQL and basis shown
* [ ] You can point to the notes file explaining at least one metric's definition decision
* [ ] Ana proposed a write-back for a not-yet-governed question — and you saw it land as a PR


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.