hhs-hcc-risk-adjustment 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "hhs-hcc-risk-adjustment",
+  "version": "1.0.0",
+  "description": "Domain expertise and computational tools for the HHS-HCC commercial risk adjustment model (ACA Individual & Small Group, BY2018–BY2027)",
+  "author": {
+    "name": "Wesley Sanders",
+    "url": "https://evensun.com"
+  },
+  "license": "MIT",
+  "keywords": ["risk-adjustment", "hhs-hcc", "aca", "cms", "health-insurance"]
+}

package/README.md

@@ -0,0 +1,227 @@
+# HHS-HCC Risk Adjustment — Claude Code Plugin
+
+A [Claude Code](https://claude.ai/code) plugin that gives Claude deep expertise in the **HHS-HCC commercial risk adjustment model** — the CMS model used to calculate risk scores and transfer payments for ACA Individual and Small Group plans. Covers the current V07 model (BY2021–BY2027) and the earlier V05 model (BY2018–BY2020), with bundled coefficient data for all ten benefit years.
+
+---
+
+## What you can ask Claude
+
+Once the plugin is installed, you can ask Claude questions like:
+
+- *"What is the BY2025 Silver coefficient for HHS_HCC042?"*
+- *"Score a 45-year-old female on a Silver CSR-1 plan with HCC042 and HCC156 flagged."*
+- *"What changed in the severity model between BY2022 and BY2023?"*
+- *"Why isn't this diabetes diagnosis contributing to the risk score?"*
+- *"If our plan has a PLRS of 1.8 and statewide PLRS is 1.5, what's our transfer?"*
+- *"Walk me through how the infant maturity × severity grid works."*
+- *"Which ICD-10 codes map to HCC018?"*
+- *"What J-codes trigger RXC_09?"*
+
+Claude answers using the bundled reference data and scripts, citing the correct CMS rules for the benefit year you specify.
+
+---
+
+## Model coverage
+
+| Sub-model | Who it covers | Key distinction |
+|---|---|---|
+| **Adult** | AGE_LAST ≥ 21 | HCC-additive; RXC interactions; severity/transplant counters; HCC_ED short-enrollment flag |
+| **Child** | AGE_LAST 2–20 | HCC-additive; same group flags as Adult; different severity bucket schema (6_7 and 8PLUS) |
+| **Infant** | AGE_LAST 0–1 | Maturity × severity interaction grid — does **not** score HCCs additively |
+
+The model family depends on the benefit year: **V07** covers BY2021 and forward; **V05** covered BY2018–BY2020. Always confirm the benefit year before interpreting a coefficient — values change annually with the NBPP.
+
+---
+
+## Slash commands
+
+| Command | What it does |
+|---|---|
+| `/hhs-hcc-score` | Guided intake → runs `score_enrollee.py` → explains the output clinically |
+| `/hhs-hcc-lookup` | Look up any coefficient by variable name, year, and metal level |
+| `/hhs-hcc-transfer` | Compute T(i) or find the Platinum inflection point; auto-populates statewide inputs by state+year |
+
+Or just ask Claude a question directly — the plugin activates automatically based on context.
+
+---
+
+## Scripts
+
+Pure Python 3.10+, stdlib only — no dependencies to install. Scripts live in `skills/hhs-hcc-risk-adjustment/scripts/`.
+
+### Score an enrollee
+
+```bash
+python3 skills/hhs-hcc-risk-adjustment/scripts/score_enrollee.py \
+  --age 45 --sex F --metal S --csr 1 --year 2025 \
+  --hcc HHS_HCC042 HHS_HCC156 --rxc RXC_09 --enrol-duration 12
+```
+
+```
+Sub-model: Adult
+Metal: S (column Silver_Level)
+BY: 2025
+
+Variable                                  ind       coef    contrib
+----------------------------------------------------------------------
+HHS_HCC042                                  1    10.9030    10.9030
+HHS_HCC156                                  1     7.4610     7.4610
+RXC_09                                      1     0.6330     0.6330
+FAGE_LAST_45_49                             1     0.2770     0.2770
+----------------------------------------------------------------------
+RAW SCORE                                                   19.2740
+CSR factor (CSR_INDICATOR=1): 1.0000
+CSR-ADJUSTED SCORE: 19.2740
+```
+
+**Key inputs:**
+
+| Flag | Description |
+|---|---|
+| `--age` | `AGE_LAST` — age on the last day of the benefit year |
+| `--sex` | `M` or `F` |
+| `--metal` | `P` / `G` / `S` / `B` / `C` (or full name) |
+| `--csr` | `RA_CSR_Indicator` — CMS internal CSR code (1 = standard/no CSR; 3 = Silver state-subsidy; 4 = ZCS Platinum; etc.) |
+| `--year` | Benefit year — selects the bundled coefficient set |
+| `--hcc` | Space-separated HCCs **after** hierarchy and group collapsing |
+| `--rxc` | Space-separated RXCs (Adult model only) |
+| `--enrol-duration` | Months enrolled (1–12) — triggers `HCC_ED` short-enrollment flag |
+| `--data-dir` | Override the bundled data with a custom coefficient directory |
+
+### Look up a coefficient
+
+```bash
+# Single metal
+python3 skills/hhs-hcc-risk-adjustment/scripts/lookup.py \
+  --year 2025 --model Adult --variable HHS_HCC042 --metal Silver
+# → 10.9030
+
+# All metals
+python3 skills/hhs-hcc-risk-adjustment/scripts/lookup.py \
+  --year 2025 --model Infant --variable EXTREMELY_IMMATURE_X_SEVERITY5
+```
+
+### Compute a risk transfer
+
+```bash
+# Transfer payment per billable member-month
+python3 skills/hhs-hcc-risk-adjustment/scripts/risk_transfer.py \
+  --plrs 1.8 --idf 1.08 --gcf 1.09 --av 0.8 --arf 1.90 \
+  --statewide-plrs 1.5 --statewide-idf 1.03 --statewide-gcf 1.0 \
+  --statewide-av 0.686 --statewide-arf 1.541 --premium 375
+
+# Inflection point: at what PLRS does Platinum beat Gold?
+python3 skills/hhs-hcc-risk-adjustment/scripts/risk_transfer.py --inflection \
+  --arf 1.541 --statewide-plrs 1.5 --statewide-av 0.686 --statewide-arf 1.541
+```
+
+---
+
+## Bundled data
+
+All data lives under `skills/hhs-hcc-risk-adjustment/`.
+
+### Coefficient CSVs — `data/BY<YYYY>/`
+
+Three files per benefit year: `adult_model_factors.csv`, `child_model_factors.csv`, `infant_model_factors.csv`. Each row is a model variable with five metal-level coefficients (Platinum through Catastrophic).
+
+| Folder | CMS source revision | Model family |
+|--------|---------------------|--------------|
+| BY2018 | `2018_DIY_120418` | V05 |
+| BY2019 | `2019_DIY_041520` | V05 |
+| BY2020 | `2020_DIY_080320` | V05 |
+| BY2021 | `2021_DIY_033122` | V07 |
+| BY2022 | `2022_DIY_122022` | V07 |
+| BY2023 | `2023_NBPP_050622` | V07 |
+| BY2024 | `2024_DIY_090624` | V07 |
+| BY2025 | `2025_DIY_072325` | V07 |
+| BY2026 | `2026_NBPP_100524` | V07 |
+| BY2027 | `2027_NBPP_020926` | V07 |
+
+Where CMS published both an initial NBPP release and a later DIY revision, the DIY revision is used — it supersedes the NBPP release and incorporates corrections.
+
+### Cross-reference tables — `data/`
+
+| File | Contents | Rows |
+|------|----------|------|
+| `hcc_labels.csv` | Human-readable label and clinical category for every HCC, group flag, RXC, and interaction variable | 210 |
+| `csr_adjustment_factors.csv` | CSR adjustment factors by CSR_Code and model year (BY2020–BY2027) | 96 |
+| `statewide_ra_factors.csv` | Statewide PLRS, IDF, AV, ARF, avg premium, and member months by state, market, and year (BY2018–BY2024) | 1,009 |
+
+### Code-mapping tables — `references/`
+
+| File | Contents | Rows |
+|------|----------|------|
+| `dx-mapping.csv` | Full ICD-10 → CC crosswalk with age/sex edits and effective date gating | 11,568 |
+| `hcpcs-rxc.csv` | HCPCS J-code → RXC mapping | 86 |
+| `ndc-rxc.csv` | NDC → RXC pharmacy mapping with start/end year | 15,134 |
+| `service-code-reference.csv` | CPT/HCPCS qualifying-service-code list | 21,109 |
+
+### Reference documents — `references/`
+
+| File | Covers |
+|------|--------|
+| `model-overview.md` | V07 architecture, sub-models, scoring formula, key terminology |
+| `adult-model.md` | Adult variables, group flags, severity/transplant buckets, HCC_ED, RXC interactions |
+| `child-model.md` | Child variables, group flags, severity/transplant buckets (note 6_7 and 8PLUS collapsing) |
+| `infant-model.md` | Maturity hierarchy, severity hierarchy, AGE0/AGE1 swap, maturity × severity grid |
+| `cc-hcc-hierarchies.md` | DX → CC mapping, CC → HCC hierarchies, group collapsing, age/sex/MCE edits |
+| `claim-qualification.md` | Which medical claims qualify for HCC scoring; why labs, DME, and J-code-only claims don't count |
+| `rxc-interactions.md` | RXC variables, RXC_06 → RXC_07 hierarchy, HCC × RXC interactions including the RXC_09 triple |
+| `csr-adjustments.md` | CSR adjustment factors by HIOS variant, RA_CSR_Indicator mapping, BY2025 schedule change |
+| `risk-transfer-formula.md` | Full CMS risk transfer formula and metal-level optimization |
+| `year-changes.md` | NBPP year-over-year model changes (BY2018–BY2027) |
+
+---
+
+## Background: what is HHS-HCC risk adjustment?
+
+Under the ACA, CMS runs a risk adjustment program across all non-grandfathered Individual and Small Group plans. Plans with sicker-than-average enrollees receive transfer payments from plans with healthier-than-average enrollees. This levels the playing field and reduces incentives to cherry-pick healthy members.
+
+The **HHS-HCC model** is the risk-scoring engine. It converts each enrollee's demographics, diagnoses (mapped from medical claims to Hierarchical Condition Categories), and pharmacy fills (mapped to RXC variables) into a **Plan Liability Risk Score (PLRS)**. The PLRS feeds into the CMS transfer formula alongside state-level Induced Demand Factors (IDF), Geographic Calibration Factors (GCF), actuarial values (AV), and allowable rating factors (ARF).
+
+CMS publishes updated model specifications annually in the **Notice of Benefit and Payment Parameters (NBPP)** and releases SAS source code, DIY Excel workbooks, and (starting BY2025) a Python package. The SAS source is the authoritative spec when sources disagree.
+
+---
+
+## Installing the plugin
+
+### Option 1 — npx (recommended)
+
+```bash
+npx hhs-hcc-risk-adjustment
+```
+
+This copies the plugin to `~/.claude/plugins/hhs-hcc-risk-adjustment/` and adds it to your global `~/.claude/settings.json` automatically. Restart Claude Code afterward.
+
+Safe to re-run — it won't add a duplicate entry.
+
+### Option 2 — manual
+
+Clone the repo and add the plugin path to your Claude Code settings.
+
+**User-level** (`~/.claude/settings.json`):
+```json
+{
+  "plugins": [
+    { "path": "/path/to/skills/hhs-hcc-risk-adjustment" }
+  ]
+}
+```
+
+**Project-level** (`.claude/settings.json` in your project):
+```json
+{
+  "plugins": [
+    { "path": "/path/to/skills/hhs-hcc-risk-adjustment" }
+  ]
+}
+```
+
+---
+
+## License
+
+Code and scripts: [MIT](../LICENSE) — © 2026 Wesley Sanders.
+
+CMS model specifications, coefficient tables, and code-mapping crosswalks are U.S. government works in the public domain (published by the Centers for Medicare & Medicaid Services under the ACA risk adjustment program).

package/bin/install.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PLUGIN_NAME = 'hhs-hcc-risk-adjustment';
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const INSTALL_DIR = path.join(CLAUDE_DIR, 'plugins', PLUGIN_NAME);
+const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
+
+// Package root is one level up from bin/
+const SOURCE_DIR = path.join(__dirname, '..');
+
+// Directories/files to skip at the top level of the package
+const TOP_LEVEL_SKIP = new Set([
+  'bin', 'node_modules', 'package.json', 'package-lock.json',
+  '.git', 'scripts', // scripts/ at plugin root is stale; real scripts are in skills/
+]);
+
+function copyDir(src, dest, topLevel = false) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') && entry.name !== '.claude-plugin') continue;
+    if (topLevel && TOP_LEVEL_SKIP.has(entry.name)) continue;
+    if (entry.name === 'node_modules' || entry.name === '__pycache__') continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    entry.isDirectory() ? copyDir(s, d) : fs.copyFileSync(s, d);
+  }
+}
+
+function patchSettings(pluginPath) {
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try { settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8')); }
+    catch { console.warn(`Warning: could not parse ${SETTINGS_PATH} — will create a new one.`); }
+  }
+
+  // Support both skills[] and plugins[] arrays
+  if (!Array.isArray(settings.plugins)) settings.plugins = [];
+
+  const already = settings.plugins.some(
+    (p) => (typeof p === 'string' ? p : p?.path) === pluginPath
+  );
+
+  if (!already) {
+    settings.plugins.push({ path: pluginPath });
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return true;
+  }
+  return false;
+}
+
+function main() {
+  console.log(`\nInstalling ${PLUGIN_NAME} plugin...\n`);
+
+  copyDir(SOURCE_DIR, INSTALL_DIR, true);
+  console.log(`  Plugin files copied to:\n    ${INSTALL_DIR}`);
+
+  const added = patchSettings(INSTALL_DIR);
+  if (added) {
+    console.log(`  Added to Claude Code settings:\n    ${SETTINGS_PATH}`);
+  } else {
+    console.log(`  Already in Claude Code settings — no change needed.`);
+  }
+
+  console.log(`
+Done. Restart Claude Code (or reload the window) for the plugin to take effect.
+
+Slash commands added:
+  /hhs-hcc-score    — score an enrollee
+  /hhs-hcc-lookup   — look up a coefficient
+  /hhs-hcc-transfer — compute a risk transfer
+
+Or just ask Claude a question about the HHS-HCC model directly.
+`);
+}
+
+main();

