# Ehr Quality Governance Packets

> Produce normalized JSON packets from a read-only EHR quality-governance HTTP API. Use when a task gives case-object IDs (patients, referrals, duplicate candidates, service requests, batch IDs) plus an input/payloads/answer_template.json schema and asks you to reconcile clinical evidence into one strict-schema JSON object. Covers duplicate-merge readiness packets, referral-coordination packets, care-transition handoff packets, duplicate+ServiceRequest quality review, and referral-batch audits. Reach the environment ONLY over the network via environment_access.md; the API is the sole source of truth for environment data.

- Skill: `prism-shadow/ehr-quality-governance-packets-3` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add prism-shadow/ehr-quality-governance-packets-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prism-shadow/ehr-quality-governance-packets-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: prism-shadow (https://skillmd.com/u/prism-shadow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prism-shadow/ehr-quality-governance-packets-3

---


# EHR Quality-Governance Packets

This skill solves a family of tasks that all share one shape: you are given a few
**case-object IDs** in a `prompt.txt`, a strict output **schema** in
`input/payloads/answer_template.json`, and a **read-only EHR HTTP API** described
in `environment_access.md`. You must fetch evidence over the network, reconcile it
against the clinical record, and emit **a single normalized JSON object** that
conforms exactly to the template.

The five packet types this skill covers:
1. **Duplicate-chart merge readiness packet** — pick canonical target/source, merge
   disposition, active clinical-key unions, identity match/conflict signals,
   document/audit evidence, specialist+PCP contact.
2. **Referral coordination packet** — reconcile a referral with the active chart:
   diagnosis/code set for the letter, allergy readiness, encounter + required-document
   evidence, receiving provider, authorization/readiness, medication highlights,
   referral-letter field choices.
3. **Care-transition handoff packet** — patient + recipient, active clinical keys,
   the N most relevant handoff encounters, latest immunization, applicable disclosure,
   risk flags + evidence, send readiness.
4. **Duplicate + ServiceRequest quality review** — validate the duplicate-review
   outcome and the ServiceRequest quality signals (code validity, reason-code
   validation, performer service line, SBAR coverage).
5. **Referral-batch audit** — invalid/out-of-range diagnosis codes, laterality/narrative
   mismatches, duplicate groups, insurance/patient anomalies, follow-up queues,
   Tier 1/2/3 action plan, summary counts.

## Inputs you are given

- `prompt.txt` — states the packet type and lists the **case-object IDs** to act on.
  It contains a `<TASK_ENV_BASE_URL>` placeholder. Extract every ID it names.
- `input/payloads/answer_template.json` — the **output contract**. It states required
  top-level keys, field types, `enum` allowed values, which arrays have `set_semantics`,
  and `ordering` rules. Treat it as law.
- (Some tasks add extra payloads, e.g. a request manifest listing `requested_outputs`.
  Read every file under `input/payloads/`.)
- `environment_access.md` — the **base URL** and the list of allowed `GET` endpoints.
  No authentication.

## Non-negotiable rules

- **The network API is the only source of truth for environment data.** Do not read
  local source files for environment data. Use `environment_access.md` solely to obtain
  the base URL needed to reach the API over the network.
- **`normalized_key` is provided by the API** on conditions, medications, and allergies.
  Read it directly; never invent or re-derive it.
- **Output is one JSON object only.** No prose, no markdown fences, no extra keys, no
  omitted required keys. Conform exactly to `answer_template.json`.
- **Honor every enum, set-semantics, and ordering rule in the template.** Arrays marked
  as sets → sorted ascending (alphabetically unless the template says otherwise). Dates
  → `YYYY-MM-DD`.
- **Active records only.** Filter clinical lists by `status == "active"`. Exclude stale,
  inactive, opposite-laterality, and unrelated-distractor records (see
  `references/normalization.md`).
- **The duplicate candidate's `merge_preview` is a hint, not authoritative.** Patient
  active-list endpoints are authoritative for clinical unions; the preview may omit
  active keys that the patient endpoints contain.
- **Do not copy specific values from any example.** Derive every value from the live API
  for the case objects in the current prompt.

## Workflow

1. **Parse the prompt.** Identify the packet type and extract every case-object ID.
2. **Internalize the template.** Read `answer_template.json` (and any extra payload).
   Note required top-level keys, field types, enums, set-semantics, and ordering. This
   is the contract you must satisfy.
3. **Resolve the base URL.** Read `environment_access.md`, substitute the value into
   `<TASK_ENV_BASE_URL>`.
4. **Fetch evidence.** Map each case object to its endpoints (see
   `references/api_endpoints.md`) and pull the records you need. List endpoints return
   the **full** set and ignore query parameters — filter client-side by `batch_id`,
   `patient_id`, `service_line`, etc.
5. **Reconcile.** Apply the reasoning for your packet type (see
   `references/reconciliation_playbook.md`). Use `scripts/ehr_client.py` for fetching
   and the shared normalization helpers.
6. **Normalize.** Apply the conventions in `references/normalization.md` (active filter,
   sorted sets, `YYYY-MM-DD` dates, distractor exclusion, enum compliance).
7. **Validate against the template.** Every required key present; every enum value legal;
   every set sorted; every date formatted; no extra keys.
8. **Emit one JSON object.** Nothing else.

## Case-object → endpoint map (compact)

| Case object | Endpoints |
|---|---|
| Patient `P-…` | `/api/patients/{id}` + `/conditions` `/medications` `/allergies` `/encounters` `/documents` `/immunizations` `/disclosures` `/service-requests` |
| Duplicate candidate `DUP-…` | `/api/duplicates/{id}` (has `merge_preview`, `match_signals`, `conflict_signals`) |
| Referral `REF-…` | `/api/referrals/{id}` ; batch via `/api/referrals` filtered by `batch_id` |
| Service request `SR-…` | `/api/patients/{patient_id}/service-requests` (carries `sbar`, `reason_codes`, `service_code`) |
| Provider `PRV-…` | `/api/providers/{id}` |
| ICD-10 code | `/api/icd10/{code}` (`chapter`, `expected_terms`, `requires_laterality`) |
| Service code | `/api/service-codes/{code}` (`active`, `service_line`) |
| Audit logs | `/api/audit-logs` filtered by `patient_id` |

ID formats you will see: patients `P-NNNNN`, providers `PRV-XXX-NNN`, referrals
`REF-…`, duplicate candidates `DUP-…`, service requests `SR-…`, batches
`MONYY-LINE-X`. Always use the exact IDs from the prompt.

## Normalization in one screen

- `normalized_key`: take it verbatim from the API record.
- Active filter: `status == "active"` (case-insensitive). Inactive → excluded distractor.
- Sets: unique, non-empty, sorted ascending (string order) unless the template overrides.
- Dates: pass through as `YYYY-MM-DD`.
- Distractors to exclude: inactive clinical records, opposite-laterality conditions for
  the joint in question, unrelated document types (e.g. `chart_summary`), unrelated audit
  logs, synthetic-looking encounter IDs outside the selection window.
- Derived (not stored) fields: `performer_service_line` (from provider lookup),
  `service_code_valid` (from service-code `active`), `reason_code_validation` (from
  ICD-10 lookup), `sbar_coverage` (from the `sbar` object).

## Output checklist (before emitting)

- [ ] One JSON object, no prose, no fences.
- [ ] All required top-level keys present; no extra keys.
- [ ] Every enum value is in the template's allowed list.
- [ ] Every set array sorted ascending; dates `YYYY-MM-DD`.
- [ ] Clinical unions use active records only; distractors excluded and (where the
      template asks) listed under `excluded_distractors`.
- [ ] Every cited evidence ID actually exists in the fetched records.
- [ ] No value copied from an example — all derived from the live API for this prompt.

## References

- `references/api_endpoints.md` — full endpoint catalog, response shapes, wrapper keys,
  the no-server-side-filter rule, and stored-vs-derived fields.
- `references/normalization.md` — normalization conventions and the
  duplicate-preview-vs-active-list reconciliation rule in detail.
- `references/reconciliation_playbook.md` — per-packet-type reasoning that turns
  evidence into the template's fields.
- `scripts/ehr_client.py` — generic, tested API client + normalization helpers
  (stdlib only). Run `python3 scripts/ehr_client.py` for a reachability smoke test.