# Reflect 3 Attempt 02

> EHR Quality-Governance Skill

- Skill: `prism-shadow/reflect-3-attempt-02-57` (Agent Skill)
- Install (CLI): `npx skillmds@latest add prism-shadow/reflect-3-attempt-02-57`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prism-shadow/reflect-3-attempt-02-57/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: prism-shadow (https://skillmd.com/u/prism-shadow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prism-shadow/reflect-3-attempt-02-57

---

# EHR Quality-Governance Skill

## Purpose
Prepare normalized JSON packets for EHR quality-governance tasks: duplicate-chart merge readiness, referral coordination, care-transition handoffs, duplicate-review with ServiceRequest validation, and referral-batch audits.

## Core Principles

### 1. API-First Data Gathering
Query the EHR environment exhaustively before constructing any answer. Every answer field must be grounded in data returned by the API. Do not guess or interpolate values.

**Standard data-gathering sequence:**
- Read the task prompt to identify the primary entities (patient IDs, referral IDs, duplicate candidate IDs, batch IDs).
- Query the primary entity endpoints first (patient detail, referral detail, duplicate candidate detail).
- Then query all related clinical endpoints (conditions, medications, allergies, encounters, immunizations, documents, service-requests, disclosures).
- Query reference directories (providers, ICD-10 codes, service codes) for every code or provider ID referenced.
- For batch audits, query the full referral list and filter by batch_id; then look up every distinct diagnosis code in the ICD-10 directory.

### 2. Template-Driven Output
Every task includes an `answer_template.json` that is authoritative for field names, types, and enum values. Study it before building the answer.

**Template rules:**
- Required top-level keys must all be present. Missing a required key is a hard failure.
- Enum fields must use exactly one of the listed `allowed_values`. Do not invent new enum values.
- Arrays marked with `set_semantics: true` should be sorted alphabetically unless the template explicitly says otherwise.
- Arrays of objects should be sorted by the field specified in `ordering_rules` or the template annotations (e.g., "Sort by referral_id ascending").
- Date fields use `YYYY-MM-DD` format.
- Boolean fields use `true`/`false` (not strings).

### 3. Normalized Keys
Clinical records carry a `normalized_key` field. Use these keys for all set-union and array fields — never use raw description text or record IDs.

**Key sources:**
- Conditions: use `normalized_key` from each record with `status: "active"`.
- Medications: use `normalized_key` from each record with `status: "active"`.
- Allergies: use `normalized_key` from each record with `status: "active"`.

**Inactive records:** Records with `status: "inactive"` must be excluded from active-key sets and placed in `excluded_distractors` when the template calls for it. Always verify status before including a key.

### 4. Cross-Reference Data Sources
Many answers require reconciling information from multiple endpoints. Common reconciliation patterns:

**Duplicate merge readiness:**
- Compare the duplicate candidate's `merge_preview` keys against the union of active keys from both patients' individual endpoints. The `active_key_unions` should be the full union from patient endpoints. The `active_list_reconciliation` captures what the endpoints add beyond the merge preview.
- Match and conflict signals come from the duplicate candidate API response. Do not invent additional signals.
- Demographic match/conflict fields should reflect the actual match and conflict signals from the duplicate system, expressed as field-level descriptors.

**Referral coordination:**
- Compare the referral's `diagnosis_code` against the patient's active condition list. A code is `referral_relevant` when it relates to the referral's service line or appears in the referral narrative.
- Validate the primary diagnosis code against the ICD-10 directory: check chapter, expected terms, and narrative match. Supporting codes should include other active diagnoses relevant to the referral reason.
- Document evidence: check `documents_received` on the referral against the patient's document list to identify specific document IDs, types, dates, and statuses.

**Referral batch audit:**
- Look up every distinct diagnosis code in the ICD-10 directory. A code whose chapter is not the expected chapter for the service line is `out_of_range_chapter`.
- For laterality/narrative mismatches: compare the ICD-10 `expected_terms` against the referral's `diagnosis_narrative`. A mismatch exists when the narrative describes a different body part, condition, or laterality than the code's expected terms.
- Duplicate detection: group referrals by `patient_id` and check coordination notes for markers like "duplicate resubmission."

### 5. Evidence-Based Classifications
Every classification (risk flag, readiness status, blocking issue, highlight reason) must be supported by explicit data from the API.

**Risk flags:** Map only to the `allowed_values` in the template. Each flag needs evidence drawn from conditions (by normalized_key), medications (by normalized_key), and encounters (by encounter_id) that support it. Evidence arrays should be sorted alphabetically.

**Readiness statuses:** Choose the status that best describes the aggregate evidence. If any required element is missing or incomplete, the status should reflect that — but do not invent blockers. If a referral has approved authorization, received documents, and no clinical mismatches, it is ready unless a coordination note explicitly states a hold.

### 6. Distractor Exclusion
When the template includes `excluded_distractors`, identify records that are:
- Inactive (status is not "active").
- Unrelated to the primary task entities (e.g., audit logs about different patients, documents not related to the merge/referral/transition).
- Stale encounters outside the relevant time window or not relevant to the service line.

### 7. Validated-Ready Classification
For batch audits, a referral is `validated_ready_no_follow_up` only when ALL of these hold:
- Diagnosis code is in the expected chapter for the service line.
- No laterality or narrative mismatch.
- Authorization is approved (not missing or pending).
- All required documents are received (including office_note).
- Not part of a duplicate group.
- No imaging follow-up pending.
- Coordination note does not indicate a clinical concern or hold.

### 8. Action Plan Tiering
Assign each non-validated referral to exactly one tier:
- **Tier 1 (immediate):** urgent referrals with coding issues or duplicate-blocker status. Reason: `urgent_coding_or_duplicate_blocker`.
- **Tier 2 (short-term):** routine referrals with coding, authorization, or document issues. Reason: `routine_coding_auth_or_document_blocker`.
- **Tier 3 (administrative):** referrals that only need document completion or have no clinical issues. Reason: `administrative_document_completion`.

Every referral in the batch must appear in exactly one action-plan tier or be counted as validated-ready. The sum of all tier counts plus validated-ready must equal the total referral row count.

### 9. Provider Contact Selection
When the template requires provider contact information:
- Copy provider details exactly from the provider directory endpoint response — do not modify names, phone numbers, or fax numbers.
- Select the specialist based on the service line of the referral or the external document source referenced in match/audit signals.
- The primary care provider comes from the patient's `primary_care_provider` field.

### 10. Iterative Refinement
After constructing an answer, verify:
- Every required top-level key is present.
- Every enum field uses an allowed value.
- All arrays marked as sets are alphabetically sorted.
- All referenced IDs (patient, provider, document, audit, encounter) exist in the API responses.
- Count fields in `summary_counts` are consistent with the lengths of the corresponding arrays.
- The tier assignments cover every referral exactly once.
- No data was fabricated — every value traces back to an API response.