Adding Billing Codes

Most codesets are managed in the cld-utils DAG, not the sub-DAG.

Steps

1

Identify the right codeset SQL

Match the provider type and bill type to the correct cld-utils SQL file. See the codeset files table below.

2

Edit manual additions array

Append new billing codes to the ARRAY[...] in the manual additions section of the codeset SQL file.

3

Re-run cld-utils DAG

Builds a new date-stamped table, e.g., outpatient_codeset_2026_04_11. The prior table is not overwritten.

→ tq_intermediate.cld_utils.*_codeset_YYYY_MM_DD

4

Update params.py pointer

Change the table name constant in params.py to point to the newly built date-stamped table.

5

Run Clear Rates sub-DAG

New codes appear in the code spine → rate object space → downstream pricing phases.

→ prod_combined_abridged

Codeset Files

Provider Type	Bill Type	cld-utils SQL File	Managed By
Hospital	Outpatient	sql/spines/outpatient_codeset.sql	cld-utils DAG
ASC	Outpatient	sql/spines/asc_codeset.sql	cld-utils DAG
Laboratory	Professional	sql/spines/hospital_lab_codes.sql	cld-utils DAG
Physician Group	Professional	build/physician_group_codeset/pg_codeset.py	cld-utils Python builder
Dialysis	Professional	sql/spines/dialysis_center_codeset.sql	cld-utils DAG
DME	Professional	sql/spines/dme_codeset.sql	cld-utils DAG
Urgent Care	Professional	sql/spines/urgent_care_codeset.sql	cld-utils DAG

note

MS-DRG, APR-DRG, SSP line codes, J1 HCPCS, and Life Sciences drugs are baked directly into code.sql — they don't go through cld-utils and don't follow this process.

params.py Date-Suffix Pattern

Each codeset table is date-stamped. After rebuilding, update the corresponding constant in params.py to point to the new table.

params.py — codeset table pointers

OUTPATIENT_CODESET  = "tq_intermediate.cld_utils.outpatient_codeset_2026_03_24"
ASC_CODESET         = "tq_intermediate.cld_utils.asc_codeset_2026_03_23"
LAB_CODESET         = "tq_intermediate.cld_utils.hospital_lab_codes_2026_03_24"
DIALYSIS_CODESET    = "tq_intermediate.cld_utils.dialysis_center_codeset_2026_03_20"
DME_CODESET         = "tq_intermediate.cld_utils.dme_codeset_2026_03_20"
URGENT_CARE_CODESET = "tq_intermediate.cld_utils.urgent_care_codeset_2026_03_20"

warning

Stale pointer = stale codes. If you rebuild the codeset but forget to update params.py, the sub-DAG continues reading the old table. The new codes will not appear in the output until the pointer is updated.

Manual Additions Pattern

New codes are appended to the manual_additions array in the codeset SQL file. The array is unioned with the auto-generated codeset.

outpatient_codeset.sql — manual additions pattern

manual_additions AS (
  SELECT billing_code, billing_code_type, description
  FROM UNNEST(ARRAY[
      -- existing codes
      ROW('12345', 'HCPCS', 'Existing code description'),
      -- append new codes here
      ROW('G2023', 'HCPCS', 'New code description'),
      ROW('G2024', 'HCPCS', 'Another new code description')
  ]) AS t(billing_code, billing_code_type, description)
)

note

/add-codes skill: For routine code additions, the /add-codes skill automates this process. It reads a spec xlsx, routes each row to the correct SQL file based on bill_type and provider_type, and inserts new codes into the manual additions array.

Adding a New Provider Type

Adding a provider type is substantially more involved than adding codes to an existing type. It requires editing code.sql, rate_object_space.sql, and plausibility tables, plus accuracy scoring rules.

note

The /add-provider-type skill walks through all required changes for adding a new provider type to the Clear Rates pipeline.