> ## 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. The values below are the starter's **pinned golden values** from `validation/golden-queries.md` — verified against a synthetic wealth warehouse on Databricks (horizon 2026-05-31, window 2025-06-01…2026-05-31). Yours will differ; the point is that the same call gives the same number every time.

## 5.1 · AUM (the firm-wide number)

```text Prompt theme={null}
What's our firm-wide AUM as of the horizon? Use the governed point-in-time definition, then show me the average-12m (billing/KPI) basis too — and explain why they differ.
```

<Check>
  **You'll see:** AUM from the `account_value` series at one valuation date (golden: \*\*$60,372,722,173** across **102,340** open accounts), not a sum of position snapshots — and the average-12m basis (≈$58.6B) used for billing. `point_in_time ≠ average_12m`; the surface pins both (`notes/aum-definition.md`).
</Check>

## 5.2 · Net flows (organic growth)

```text Prompt theme={null}
What were net flows (net new money) for the trailing 12 months, decomposed into gross inflows and gross outflows? Use the governed definition and confirm it excludes market movement.
```

<Check>
  **You'll see:** the organic-growth number isolated from market beta (golden: net \*\*−$1,672,009,009** = in $648,148,543 + out −\$2,320,157,552), sourced from `account_value.net_external_flow` (`notes/aum-definition.md`).
</Check>

## 5.3 · Return (TWR vs MWR)

```text Prompt theme={null}
What was our time-weighted return over the trailing 12 months? Walk me through the governed definition — why TWR is the default, how flows are removed, and how it differs from the money-weighted (client-experience) number.
```

<Check>
  **You'll see:** the GIPS-standard TWR (golden: **+10.15%**), with client flows geometrically removed, and MWR (Modified Dietz) exposed explicitly — never silently swapped. They answer different questions: manager skill vs. the client's dollar experience (`notes/return-definition.md`).
</Check>

## 5.4 · Allocation and concentration

```text Prompt theme={null}
Show our asset-class allocation at the horizon, and then how many holdings exceed 10% of their account (and how many accounts that affects, with the max weight). Cite the governed surfaces, and confirm both are computed at ONE as_of_date.
```

<Check>
  **You'll see:** allocation weights that sum to 1.000 (golden: US\_EQUITY **0.4436** · FIXED\_INCOME **0.3446** · INTL\_EQUITY **0.1571** · CASH **0.0547**), and a concentration breach list (golden: **201,120** holdings >10% across **60,701** accounts, max weight **0.8601**) — both point-in-time, both vs. the *account* denominator.
</Check>

<Warning>
  **Know what concentration means here** — The governed surface flags a holding's weight in its **own account** above a threshold (default 10%), at one snapshot. `scope="issuer"` combines all share classes of one issuer — the more conservative view. Whether diversified funds are looked-through or exempt is a decision you pin (`notes/concentration-definition.md`); on the synthetic set, issuer == position because `dim_security` has no issuer grain.
</Warning>

## 5.5 · Effective fee rate (revenue quality)

```text Prompt theme={null}
What's our effective fee rate (realized yield, bps) over the trailing 12 months? Use the governed definition and show the average-AUM denominator logic.
```

<Check>
  **You'll see:** realized yield as fee revenue / average AUM × 10,000 (golden: $306,644,253 / $58,582,267,503 = **52.34 bps**), with the billing-basis *average* AUM denominator — not point-in-time (`notes/fee-definition.md`).
</Check>

<Note>
  **Why everyone gets the same number** — Metrics like AUM, return, and fee yield can be computed several ways (point-in-time vs average AUM, TWR vs MWR, gross vs net). The ontology pins one governed definition — with the decision recorded in `ontology/notes/` — so Finance, the CIO office, and the advisors stop disagreeing.
</Note>

## 5.6 · 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. (Even the synthetic dataset has honest gaps — no benchmark-return series, and undated closures — recorded openly in `golden-queries.md` and `schema-mapping.md`.)

```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-mnpi-pii.md` scope or a core metric (AUM, return, a benchmark assignment) should require review before merge — 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 five metric 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