Coding Hcc Risk Adjustment
Maps chronic conditions extracted by OpenMed to CMS-HCC V28 risk-adjustment categories...
Install
npx skills add maziyarpanahi/openmed --skill coding-hcc-risk-adjustment -g -a claude-code -y- Repository
- maziyarpanahi/openmed5.8k
- Category
- Writing
- Updated
- 4d ago
- License
- Apache-2.0
- Context cost
- Mediumabout 1,980 tokens
- Runs scripts
- No, instructions only
What it does
Maps chronic conditions extracted by OpenMed to CMS-HCC V28 risk-adjustment categories and estimates a RAF (Risk Adjustment Factor) score as decision support. Use when the user wants to surface risk-adjustable diagnoses from notes, map ICD-10-CM codes to HCC categories, estimate or reconcile a patient/panel RAF, find suspected-but-undocumented HCCs, or check MEAT documentation support. Trigger keywords: HCC, CMS-HCC, V28, RAF score, risk adjustment, Medicare Advantage, hierarchical condition category, MEAT, recapture, suspect HCC, RADV. Pairs after OpenMed NER + ICD-10 coding: consume Disease/Pathology entities from openmed.analyze_text, code them (see coding-icd10), then roll up to HCCs. CMS-HCC mappings and weights are public from CMS. This is a coding-support aid for human review, never autonomous risk-adjustment coding.
Mapping conditions to CMS-HCC V28 and estimating RAF
Surface and risk-adjust the chronic conditions OpenMed extracts by mapping them to CMS-HCC categories (the V28 model, phasing in for payment years 2024, 2026) and estimating a RAF (Risk Adjustment Factor) score. CMS pays Medicare Advantage plans based on RAF, so accurate, documented capture of chronic disease matters, and much of that signal lives in the narrative note, exactly what OpenMed reads.
This is decision support for coders/clinicians, not autonomous coding. The output is "candidate HCCs + estimated RAF + the documentation that supports (or fails to support) each one," for human validation.
CMS-HCC crosswalks (ICD-10-CM → HCC) and the category coefficients are public, CMS publishes them annually. Nothing restricted is bundled.
When to use
- You want to find risk-adjustable diagnoses mentioned in a note that may not be on the coded problem list ("suspect HCCs" / recapture).
- You need to map ICD-10-CM codes to V28 HCCs and apply the hierarchy.
- You want an estimated RAF for a patient or panel for review.
- You need to check whether a diagnosis has MEAT support (Monitored, Evaluated, Assessed, Treated) in the documentation.
Pairs with coding-icd10 (you need ICD-10-CM codes first) and may consume
mapping-to-snomed output upstream.
Quick start (public CMS crosswalk + coefficients)
CMS publishes the V28 ICD-10-CM→HCC mapping and the model coefficients. Load them locally (public files) and apply the model:
import csv
# 1) ICD-10-CM -> HCC (V28) crosswalk from the CMS Risk Adjustment files.
icd_to_hcc = {} # "E1122" -> "HCC38" (Diabetes w/ complication)
with open("cms_hcc_v28_icd_map.csv") as fh:
for row in csv.DictReader(fh):
icd_to_hcc[row["icd10cm"].replace(".", "")] = row["hcc_v28"]
