stack/docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md

Code families as first-class objects — element model, lineage anchors, longitudinal chat, legal epidemiology

Tracker: milestone P49 (this spec) and milestone P50 (outcome series). Builds on P48 (pfs/families.py, codes chunk metadata, valuation event), P47 (dockets/seals), P40/P41 (FR + eCFR jump links), P35 (closed-vocabulary RAG tagging).

Why

When the physician fee schedule decides coding and payment for a service, the unit of decision is a code or a code family: a bundle of logical elements that say what the service is and is not. CMS says this itself in the Medicare telehealth review process, where Step 3 is literally "Review the elements of the service as described by the HCPCS code" (CY2026 NPRM, 90 FR 32389, item 2KVJ2HKX ¶398). The corpus already holds every layer of the record for those elements — 84 PFS rules with paragraph anchors back to CY2002, RVU files 2015–2026, ten comment dockets 2017–2026, 177 IOM chapters, 699 eCFR sections — but nothing ties the layers together per code. The chat can price a code (P48) but cannot answer "where did this code come from, what replaced what, how did the elements change, who objected, and what does the manual say".

The goal of P49 is that the chat, and the notebooks, can build a longitudinal view of any code or code set payable under the PFS: creation, predecessors and successors, element changes, valuation history, sub-regulatory guidance, and public reaction, each step anchored to a citable paragraph. P50 then joins that timeline to outcome series (utilization, BLS wages, industry markets) so the fee schedule can be studied as law with effects — legal epidemiology.

What the corpus already shows (measured 2026-09-09)

The "elements" construct is explicit in the record.

• CPT 99490 was adopted for CY2015 in place of a CMS G-code; the FR prints its descriptor as a stem plus enumerated required elements — two or more chronic conditions expected to last ≥12 months; conditions placing the patient at significant risk; comprehensive care plan established/implemented/revised/monitored (CY2015 final rule DE2VH9PD ¶1244–1247, 79 FR 67716). The commenter-vs-CMS argument was about a single element (per calendar month vs per 30 days, ¶1248–1251).
• HCPCS G0556–G0558 (APCM, CY2025) print as a stem plus ~20 elements and ++ sub-elements: consent, initiation visit, 24/7 access, continuity, alternative care delivery, comprehensive care management, electronic care plan, transitions, community coordination, asynchronous communication, population data analysis, risk stratification, performance measurement (CY2025 final rule JJ6AM5HJ ¶1163–1185, 89 FR 97864–97865). G0557 is defined by reference to G0556's elements plus a population element (¶1186).
• The telehealth process (first printed in the CY2024 rules, 44F3F6VU/JJV3R692, and repeated every year since) is a three-step element test: Step 1 separately payable under the PFS; Step 2 subject to §1834(m), i.e. is the service "in whole or in part, inherently a face-to-face service"; Step 3 each element capable of being furnished via an interactive telecommunications system as defined in § 410.78(a)(3) (2KVJ2HKX ¶394, ¶396, ¶398).

Lineage is recoverable from the record but only by hand today.

• G-code → CPT 99490 (CY2015 final DE2VH9PD ¶1249–1251).
• G2058 (RVU file 2020 only) → CPT 99439 (2021–): "descriptor identical to G2058", temporary crosswalk value (CY2021 final YBM4IZUS ¶1578, 85 FR 84639; ¶686, ¶2369).
• G2064/G2065 (2020–2021) → CPT 99424/99426 (2022–), including the knock-on into the RHC/FQHC G0511 rate (CY2022 final JE7KYBW3 ¶1100/¶1111, 86 FR 65118; CY2023 final MZ24MX5S ¶1305).
• 99441–99443 deleted by the CPT panel, last in the RVU file 2024, replaced by 98008–98015 / 98016 (CY2025 rules XFGGRBDH/JJ6AM5HJ ¶489/¶765).
• Status changes visible in pfs.rvu: 99487/99489 B→A, 99497/99498 I→A, 99091 B→A, G2211 B→A.
• 99490 is discussed in 27 distinct rule documents from CY2015 final to CY2027 proposed; 284 rule chunks already carry codes ∋ 99490.

Public reaction is in the corpus, in two forms.

• Dockets CMS-2017-0092 … CMS-2026-2377 (10 dockets, 918,484 comment chunks). Abstract-level hits per docket: CCM 5/19/6/11/24/2/5/10/174/27; APCM 19 (CMS-2024-0256, the year it was proposed), 25, 5; G2211 3,353 in CMS-2023-0121 (the year it was activated), then 146 and 190. Telehealth: ~10–13k per docket 2020–2023.
• Before 2017 the only public-comment record is the FR itself: the Comment: / Response: paragraph pairs (e.g. DE2VH9PD ¶1244/¶1249, ¶1255) — a proxy series back to CY2002.

