From 8c12e3c81a6fafe5c67d2652b5f992d8487f9fa7 Mon Sep 17 00:00:00 2001
From: Tyler <tyler@crispygoat.com>
Date: Fri, 19 Jun 2026 19:49:26 -0600
Subject: [PATCH] docs: add x12 naming reference note

---
 docs/reference/x12naming.md | 68 +++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/reference/x12naming.md

diff --git a/docs/reference/x12naming.md b/docs/reference/x12naming.md
new file mode 100644
index 0000000..9dfe253
--- /dev/null
+++ b/docs/reference/x12naming.md
@@ -0,0 +1,68 @@
+# X12 naming conventions
+
+A short glossary of the names and indices used throughout Cyclone's parsers.
+
+## Segments
+
+Two- or three-letter codes that identify a row type. The codes are mnemonic:
+`CLM` = claim, `NM1` = name, `BPR` = beginning segment for payment
+order/remittance advice, `SVC` = service, `DTM`/`DTP` = date/time/period.
+
+## Elements
+
+Inside a segment, elements are separated by `*` and are 1-indexed. So
+`CLM01` is the first element of the `CLM` segment — the patient control
+number on 837P. `CLM02` is the second element — the total claim charge.
+
+## Composite elements
+
+A single element can carry sub-fields, separated by `:`. The sub-fields are
+also 1-indexed, suffixed to the element index:
+
+- `CLM05-1` = place of service (Facility Type Code)
+- `CLM05-2` = facility code qualifier
+- `CLM05-3` = claim frequency code
+
+In the Python code, this is `claim.place_of_service`,
+`claim.facility_code_qualifier`, and `claim.frequency_code` on the
+`ClaimHeader` model in `cyclone/parsers/models.py`.
+
+## Loops
+
+Four-digit numeric IDs, hierarchical:
+
+- 2000A (Billing Provider hierarchy) contains
+  - 2000B (Subscriber hierarchy) which contains
+    - 2300 (Claim) which contains
+      - 2400 (Service line)
+
+In `cyclone.parsers`, the `parse_837` walker descends through these loops
+explicitly.
+
+## Common qualifiers Cyclone cares about
+
+| Qualifier | Meaning | Where |
+|---|---|---|
+| `ABK` | ICD-10 principal diagnosis | `HI01-1` |
+| `ABF` | ICD-10 diagnosis | `HI01-1` |
+| `B` | Facility code qualifier (CMS POS) | `CLM05-2` |
+| `MC` | Medicaid (claim filing indicator) | 835 `CLP06` |
+| `PR` | Payer | 835 `N1*PR` |
+| `PE` | Payee | 835 `N1*PE` |
+| `G1` | Prior authorization | 837P `REF01` |
+| `TJ` | Federal taxpayer ID | 837P `REF01` (rendering provider TIN) |
+| `1` | Original claim | 837P `CLM05-3` |
+| `7` | Replacement claim | 837P `CLM05-3` |
+| `8` | Void/cancel claim | 837P `CLM05-3` |
+
+## The four delimiters
+
+All four are declared in the `ISA` segment (positions 103–106 in the ISA
+fixed-width header) and reused throughout the file. Cyclone's tokenizer
+in `cyclone/parsers/segments.py` reads the ISA first, then splits the
+rest of the file by those characters.
+
+- `*` — element separator
+- `:` — component (sub-element) separator
+- `~` — segment terminator
+- `^` — repetition separator