Clarity is a health navigation companion that guides young adults through the complexity of the American healthcare system — entering at the moment of highest confusion: first open enrollment at a new employer.
Clarity's intelligence is powered by a 100-triple domain knowledge graph organized into 5 entity clusters plus 15 cross-cluster reasoning chains. The graph is user-centered — every entity exists in relation to one specific person's situation.
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 1 | User | HAS | Insurance Plan |
| 2 | User | EARNS | Income Bracket |
| 3 | User | LIVES_IN | Location |
| 4 | User | HAS_CONDITION | Health Status |
| 5 | User | CAN_AFFORD | Monthly Premium |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 6 | Insurance Plan | HAS_TYPE | HMO |
| 7 | Insurance Plan | HAS_TYPE | PPO |
| 8 | Insurance Plan | HAS_TYPE | HDHP |
| 9 | Insurance Plan | HAS_COST | Monthly Premium |
| 10 | Insurance Plan | HAS_COST | Deductible |
| 11 | Insurance Plan | HAS_COST | Copay |
| 12 | Insurance Plan | HAS_COST | Coinsurance |
| 13 | Insurance Plan | HAS_LIMIT | Out-of-Pocket Maximum |
| 14 | Insurance Plan | INCLUDES | In-Network Providers |
| 15 | Insurance Plan | EXCLUDES | Out-of-Network Providers |
| 16 | Insurance Plan | REQUIRES | Primary Care Physician |
| 17 | Insurance Plan | COVERS | Preventative Care |
| 18 | Insurance Plan | COVERS | Mental Health |
| 19 | Insurance Plan | COVERS | Prescriptions |
| 20 | Insurance Plan | COVERS | Emergency Care |
| 21 | Employer | CONTRIBUTES_TO | Monthly Premium |
| 22 | Employer | SETS | Enrollment Window |
| 23 | Employer | DEFINES | Waiting Period |
| 24 | HDHP | PAIRS_WITH | HSA Account |
| 25 | User | SELECTS | Insurance Plan |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 26 | Care System | HAS_PROVIDER | Primary Care Physician |
| 27 | Care System | HAS_PROVIDER | Specialist |
| 28 | Care System | HAS_PROVIDER | Urgent Care |
| 29 | Care System | HAS_PROVIDER | Emergency Room |
| 30 | Care System | HAS_PROVIDER | Telehealth |
| 31 | Primary Care Physician | SERVES_AS | First Point of Contact |
| 32 | Specialist | REQUIRES | Referral (HMO) |
| 33 | Urgent Care | COSTS_LESS_THAN | Emergency Room |
| 34 | Telehealth | IS_COVERED_BY | Most Modern Plans |
| 35 | Visit Type | HAS_CATEGORY | Preventative |
| 36 | Visit Type | HAS_CATEGORY | Acute |
| 37 | Preventative Visit | IS_FREE_UNDER | ACA Guidelines |
| 38 | Acute Visit | TRIGGERS | Copay |
| 39 | Emergency Room Visit | TRIGGERS | Deductible |
| 40 | Provider | HAS_STATUS | In-Network |
| 41 | Provider | HAS_STATUS | Out-of-Network |
| 42 | In-Network Provider | COSTS_LESS_THAN | Out-of-Network Provider |
| 43 | HMO Plan | REQUIRES | Referral for Specialist |
| 44 | PPO Plan | ALLOWS | Direct Specialist Access |
| 45 | User | SHOULD_VERIFY | Network Status Before Visit |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 46 | Health Event | HAS_TYPE | Preventative |
| 47 | Health Event | HAS_TYPE | Acute |
| 48 | Health Event | HAS_TYPE | Chronic |
| 49 | Preventative Event | PREVENTS | Acute Crisis |
| 50 | Annual Physical | IS_COVERED_AT | Zero Cost (ACA) |
| 51 | Blood Panel | DETECTS | Early Risk Indicators |
| 52 | Early Risk Indicator | TRIGGERS | Preventative Action |
| 53 | Preventative Action | COSTS_LESS_THAN | Crisis Treatment |
| 54 | Acute Event | TRIGGERS | Unplanned Spending |
| 55 | Mental Health Episode | IS_COVERED_BY | Modern Insurance Plans |
| 56 | Chronic Condition | REQUIRES | Ongoing Care Plan |
| 57 | Chronic Condition | INCREASES | Annual Healthcare Cost |
| 58 | Life Stage Trigger | REQUIRES | Insurance Re-evaluation |
| 59 | New Job | IS_A | Life Stage Trigger |
| 60 | Aging Out of Parent Plan | IS_A | Life Stage Trigger |
| 61 | Moving to New City | AFFECTS | Provider Network Access |
| 62 | EOB Received | REQUIRES | Plain Language Translation |
| 63 | Lab Result | REQUIRES | Contextual Explanation |
| 64 | Enrollment Window | HAS_DURATION | 2–3 Weeks |
| 65 | User | EXPERIENCES | Life Stage Trigger |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 66 | Financial Document | HAS_TYPE | EOB |
| 67 | Financial Document | HAS_TYPE | Medical Bill |
| 68 | EOB | IS_NOT | Medical Bill |
| 69 | EOB | SHOWS | What Insurance Paid |
| 70 | Medical Bill | SHOWS | Patient Responsibility |
| 71 | Itemized Bill | CONTAINS | CPT Codes |
| 72 | CPT Code | REQUIRES | Plain Language Translation |
| 73 | Surprise Bill | VIOLATES | No Surprises Act (2022) |
| 74 | Patient Responsibility | EQUALS | Bill Minus Insurance Payment |
| 75 | User | HAS_RIGHT | Request Itemized Bill |
| 76 | Hospital | OFFERS | Financial Assistance Program |
| 77 | Financial Assistance | IS_UNKNOWN_TO | Most Patients |
| 78 | HSA | REQUIRES | HDHP Enrollment |
| 79 | HSA | PROVIDES | Triple Tax Advantage |
| 80 | FSA | HAS_RULE | Use It or Lose It |
| 81 | Medical Debt | CAN_AFFECT | Credit Score |
| 82 | Payment Plan | IS_AVAILABLE_AT | Most Hospitals |
| 83 | Payment Plan | IS_UNKNOWN_TO | Most Patients |
| 84 | User | SHOULD_NEGOTIATE | Medical Bill |
| 85 | Clarity | TRANSLATES | Financial Document → Plain Language |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 86 | User (healthy, low income) | SHOULD_SELECT | HDHP + HSA |
| 87 | User (chronic condition) | SHOULD_SELECT | PPO |
| 88 | User (new city) | MUST_REVERIFY | In-Network Providers |
| 89 | Life Stage Trigger | INITIATES | Full Plan Re-evaluation |
| 90 | Preventative Visit | REDUCES | Long-Term Financial Risk |
| 91 | Unmet Deductible | AFFECTS | Cost of Acute Visit |
| 92 | HSA Balance | OFFSETS | Out-of-Pocket Cost |
| 93 | Out-of-Network Visit | GENERATES | Surprise Bill Risk |
| 94 | Surprise Bill | TRIGGERS | No Surprises Act Protection |
| 95 | Mental Health Visit | IS_COVERED_EQUALLY | Physical Health Visit |
| 96 | Annual Physical | PREVENTS | Undetected Chronic Condition |
| 97 | Undetected Chronic Condition | INCREASES | Medical Debt Risk |
| 98 | Employer | FUNDS | Clarity Access |
| 99 | Clarity | BUILDS | User Health Literacy Over Time |
| 100 | Health Literate User | COSTS_LESS_THAN | Uninformed User (to employer) |
Entity linking proves that Clarity's knowledge graph is grounded in real-world standards — not invented terminology. Each key entity is mapped to an authoritative ontology, making the graph interoperable, verifiable, and trustworthy.
| Clarity Entity | Standard / Ontology | Authority | Notes |
|---|---|---|---|
| Insurance Plan (HMO, PPO, HDHP) | HL7 FHIR Coverage Resource | HL7 International | FHIR R4 defines plan type codes used in all US payer APIs |
| Deductible / Premium / Copay / OOP Max | FHIR InsurancePlan.cost | HL7 / CMS | Standardized under ACA Section 1311 disclosure rules |
| CPT Code | Current Procedural Terminology (CPT) | American Medical Association | Required on all US medical claims; 10,000+ procedure codes |
| ICD-10 Diagnosis Code | ICD-10-CM | WHO / CDC | All US diagnoses mapped here; mandatory for billing |
| Primary Care Physician / Specialist | SNOMED CT | SNOMED International | Clinical role taxonomy; also in NPI Registry (CMS) |
| Health Status / Chronic Condition | SNOMED CT + ICD-10 | WHO / SNOMED International | SNOMED for clinical terms; ICD-10 for billing classification |
| Preventative Visit / Annual Physical | USPSTF Guidelines | US Preventive Services Task Force | ACA mandates zero-cost coverage for A/B rated services |
| HSA / FSA / HRA | IRS Publication 969 | Internal Revenue Service | Federal tax code defines eligibility, contribution limits, rules |
| Surprise Bill | No Surprises Act (2022) | US Federal Law (CMS) | Prohibits balance billing; dispute resolution process defined |
| EOB (Explanation of Benefits) | FHIR ExplanationOfBenefit Resource | HL7 / CMS | CMS requires machine-readable EOBs under Interoperability Rule |
| Mental Health Parity | Mental Health Parity and Addiction Equity Act | US Federal Law (DOL/HHS) | Requires equal coverage for mental + physical health |
| In-Network / Out-of-Network | FHIR Network Resource | HL7 / CMS | Plan network data now available via CMS Price Transparency Rule |
| User Location | FHIR Patient.address | HL7 International | ZIP-level data affects plan availability and provider network |
| Lab Result / Blood Panel | LOINC (Logical Observation Identifiers) | Regenstrief Institute | Universal standard for lab tests and clinical observations |
| Enrollment Window | 45 CFR Part 155 (ACA Regulations) | HHS / CMS | Federal regulation defines SEP and OEP timelines |
Where will Clarity's AI get things wrong — and what happens when it does? This analysis maps the highest-risk failure modes, their triggers, and the mitigation architecture built into Clarity's design.
| Failure Mode | How It Happens | Severity | Mitigation |
|---|---|---|---|
| Plan Recommendation Error | AI recommends HDHP to user with undiagnosed chronic condition — based on incomplete health history | Critical | Human consultant escalation for any recommendation involving chronic risk; disclaimer on all plan suggestions |
| Network Status Hallucination | AI states a provider is in-network based on stale training data — user gets surprise bill | Critical | Real-time FHIR network API lookup required; no static assertions about network status |
| CPT Code Mistranslation | AI translates CPT code incorrectly — user believes they were billed for wrong procedure | High | CPT translations sourced from AMA database, not LLM generation; human review for disputed bills |
| State-Specific Rule Errors | AI applies federal ACA rules without accounting for state-level variation in Medicaid, mandates, or plan types | High | User.location entity used to route to state-specific rule layer; 50-state regulatory index required |
| Financial Assistance Gaps | AI fails to surface hospital charity care programs because they are not in training data | High | RAG pipeline with live hospital financial assistance database; not LLM parametric knowledge |
| Confident Hedging on Legal Rights | AI softens user's legal rights (No Surprises Act, itemized bill right) to avoid sounding prescriptive | High | Legal rights stored as hard assertions in KG — not LLM-generated; output templated not generated |
| Deductible Math Errors | AI miscalculates remaining deductible, OOP max, or HSA contribution limit | High | Financial calculations handled by deterministic code, not LLM; LLM only provides explanation layer |
| Emotional Tone Mismatch | AI delivers bad news (high bill, denied claim) with incorrect emotional register — too clinical or too casual | Medium | Tone calibration layer in prompt architecture; human consultant available for high-stress moments |
The knowledge graph and AI architecture are strong. These are the open questions that still need answers before Clarity ships.
| # | Open Question | Impact | Mitigation Path |
|---|---|---|---|
| 1 | Will young adults trust an employer-funded health app with their personal data? | Core trust architecture assumption | Structural privacy firewall; independent data store; explicit user consent flow |
| 2 | Does giving personalized plan recommendations trigger insurance advisor licensing? | Legal/regulatory exposure | Legal review; "guidance not advice" framing; human consultant as licensed layer |
| 3 | How do we handle 50-state insurance regulation variation at scale? | Knowledge graph completeness | State-specific regulatory layer; location-aware routing in KG |
| 4 | What happens when Clarity's recommendation conflicts with the employer's cheapest plan? | Structural independence test | Fiduciary-like duty to user written into employer contract language |
| 5 | Can we source and scale high-quality on-demand health consultants? | Human layer quality + liability | Credentialing framework; scope of practice guidelines; malpractice clarity |