Sub-regulatory guidance is present but unlinked. 177 IOM chapters (MCPM ch. 12 SPJB4FX2 and MBPM ch. 15 YQFGB6JS = 988 corpus chunks), 699 eCFR sections (§ 410.78 telehealth SAJSGG28, § 410.26 incident-to Q78GP4Z9, § 414.22 T7PXFV4S), MLN909188 CCM/PCM/APCM booklet (PV8APQ4A). None carries a code: tag; comments and corpus chunks carry no codes metadata (0 of 1.15 M), only rules do (29,595 of 67,340).

Scale of "any code". pfs.rvu has 18,641 distinct HCPCS over 2015–2026; 8,572 are status A/R/T in CY2026 (7,087 in 2015). The hand registry in pfs/families.py covers 5 families / 17 codes.

Decisions

1. Elements are a closed, typed vocabulary, not free text. Element types are fixed in code; element values are a curated list that grows by review (P35 pattern: local model proposes from a closed list, humans accept). Types: actor (clinical staff directed by / personally by physician or QHP; RHC/FQHC), time (threshold minutes, "each additional"), period (calendar month, 30 days, per visit, 14/7 days post-discharge), population (≥2 chronic conditions ≥12 months; QMB; high risk), activity (consent; care plan; 24/7 access; transitions; medication reconciliation; …), modality (face-to-face; interactive telecommunications; audio-only; asynchronous), relation (add-on to; do-not-report-with; replaces; defined-by-reference-to; crosswalk-valued-to), setting (facility/non-facility; place of service), billing (one practitioner per month; initiating visit).
2. Lineage is a table of dated events with anchors, derived from two independent sources that must agree or be flagged: (a) pfs.rvu/rvu_proposed (first year, last year, status transitions, descriptor changes, RVU changes beyond a threshold) and (b) FR paragraphs whose text carries the code and an event verb (create/adopt/replace/delete/crosswalk/bundle/telehealth-list). Every event row stores item_key, p_id, page so the chat cites a paragraph, never a table. Lineage now has a third source, cpt — the AMA CPT Changes book's own "Effective January 1, YYYY" statement per code, ingested as pfs.cpt_reference/pfs.cpt_code change years, which are effective years rather than paragraph-anchored FR events; a cpt_changed year anchors an RVU event (an appearance/status change with no FR paragraph nearby) the same way an FR event does.
3. Families are derived, not hand-listed. A family = codes sharing a stem and differing in time/actor/population elements, plus CMS's own "code family" language in the FR ("The Chronic Care Management code family will be resurveyed", YBM4IZUS ¶1578) and relation elements (add-on/replaces). The five hand families become the regression fixture.
4. Anchors live in two places, one per consumer. Items get code:<hcpcs> and family:<key> tags in bib/Zotero (browsable, syncable); chunks get codes, families, and elements metadata in pgvector (retrievable). comments and corpus are re-indexed once with --force to stamp them, as P48 did for rules.
5. Longitudinal retrieval is era-balanced, not recency-blended. A "history of X" question retrieves per era (rule year) with a cap per era, so CY2015 and CY2027 both appear; the P34 recency blend stays for ordinary questions.
6. Chat presents a timeline the way P48 presents a valuation: a lineage SSE event before the first token, rendered as a table (year, event, codes, anchor link), and a prompt block whose rows carry bracketed labels the model must cite.
7. Self-hosted inference only for element extraction and stance tagging (llm module rule; qwen2.5 on the GPU pool).
8. Outcome series (P50) are separate: they never write into bib; they join on the lineage table's effective dates.

Architecture

FR rules (fr_anchors) ─┐
RVU files (pfs.rvu)  ──┼─► element extractor ─► pfs.code_element (code, year, type, value, anchor)
HCPCS/CPT descriptors ─┘             │
                                      ▼
                       family deriver ─► pfs.code_family (key, code, role, since, until, anchor)
                                      │
   rvu first/last/status ─┐           ▼
   FR event paragraphs ───┴─► lineage builder ─► pfs.code_event (code, year, kind, from/to, item_key, p_id, page)
                                      │
                 ┌────────────────────┼─────────────────────┐
                 ▼                    ▼                     ▼
   bib tags code:/family:    pgvector metadata          notebooks
   (rules, comments, IOM,    codes/families/elements    (timeline, reaction series)
    eCFR, MLN)               on all 3 collections
                 └────────────────────┬─────────────────────┘
                                      ▼
   chat: detect codes → lineage(codes) + era-balanced retrieve → `lineage` SSE + prompt block → cited answer
                                      │
   P50: event calendar ─► BLS OEWS/CES, market series, Part B utilization ─► event-study notebook

