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

> [!TIP]
>
> **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`).

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

> [!TIP]
>
> **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`).

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

> [!TIP]
>
> **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`).

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

> [!TIP]
>
> **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.

> [!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.

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

> [!TIP]
>
> **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`).

> [!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.

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

> [!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-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.

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


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