Skip to main content
Why a healthcare starter exists at all: raw codes are unusable. There are ~70,000 ICD-10 codes — “how many members have diabetes?” isn’t one code, it’s a whole branch. The starter pre-maps those into meaningful groups using public AHRQ/CMS standards, pins one governed definition for contested metrics like PMPM and readmission, wires risk adjustment (HCC/RAF) to the official CMS model, and makes HIPAA-aligned behavior the default.

​
The six layers

LayerWhereWhat
1 — Entity spineontology/schema.tql, ontology/relations/Member, Provider, Coverage, Medical/Pharmacy Claim, Encounter, Diagnosis, Procedure, Drug.
2 — Metricsontology/queries/Governed surfaces: PMPM, readmission, prevalence, comorbidity/RAF, utilization/1000, Rx adherence, HEDIS template.
3 — Terminologyontology/dimensions/, filters/, reference/terminology/The heart. ICD-10 hierarchy + groupers (CCSR, CMS-HCC, CCW) as dimensions, filters & committed crosswalks.
4 — Governance & PHIontology/notes/governance-phi.md, config/org_context.mdHIPAA minimum-necessary, <11 suppression, 42 CFR Part 2.
5 — Decision recordsontology/notes/Why each metric is defined the way it is; canonical grouper per question; the glossary, claim-grain, and join-verification guides.
6 — Validationvalidation/validate_tql.py (every surface checked against your live schema + compiled), golden queries with pinned values, the dry-run + A/B playbooks.
Standards alignment —STANDARDS.md maps the model to the industry data models it aligns with (Tuva, OMOP, FHIR, X12). The semantic layer (metrics, routing, terminology) is fully separated from the physical mapping: every physical table name lives in one file, ontology/schema.tql — re-point it and the metric logic stays put. The starter is authored Redshift-first with BigQuery equivalents inline; MIGRATION.md is the 8-step re-point checklist and works the same for commercial, Medicare, or Medicaid warehouses on Redshift, BigQuery, Snowflake, or Databricks (budget: about a half-day with warehouse access). For a deep technical tour, read DEEP_DIVE.md.

​
✅ Checkpoint

  • You can name the six layers and find each one in the repo
  • You know which code systems ship in the box vs. need your own license/key
  • You know the default dialect (Redshift-first, Tuva-shaped) and where BigQuery notes live
Two rules for a long, live session —1 · Checkpoint every couple of modules. Long threads have a ceiling. After every module or two, ask Ana: “Save a handoff document summarizing what we’ve built, what we decided, and what’s next — so we can continue in a new thread.” If a thread ever maxes out, you lose nothing.

2 · Pin the scope in every prompt. Name the entity and the source-of-truth tables in each prompt (“…for [entity X], using the [base] tables, not the summary table”) — otherwise Ana may drift to a convenient summary table or query every source at once.