package/commands/hhs-hcc-lookup.md

@@ -0,0 +1,23 @@
+---
+name: hhs-hcc-lookup
+description: Look up a coefficient from the HHS-HCC model by variable name, benefit year, and metal level. Handles HCCs, group flags, RXCs, interaction terms, age/sex variables, severity/transplant counters, and infant maturity×severity variables.
+---
+
+Collect the following. If the user already provided them in their message, proceed directly.
+
+- **Variable name** — the exact model variable (e.g. `HHS_HCC042`, `G01`, `RXC_09`, `EXTREMELY_IMMATURE_X_SEVERITY5`, `SEVERE_HCC_COUNT3`, `MAGE_LAST_45_49`). If the user gives a description instead of a variable name (e.g. "heart failure"), look it up in `data/hcc_labels.csv` using Grep first.
+- **Benefit year** — BY2018–BY2027.
+- **Model** — Adult, Child, or Infant. If not provided, infer from the variable type (infant maturity/severity variables → Infant; G-prefix group flags → Adult or Child as applicable).
+- **Metal level** — Platinum, Gold, Silver, Bronze, Catastrophic. If omitted, return all five.
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/hhs-hcc-risk-adjustment/scripts/lookup.py" \
+  --year YEAR --model MODEL --variable VARIABLE [--metal METAL]
+```
+
+Present the result and add brief context:
+- What condition or model construct the variable represents
+- Whether the variable is in the severity/transplant bucket set
+- Any year-over-year note if the user might be comparing to a prior year value (check `references/year-changes.md` for changes affecting this variable)

package/commands/hhs-hcc-score.md

@@ -0,0 +1,41 @@
+---
+name: hhs-hcc-score
+description: Score an ACA enrollee under the HHS-HCC risk adjustment model. Collects demographics, flagged HCCs/RXCs, and benefit year, then runs score_enrollee.py and explains the result.
+---
+
+Collect the following inputs conversationally. If the user already provided some in their message, skip those questions.
+
+**Required:**
+- **Benefit year** — BY2018–BY2027. Always confirm this first; coefficients change annually.
+- **Age** — `AGE_LAST` (age on the last day of the benefit year)
+- **Sex** — M or F
+- **Metal level** — Platinum, Gold, Silver, Bronze, or Catastrophic
+- **CSR indicator** — the `RA_CSR_Indicator` for this enrollment span:
+  - `1` = Standard plan, no CSR (most Bronze/Gold/Platinum, and Silver plans not receiving CSR)
+  - `3` = Silver state-subsidy (HIOS variants 05/06/07, 30–36)
+  - `4` = Zero Cost Share Platinum | `5` = LCS Platinum | `6` = ZCS Silver | `7` = LCS Silver
+  - `8` = ZCS Gold | `9` = LCS Gold | `10` = ZCS Bronze | `11` = LCS Bronze | `12` = ZCS Platinum
+  - If unsure, ask for the last two digits of the 16-character HIOS plan ID.
+- **Flagged HCCs** — space-separated list of HCC variable names **after hierarchy and group collapsing** (e.g. `HHS_HCC042 HHS_HCC156`). Remind the user: inputs must be post-hierarchy; do not pass both an HCC and an HCC it supersedes.
+
+**Optional:**
+- **Flagged RXCs** — Adult model only (e.g. `RXC_09`). Skip for Child/Infant.
+- **Enrollment duration** — months enrolled (1–12). Only relevant if < 7 months and the enrollee has at least one HCC; triggers the `HCC_ED` short-enrollment flag.
+
+Once you have the inputs, run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/hhs-hcc-risk-adjustment/scripts/score_enrollee.py" \
+  --age AGE --sex SEX --metal METAL --csr CSR --year YEAR \
+  --hcc HCC1 HCC2 ... \
+  --rxc RXC1 ... \
+  --enrol-duration MONTHS
+```
+
+Omit `--rxc` if no RXCs. Omit `--enrol-duration` if not provided.
+
+After running, present the output table and then:
+1. Identify the top contributing variables and explain what each HCC/RXC/interaction represents clinically.
+2. Note any severity or transplant counter that fired and why.
+3. Show the CSR-adjusted final score and explain the CSR factor applied.
+4. Flag anything surprising (e.g. an expected HCC that didn't appear — check if it was superseded by a hierarchy).

package/commands/hhs-hcc-transfer.md

@@ -0,0 +1,61 @@
+---
+name: hhs-hcc-transfer
+description: Compute a CMS risk transfer payment T(i) per billable member-month, or find the PLRS inflection point where a Platinum metal strategy beats Gold. Optionally looks up statewide inputs from the bundled statewide_ra_factors.csv.
+---
+
+Ask the user which mode they want:
+
+1. **Transfer** — compute T(i) for a plan given its plan-level and statewide inputs
+2. **Inflection** — find the PLRS at which Platinum becomes favorable over Gold (transfer-only perspective)
+
+---
+
+### Transfer mode
+
+Collect:
+
+**Plan-level inputs:**
+- `PLRS` — Plan Liability Risk Score
+- `IDF` — Induced Demand Factor
+- `GCF` — Geographic Calibration Factor
+- `AV` — Actuarial Value (e.g. 0.80 for Gold)
+- `ARF` — Allowable Rating Factor
+
+**Statewide inputs:**
+- Statewide weighted-average PLRS, IDF, GCF, AV, ARF
+- Statewide average premium P̄
+
+**Offer to look up statewide values:** If the user provides a state abbreviation and benefit year, grep `${CLAUDE_PLUGIN_ROOT}/skills/hhs-hcc-risk-adjustment/data/statewide_ra_factors.csv` for matching rows and present the available market options (Market 1 = Individual, Market 2 = Small Group). Let the user select the right market and confirm the values before running.
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/hhs-hcc-risk-adjustment/scripts/risk_transfer.py" \
+  --plrs PLRS --idf IDF --gcf GCF --av AV --arf ARF \
+  --statewide-plrs SW_PLRS --statewide-idf SW_IDF --statewide-gcf SW_GCF \
+  --statewide-av SW_AV --statewide-arf SW_ARF \
+  --premium PBAR
+```
+
+After running, explain:
+- Whether the plan receives or pays a transfer and why (PLRS vs. statewide average, metal AV)
+- The magnitude in annualized terms (multiply per-member-month result × 12 × estimated enrollment)
+- What levers would shift the transfer (PLRS improvement, metal-level mix, GCF)
+
+---
+
+### Inflection mode
+
+Collect:
+- Plan ARF
+- Statewide PLRS, AV, ARF
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/hhs-hcc-risk-adjustment/scripts/risk_transfer.py" \
+  --inflection --arf ARF \
+  --statewide-plrs SW_PLRS --statewide-av SW_AV --statewide-arf SW_ARF
+```
+
+Explain the result: if projected PLRS exceeds the inflection point, Platinum is favorable from a transfer-only perspective. Note this is before considering the premium revenue difference between metals.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "hhs-hcc-risk-adjustment",
+  "version": "1.0.0",
+  "description": "Claude Code plugin for HHS-HCC commercial risk adjustment (ACA BY2018–BY2027)",
+  "bin": {
+    "hhs-hcc-skill": "./bin/install.js"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "commands/",
+    "skills/",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-plugin",
+    "risk-adjustment",
+    "hhs-hcc",
+    "aca",
+    "cms",
+    "health-insurance"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/skills/hhs-hcc-risk-adjustment/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: hhs-hcc-risk-adjustment
+description: Domain expertise and computational support for the HHS-HCC commercial risk adjustment model (V07, plan years 2018+). Use when the user asks about how the HHS-HCC model works, what the year-over-year NBPP changes are, how to compute a risk score, what a specific coefficient is, or how to compare model specs across plan years. Covers the Adult, Child, and Infant sub-models, CC/HCC hierarchies, severity and transplant counters, RXC interactions, infant maturity-by-severity interactions, and CSR adjustments.
+---
+
+<essential_principles>
+## How the HHS-HCC Model Works (Always Apply)
+
+The HHS-HCC model is the risk adjustment model for the **commercial individual and small-group ACA markets**. It is published annually by CMS in the Notice of Benefit and Payment Parameters (NBPP) and is **not** the same model as the Medicare CMS-HCC. The model family in use depends on the benefit year — V07 covers BY2021 and onward, V05 covered BY2018-BY2020, and earlier V01-V04 versions covered BY2014-BY2017.
+
+**Always confirm the benefit year before answering substantive questions.** Coefficients, severity placements, group flags, and CSR factors all vary year over year. Never assume a "default" or "current" year; ask the user.
+
+### Principle 1: Three Sub-Models, Not One
+
+Every enrollee is scored under exactly one of three age-based sub-models. The boundary is `AGE_LAST` (age on the last day of the benefit year):
+
+- **Adult model** — `AGE_LAST >= 21`
+- **Child model** — `AGE_LAST in [2, 20]`
+- **Infant model** — `AGE_LAST in [0, 1]`
+
+The Adult and Child models are HCC-additive. The **Infant model is structurally different** — it does not score HCCs directly; instead it uses a maturity × severity *interaction grid* (see references/infant-model.md). Most cross-version bugs come from confusing infant and child rules.
+
+### Principle 2: HCC Hierarchies Run Before Group Collapsing
+
+Each enrollee's diagnoses map to CCs via `dx_mapping_table` (with effective-date and age/sex edits). CCs become HCCs after applying CC hierarchies (e.g., HCC008 zeros HCC009-013). Adult and Child models then collapse certain HCC pairs/triples into Group flags (G01, G02B, ..., G24). The Infant model does **not** apply group collapsing.
+
+### Principle 3: Severity / Transplant Counters Are Bucket-Schema Specific
+
+The Adult model has 10 severe buckets (1-9, 10PLUS) and 5 transplant buckets (4-7, 8PLUS). The Child model has 7 severe buckets (1-5, **6_7**, **8PLUS**) and a single transplant bucket (**4PLUS**). The Infant model has neither — severity in infants is part of the maturity interaction.
+
+### Principle 4: Year Matters for Both Logic and Data
+
+The published coefficients change every year. The **logic** also changes occasionally (e.g., BY2023 introduced the modern severity model; BY2024 added G24; BY2025 ungrouped HCC070/HCC071 from G07A and reassigned them to higher infant severity for sickle cell disease). Always confirm benefit year before answering or scoring.
+
+### Principle 5: CMS Python ≠ CMS DIY Tables ≠ CMS SAS
+
+CMS publishes the model in three forms — SAS source (canonical, available going back to BY2014), DIY tables (Excel reference workbook, intended for non-SAS implementers), and starting BY2025 a Python package. **The SAS source is the authoritative spec when sources disagree.** A known instance: the BY2025 Python release omits the `AGE0_MALE → AGE1_MALE` reassignment that is present in every SAS release and both the BY2024 and BY2025 DIY tables.
+
+### Principle 6: Diagnoses Only Count from Qualifying Claims
+
+A diagnosis on a claim contributes to risk score **only if** the claim is of a type CMS deems evidence of a clinician-documented condition. Inpatient (UB-04 bill types 111-114, 117) qualifies automatically. Outpatient UB-04 and Professional (CMS-1500) claims qualify only if they carry a CPT/HCPCS code on the CMS qualifying-services list — face-to-face physician encounters, surgical procedures, qualifying telehealth, etc.
+
+**Lab work, DME deliveries, technical-component-only imaging, ambulance transport, and J-code-only claims do not qualify.** A diabetes diagnosis on a lab claim adds nothing to the score, even though the same diagnosis on an office visit would add HCC021. See `references/claim-qualification.md`.
+
+This is the most common source of "I have the diagnosis on a claim, why isn't it scoring?" surprises. RXC variables (Adult only) use a different mechanism — pharmacy NDC matching, no qualifying-claim filter on the pharmacy side.
+
+### Principle 7: Risk Score Is Just One Input to the Transfer
+
+The HHS-HCC model produces a per-enrollee risk score, which aggregates to a Plan Liability Risk Score (PLRS). PLRS is **one component** of the CMS risk transfer formula:
+
+```
+T(i) = [PLRS_i · IDF_i · GCF_i / Σ(s · PLRS · IDF · GCF)
+        − AV_i · ARF_i · IDF_i · GCF_i / Σ(s · AV · ARF · IDF · GCF)] · P̄_s
+```
+
+The transfer also depends on Induced Demand Factor, Geographic Calibration Factor, Actuarial Value, Allowable Rating Factor, and statewide weighted averages. A high risk score does not guarantee a positive transfer, and metal-level decisions for high-risk populations have non-obvious effects. See `references/risk-transfer-formula.md`.
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do with the HHS-HCC model?
+
+1. **Explain** — Describe how part of the model works (general principles, a specific sub-model, how a calculation is performed, what changed in a given year)
+2. **Calculate score** — Compute a risk score for an enrollee given demographics + flagged HCCs/RXCs
+3. **Lookup** — Find a specific coefficient or rule (e.g., "what's the BY2025 Silver coefficient for HHS_HCC042?")
+4. **Compare years** — Identify what changed between two plan years
+5. **Risk transfer** — Compute or analyze the CMS risk transfer (PLRS, IDF, GCF, AV, ARF) for a plan, or evaluate metal-level optimization
+
+If the user already stated their intent in their request, skip the question and route directly.
+
+**Wait for response unless intent is already clear.**
+</intake>
+
+<routing>
+| User intent | Workflow |
+|---|---|
+| 1, "explain", "how does", "what is", "tell me about" | `workflows/explain-model.md` |
+| 2, "calculate score", "score an enrollee", "compute risk score" | `workflows/calculate-score.md` |
+| 3, "lookup", "find the coefficient", "what's the value of" | `workflows/lookup-coefficient.md` |
+| 4, "compare", "what changed", "diff", "year over year" | `workflows/compare-years.md` |
+| 5, "transfer", "PLRS", "metal optimization", "IDF", "GCF", "ARF", "AV" | `workflows/risk-transfer.md` |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Architecture and rules:**
+- `model-overview.md` — V07 architecture, sub-models, scoring formula, key terminology
+- `adult-model.md` — Adult variables, group flags, severity/transplant buckets, HCC_ED, RXC interactions
+- `child-model.md` — Child variables, group flags, severity/transplant buckets (note 6_7 and 8PLUS collapsing)
+- `infant-model.md` — Maturity hierarchy, severity hierarchy, AGE0/AGE1 swap, maturity × severity grid
+
+**Cross-cutting topics:**
+- `claim-qualification.md` — Which medical claims qualify for HCC scoring (inpatient bill types vs outpatient/professional with qualifying CPT/HCPCS), why labs/DME/J-code-only claims don't count, supplemental diagnoses
+- `cc-hcc-hierarchies.md` — DX→CC mapping, CC→HCC hierarchies, group collapsing, age/sex/MCE edits
+- `rxc-interactions.md` — RXC variables, RXC_06→RXC_07 hierarchy, HCC×RXC interactions including the RXC_09 triple
+- `csr-adjustments.md` — CSR adjustment factors by HIOS variant ID, BY2025 schedule change
+- `risk-transfer-formula.md` — The full CMS risk transfer formula (PLRS, IDF, GCF, AV, ARF, statewide averages) and metal-level optimization
+- `year-changes.md` — Year-over-year NBPP changes (BY2018-BY2027 as available)
+- `coefficient-data.md` — Where canonical coefficients live, how to load them
+
+**Local code-mapping CSVs (use Grep to look up specific codes):**
+- `dx-mapping.csv` — Full ICD-10 → CC crosswalk (11,568 rows). Columns: `DGNS_CD,CC_CD,ACC_CD,DGNS_CD_EFF_STRT_DT,DGNS_CD_EFF_END_DT,MIN_AGE_DGNS_INCLUDE,MAX_AGE_DGNS_EXCLUDE,CC_AGE_SPLIT_MIN_AGE_INC,CC_AGE_SPLIT_MAX_AGE_EXC,CC_SEX_SPLIT`. Use to answer "what CC does diagnosis X map to?" or "which diagnoses map to HCC Y?" (grep for the CC number in CC_CD column). Includes date-gating and age/sex edit columns.
+- `hcpcs-rxc.csv` — HCPCS J-code → RXC mapping (86 rows). Columns: `HCPCS_CODE,RXC`. Use to answer "does this J-code trigger an RXC?" or "which J-codes map to RXC_04?"
+- `ndc-rxc.csv` — NDC → RXC pharmacy mapping (15,134 rows). Columns: `NDC_CODE,RXC,start_year,end_year`. Use to answer "does this NDC trigger an RXC?" or "which NDCs map to RXC_05 in BY2025?" (filter by start_year/end_year).
+- `service-code-reference.csv` — CPT/HCPCS qualifying-service-code list (21,109 rows). Columns: `SRVC_CD,SRVC_TYPE_CD,SRVC_CD_EFCTV_STRT_DT,SRVC_CD_EFCTV_END_DT,CPT_HCPCSELGBL_RISKADJSTMT_IND`. Use to answer "does CPT code X qualify a claim for risk adjustment?" — look for `CPT_HCPCSELGBL_RISKADJSTMT_IND=Y` with the service date in the effective range. SRVC_TYPE_CD distinguishes CPT (01) from HCPCS (02).
+
+**Bundled reference data in `data/` (loaded automatically by scripts or grepped directly):**
+- `data/hcc_labels.csv` — Human-readable label and clinical category for every HCC, group flag, RXC, and interaction variable (210 rows). Columns: `column_name,hcc_number,label,clinical_category`. Use to answer "what does HCC042 mean?" or "which HCCs are in the Oncology category?" — grep by column_name or clinical_category.
+- `data/csr_adjustment_factors.csv` — CSR adjustment factors by CSR_Code and model year (BY2020–BY2027, 96 rows). Columns: `CSR_Code,CSR_Desc,model_year,adj_factor`. Loaded automatically by `score_enrollee.py`; also useful for "what is the CSR factor for Silver 94% in BY2025?"
+- `data/statewide_ra_factors.csv` — Statewide weighted-average PLRS, IDF, AV, ARF, average premium, and member months by state, market, and year (BY2018–BY2024, ~1,009 rows). Columns: `State,RA_Adj_Avg_Pre,Avg_pre,PLRS,ARF,AV,IDF,MM,Market,Year`. Use to look up the statewide inputs needed for the risk transfer formula — grep by State and Year, then filter by Market (1=Individual, 2=Small Group).
+- `data/BY<YYYY>/` — Coefficient CSVs (adult/child/infant model factors) for BY2018–BY2027. Loaded automatically by scripts via `--year`.
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|---|---|
+| `explain-model.md` | Walk the user through a topic in the model, citing references |
+| `calculate-score.md` | Compute a risk score for an enrollee using `scripts/score_enrollee.py` |
+| `lookup-coefficient.md` | Find a coefficient by variable name + metal + year using `scripts/lookup.py` |
+| `compare-years.md` | Diff model spec across plan years using `references/year-changes.md` |
+| `risk-transfer.md` | Compute a CMS risk transfer or analyze metal-level optimization using `scripts/risk_transfer.py` |
+</workflows_index>
+
+<scripts_index>
+Reusable code in `scripts/`:
+
+- `score_enrollee.py` — End-to-end risk score for one enrollee given demographics + flagged HCCs/RXCs. Reads CMS factor CSVs.
+- `load_coefficients.py` — Load CMS adult/child/infant factor CSVs into a dict for lookup or arithmetic.
+- `lookup.py` — Quick coefficient lookup by `(model, variable, metal, year)`.
+- `risk_transfer.py` — Compute the CMS risk transfer T(i) given PLRS, IDF, GCF, AV, ARF, statewide averages, and average premium. Includes a metal-level inflection-point helper.
+
+Coefficient CSVs for BY2018–BY2027 are bundled in `data/BY<YYYY>/`. Scripts use them automatically via `--year`; pass `--data-dir` to override with a custom path. Always confirm benefit year with the user before scoring — never assume.
+</scripts_index>
+
+<key_data_locations>
+CMS publishes all model artifacts annually on the CMS website under the Risk Adjustment section. Key file types to obtain for a given benefit year:
+- **Coefficient CSVs** — `adult_model_factors.csv`, `child_model_factors.csv`, `infant_model_factors.csv` (from the CMS HHS-HCC software package, inside `data/input/internal/`)
+- **SAS source** — canonical logic; available going back to BY2014
+- **DIY tables** — Excel reference workbook for non-SAS implementers; published for BY2024 and BY2025
+- **DX mapping, HCPCS/NDC crosswalks** — also in the CMS software package; mirrored locally in `references/` CSVs for this skill
+</key_data_locations>