name: hl7-healthcare
description: >
Generate, validate, parse, and transmit HL7 v2 messages for healthcare interoperability workflows.
Use this skill whenever the user needs to work with HL7 messages of any type — including ADT^A04
(patient/donor registration), ORM^O01 (lab orders), ORU^R01 (results), and ACK (acknowledgments).
Also trigger for MLLP transport, SoftBank/Epic/Beaker integration, anonymous donor workflows,
ISBT-128 product registration, or any task involving healthcare system messaging, HL7 segment
construction, field mapping, or clinical interoperability. Even if the user just says "build an
HL7 message" or "send a result to Epic", use this skill.

HL7 Healthcare Interoperability Skill

Generates, validates, parses, and transmits HL7 v2.x messages. Designed for clinical lab,
stem cell, and hospital integration workflows — including anonymous donor handling (FACT/JACIE, FDA 21 CFR Part 1271).

Supported Message Types

Quick Start

1. Generate a message

# ADT^A04 — anonymous donor registration
python scripts/generate_adt_a04.py \
  --din "W000055508D001" \
  --donor-id "DONOR-2026-0042" \
  --sending-app "VERITAS" \
  --sending-facility "LSU_SCL" \
  --receiving-app "SOFTBANK" \
  --receiving-facility "LSU"

# ORM^O01 — lab order panel
python scripts/generate_orm_o01.py \
  --donor-id "DONOR-2026-0042" \
  --din "W000055508D001" \
  --product-type "PBSC" \
  --output orders.hl7

# ORU^R01 — results routing to Epic
python scripts/generate_oru_r01.py \
  --donor-id "DONOR-2026-0042" \
  --recipient-mrn "MRN123456" \
  --din "W000055508D001" \
  --results results.json \
  --output oru_result.hl7

2. Validate a message

python scripts/validate_hl7.py --file message.hl7
python scripts/validate_hl7.py --stdin < message.hl7

3. Parse / inspect a message

python scripts/parse_hl7.py --file message.hl7 --segment PID
python scripts/parse_hl7.py --file message.hl7 --all

4. Send via MLLP

python scripts/mllp_sender.py \
  --host softbank.lsu.edu \
  --port 2575 \
  --file message.hl7 \
  --timeout 10

5. Receive incoming messages (MLLP listener)

# Listen continuously — responds to each incoming message with ACK
python scripts/mllp_listener.py \
  --host 0.0.0.0 \
  --port 2575 \
  --timeout 30 \
  --json

# Accept exactly one message then exit (useful in scripts/pipelines)
python scripts/mllp_listener.py --port 2575 --once

6. Register a donor (feature-flag adapter)

# Phase 1 (current) — routes to SoftBank via ADT^A04
DONOR_BACKEND=softbank python scripts/donor_registration.py \
  --din W000055508D001 \
  --donor-id DONOR-2026-0042 \
  --json

# --backend argument takes precedence over env var
python scripts/donor_registration.py \
  --backend softbank \
  --din W000055508D001 \
  --donor-id DONOR-2026-0042

Anonymous Donor Rules (LSU / FDA 21 CFR Part 1271)

When registering an anonymous HSC donor, strictly follow these field rules:

The recipient's MRN must never appear in any ADT or ORM segment. It lives only in the
encrypted linking table, hashed as SHA-256 in audit events.

Product Order Panels (LOINC Codes)

LOINC codes differ by HSC product type. Using the wrong panel is a patient safety issue.

See references/product_panels.md for the complete tables:

Tests marked NMDP — do not reorder arrive pre-populated from registry documentation.
Do not issue duplicate lab orders; import via ORU^R01.

HL7 Segment Reference

For full field-by-field documentation of each message type:
- ADT^A04 → references/adt_a04.md
- ORM^O01 and ORU^R01 → references/orm_oru_reference.md
- ORU^R01 (Epic/WellSky details) → references/oru_r01.md

Listening & ACK Processing

mllp_listener.py opens a TCP server and processes inbound MLLP messages
(e.g. ORU^R01 pushed by SoftBank — INT-05). For each received message it:

1. Unwraps the MLLP frame (<VT> ... <FS><CR>)
2. Parses the MSH segment (message type, control ID, sender)
3. Responds with an MLLP-framed ACK immediately
4. Logs the result as structured JSON (when --json is set) or plain text

ACK code behaviour:

Network errors (timeout, bind failure) exit with code 2.

Phase 2 — SoftDonor Migration

In Phase 1 (current), donors are registered as phantom patients in SoftBank
via ADT^A04. donor_registration.py wraps this with a feature flag so the
backend can be swapped without breaking in-flight cases.

Feature flag: DONOR_BACKEND environment variable (or --backend argument)

When softdonor is requested, the error message is:

SoftDonor API spec pending discovery call with SCC Soft Computer.
Set DONOR_BACKEND=softbank until Phase 2.

Do not implement SoftDonor logic until the API spec is received from
SCC Soft Computer and the Phase 2 timeline is confirmed.

MLLP Framing

HL7 v2 over TCP uses MLLP (Minimal Lower Layer Protocol) framing:

<VT> [HL7 message bytes] <FS><CR>

• <VT> = 0x0B — Start Block character
• <FS> = 0x1C — End Data character
• <CR> = 0x0D — Carriage Return

The mllp_sender.py script handles framing automatically. For raw integration, see references/mllp_protocol.md.

Validation Rules

validate_hl7.py checks:
1. MSH segment present and correctly delimited (|^~\&)
2. Message type in supported set
3. Required segments present for message type
4. PID-3 (Patient ID) non-empty
5. Timestamp format valid (YYYYMMDDHHMMSS)
6. For ADT^A04 anonymous donor: PID-5 must be ANONYMOUS^DONOR, PID-7 must be 00010101
7. No MRN-like identifiers in ORM/ADT segments (anonymous donor safety check)
8. ACK code parsing (AA=accepted, AE=error, AR=rejected)

Error Handling

All scripts exit with:
- 0 — success
- 1 — validation error (message printed to stderr)
- 2 — network/MLLP error
- 3 — parse error

Scripts log to stdout in structured JSON when --json flag is passed, useful for agent integration.

File Layout

hl7-healthcare/
├── SKILL.md                    ← You are here
├── scripts/
│   ├── generate_adt_a04.py     ← Build ADT^A04 messages
│   ├── generate_orm_o01.py     ← Build ORM^O01 lab order panels
│   ├── generate_oru_r01.py     ← Build ORU^R01 result messages (with DIN OBX/NTE)
│   ├── validate_hl7.py         ← Validate any HL7 v2 message
│   ├── parse_hl7.py            ← Parse and inspect HL7 messages
│   ├── mllp_sender.py          ← Transmit via MLLP over TCP (outbound)
│   ├── mllp_listener.py        ← Receive MLLP messages over TCP (inbound, ACK server)
│   └── donor_registration.py   ← Feature-flag adapter: SoftBank (Phase 1) / SoftDonor (Phase 2)
├── references/
│   ├── adt_a04.md              ← ADT^A04 field reference
│   ├── orm_oru_reference.md    ← ORM^O01 and ORU^R01 field reference
│   ├── oru_r01.md              ← ORU^R01 field reference (incl. Epic/WellSky custom fields)
│   ├── product_panels.md       ← HSC product-type order sets (PBSC / BM / CB)
│   └── mllp_protocol.md        ← MLLP framing specification and retry guidance
├── tests/
│   └── test_all.py             ← Skill tests
└── examples/
    ├── anonymous_donor_registration.hl7
    ├── lab_order_panel_pbsc.hl7
    └── results_routing_to_epic.hl7