> ## 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.
</Warning>

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

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

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

<Check>
  **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.
</Check>

<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.
</Warning>

<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.
</Note>

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

<Check>
  **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.
</Check>

<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.
</Warning>

### ✅ 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