# Coding Hcc Risk Adjustment

Maps chronic conditions extracted by OpenMed to CMS-HCC V28 risk-adjustment categories...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill coding-hcc-risk-adjustment -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill coding-hcc-risk-adjustment -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill coding-hcc-risk-adjustment -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill coding-hcc-risk-adjustment -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```python
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"]

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/coding-hcc-risk-adjustment/SKILL.md