> ## 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 3 · Track A: First Governed Metric

> The rule of thumb: if two users could ask the same business question with different filters, groupings, time windows, or output columns, the surface should expose those choices … (~25 min)

## 3.1 · Draft the ontology + a first metric

```text Prompt theme={null}
Using the schema and the docs we just drafted, propose the ontology: the core entities, the metrics to govern, and the dimensions. Draft the first query-surface .tql, give every metric a stable alias, and render the SQL before executing.
```

<Check>
  **You'll see:** generated `.tql` and the exact, inspectable SQL. Run it to get the answer.
</Check>

## 3.2 · Make it reusable, not one-off

**The rule of thumb:** if two users could ask the same business question with *different filters, groupings, time windows, or output columns*, the surface should expose those choices as **typed parameters** — not hard-code one answer. A rigid one-off query answers today's question; a parameterized surface answers the next hundred.

```text Prompt theme={null}
Take the query surface you just drafted and make it reusable rather than one-off: expose the metrics, dimensions, filters, and time window as typed parameters with approved options (label sets the caller picks from - the ontology owns the SQL). Document what each parameter expects in comments directly above it. If the entities or joins would be reused by other questions, split them into a reusable object module the surface imports. Show me the before/after.
```

<Check>
  **You'll see:** the same metric, but now callers pick metrics/dimensions/filters from approved options instead of triggering a rewrite — one governed surface serving many questions. Joins live once, in a reusable module.
</Check>

<Note>
  **Why this matters** —

  This is also the durable answer to "how do I stop Ana rediscovering our join paths": model joins as **reusable fragments** once, governed, and every later question routes through them. Reusable parameters are what make Module 5's "update without rebuilding" cheap.
</Note>

## 3.3 · Save it to the ontology

```text Prompt theme={null}
Save the docs, the metric definitions, and the .tql surfaces into the ontology so they persist and are reusable across sessions.
```

<Check>
  **You'll see:** the ontology files written to the repo — the basis for everything that follows.
</Check>

## 3.4 · Make it findable — for the next chat

Discoverability is part of the deliverable, not cleanup. A future thread won't know your filenames — it will *search*. Optimize for that:

```text Prompt theme={null}
Add a short routing README to the ontology folder you just wrote: what lives here, when to use it, and which files are canonical. Use searchable filenames and headings, and deliberately include the phrases people will actually ask for (the metric names, their synonyms, the team and role names). Link it from the ontology's top-level entry point so the path is broad to narrow: entry point -> overview -> this folder -> the file.
```

<Check>
  **You'll see:** a small README whose prose repeats the likely search terms on purpose — exact-match search is often the fastest retrieval path for a future agent.
</Check>

### ✅ Checkpoint

* [ ] You read the rendered SQL before executing it
* [ ] Every metric got a stable alias
* [ ] The docs and .tql surfaces are saved to the ontology repo
* [ ] Your surface exposes typed parameters (metrics / dimensions / filters / window) — not one hard-coded answer
* [ ] A routing README exists, with the search terms a future chat would use