> ## 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 and shows the rendered SQL.

## 4.1 · Prevalence (the "diabetes question")

```text Prompt theme={null}
How many members have diabetes? Use the governed prevalence definition and tell me which codes/grouper you used and why.
```

> [!TIP]
>
> **You'll see:** the whole ICD-10 branch handled by the grouper — one consistent, defensible number, not a guess over 70,000 codes.

## 4.2 · Cost PMPM

```text Prompt theme={null}
What's our cost PMPM for the last 12 complete months, broken down by month? Use the governed definition and show the member-month denominator logic.
```

## 4.3 · Readmissions

```text Prompt theme={null}
What's our 30-day readmission rate for the last complete quarter? Walk me through the governed definition — index admissions, exclusions, and the window.
```

## 4.4 · Utilization and risk

```text Prompt theme={null}
Show inpatient utilization per 1,000 members for the last year, and then the comorbidity/RAF profile of our highest-cost decile. Cite the governed surfaces you used.
```

> [!TIP]
>
> **You'll see:** utilization normalized the standard way, and risk wired to the official CMS HCC model — including the HCC hierarchy (trumping) and a by-HCC breakdown of what drives the score.

> [!WARNING]
>
> **Know what RAF means here** — The governed surface computes the **diagnosis-driven HCC portion** of RAF. The full CMS RAF adds demographic (age/sex) and interaction terms — which require demographic fields your eligibility data may not carry. Ana will say so rather than fabricate; the decision record in `ontology/notes/` documents the scope.

> [!NOTE]
>
> **Why everyone gets the same number** — Metrics like PMPM and readmission can be computed several ways. The ontology pins one governed definition — with the decision recorded in `ontology/notes/` — so Finance and Quality stop disagreeing.

## 4.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. 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.
```

> [!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-phi.md` scope or a core metric 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

* [ ] All four question families answered through governed surfaces, SQL 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.