Components (P49)

pfs/elements.py — element model

Pure dataclasses + the closed vocabulary (ElementType enum; VOCAB: dict[ElementType, tuple[str, ...]] seeded from the 99490, 99487/99489, 99491/99437, 99439, 99495/99496, 99497/99498, 99424–99427, G0556–G0558, 99441–99443/98008–98016, G2211 descriptors in the corpus). Descriptor parser for the deterministic parts: minutes, "each additional", period words, code references inside parentheticals ("Use in conjunction with 99490", "Do not report … 99487, 99489, 99491").

pfs/extract.py — extractor

Input: a descriptor text plus the FR paragraph run that prints it (stem paragraph followed by element paragraphs, as in DE2VH9PD ¶1244–1247 and JJ6AM5HJ ¶1163–1185). Deterministic parse first; then the local model maps each element paragraph to a vocabulary value or proposes a new value (queued for review, never auto-added). Output rows into DuckDB pfs.code_element with the anchor. Runs from stack pfs elements --code … | --family … | --all-payable.

pfs/lineage.py — events

Sources: (a) pfs.rvu/rvu_proposed diffs per code per year (appears, disappears, status change, descriptor change, |ΔRVU| > 10 %); (b) fr_anchors paragraphs where codes ∋ code and an event pattern matches (finaliz…creat, replace, delet, crosswalk, bundled, telehealth services list). Emits pfs.code_event. Cross-check rule: an RVU-file appearance without an FR paragraph within ±1 rule year, or vice versa, is flagged unanchored for review. The 5 worked lineages above are the fixture.

pfs/families.py — derive

Keep the API (FAMILIES, detect_codes, family_of) but source FAMILIES from pfs.code_family at import time when the replica is present, falling back to the hand list. Family key = stem slug; synonyms = descriptor stems + FR family phrases.

bib/tag.py + bib/sync.py — anchors on items

New namespaces code: and family:; tagger walks rules (via fr_anchors.text), comments (chunk text via pgvector or abstract), IOM chapters (attachment text), eCFR sections, MLN items. Nightly zotero-sync carries them (P38 tag-merge rules apply; sup: tags stay load-bearing).

llm/chunk.py + llm/index.py — anchors on chunks

codes metadata on all three collections; add families (space-joined keys) and elements (space-joined type=value slugs when a chunk mentions a vocabulary value). One-time stack llm index --collection all --force.

bib/reaction.py — reaction series

Per (family, docket): comment count, share of docket, stance (support/oppose/modify — closed vocab, local model, P35 pipeline), top organisations (org: tags exist). Pre-2017: Comment:/Response: pairs from fr_anchors where the pair mentions the family's codes. Output table pfs.code_reaction and a notebook.

llm/evidence.py + llm/rag.py + llm/web/chat.html — longitudinal chat

lineage_evidence(question) → events + element diffs for the detected codes; retrieve(..., mode="timeline") era-balanced; lineage SSE event; prompt block; system prompt: cite the event label for every dated claim. UI: timeline table with FR jump links (P40) and eCFR links (P41).

Evaluation

Golden questions with expected anchors: "history of CCM coding and payment", "what replaced G2058", "how did the APCM elements differ from CCM", "when were audio-only E/M codes payable and why did 99441–99443 end", "what did commenters say about G2211 in 2023 vs 2025", "does 99490 pass telehealth Step 3". Pass = every expected (item_key, p_id) appears in sources and the prose cites the event labels.

P50 — legal epidemiology (scoped, not designed)

• pfs.code_event supplies the exposure calendar: effective date = 1 January of the rule year (or mid-year for correction rules), exposure = code/family becomes payable, revalued, or ends.
• Outcome series to ingest, each with its own module and provenance in bib: Medicare Physician & Other Practitioners PUF (utilization and allowed amounts per HCPCS, 2013–), BLS OEWS (occupation wages: 29-1xxx physicians, 29-2xxx/31-9xxx clinical support), BLS CES (health-care employment), market series (sector ETFs; telehealth/RPM/care-management tickers).
• Event-study notebook: pre/post windows around each event with never-treated code sets as controls; output effect sizes with confidence bands, never causal language in the chat.

Out of scope (P49)

Locality pricing, OPPS, MA/commercial coding, CPT copyrighted long descriptors beyond what the FR prints, cloud LLM APIs.