2.1 · The dry run — required
Prompt
You’ll see: Ana discover your schema, diff it against the ontology, and hand you a precise list of fixes — table backings, column names. (A ready-made version of this check lives in
validation/dry-run-prompt.md.)2.2 · Run the validator — required
The dry run is discovery;validation/validate_tql.py is the mechanical gate. It verifies every governed surface against your warehouse: each logical name resolves, each referenced column exists, each query compiles. Ana runs it for you — no terminal needed:
Prompt
You’ll see: the typo’d-backing, wrong-alias, and missing-column bug classes caught here — instead of surfacing as wrong numbers in front of stakeholders.
Prefer the terminal? —The same gate runs locally:
python3 validation/validate_tql.py (static — no warehouse needed) · --check-sql (paste the output into Ana: rows = missing columns) · --dsn "<dsn>" --explain (live column check + compile test).2.3 · Apply the fixes as a PR — required
Prompt
You’ll see: Ana edit the files and open a reviewable PR in your repo. Every physical table name lives in one place (
ontology/schema.tql) — re-point it and the metric logic stays put. If you have a real member/patient table, point person_grain at it: one line.
Validation lands as a reviewable PR — not silent edits.
Why this step matters —Every customer’s warehouse differs from the reference shape somewhere — a renamed column, a missing table, a different grain. Finding those before you trust a number is the difference between a defensible metric and a debugging session in front of stakeholders.
2.4 · Decide your claim grain & verify your joins — required
Two decisions shape everything downstream, and both are prompts:Prompt
You’ll see: the grain decision made and written down before anything gets edited — it shapes every other step.
Prompt
You’ll see: a join-by-join verdict list. Even the starter’s own demo schema teaches the lesson — there’s no
patient table (demographics live on eligibility) and codes live in normalized_code. Expect quirks like these in yours.Prompt
You’ll see: the enumerations the validator can’t know, corrected from your real data instead of assumed.
The full checklist —This module covers the core;
MIGRATION.md is the complete 8-step re-point (discover → grain → schema.tql → joins → validator → literals → governance → glossary → goldens). Half a day with warehouse access; most of it is verification, not editing.Different warehouse dialect? —The starter is authored Redshift-first with BigQuery equivalents inline. On Databricks, Snowflake, or another engine, extend the dry-run ask: “…also flag any Redshift-specific SQL in the .tql surfaces and propose [dialect] equivalents.” Dialect adaptation rides the same PR loop as schema fixes.
✅ Checkpoint
- Ana produced a concrete mismatch list (or confirmed a clean match)
- The fixes landed as a PR you can review — not silent edits
- You merged the PR (or know who reviews it)
Verify the pack’s assumptions against your data
This starter already handles the healthcare cases that break naive ontologies — claim adjustments and reversals, dual-eligible members, capitated and encounter data — but it assumes a representation. Confirm yours matches before you trust the numbers.Prompt