EHR Quality Governance
Core Concepts
Task Environment URL
Prompts use TASK_ENV_BASE_URL as a placeholder. Replace it with the actual base URL from environment_access.md or the task-provided value before making any API call.
Normalized Keys
Every condition, medication, and allergy record returned by the patient endpoints carries a normalized_key field. This is a lowercase, underscore-delimited string (e.g. hypertension, right_knee_oa, insulin_glargine, latex). These keys are the primary identifiers for clinical list operations. Always sort arrays of normalized keys alphabetically.
Active vs. Inactive Records
Clinical list endpoints return records with a status field. For conditions, medications, and allergies, filter to "active" status for current clinical context. Inactive, "entered-in-error", and "resolved" records are distractors and go into excluded/distractor arrays when the template asks for them.
Sorting and Set Semantics
Arrays that the template marks as sorted or as sets must be sorted alphabetically (ascending) unless the template explicitly states otherwise (e.g. encounter arrays sorted by date newest-first). For arrays of objects, sort by the designated sort key (typically referral_id, code, or group_id). Set semantics mean an array is treated as unordered at comparison time, but you must still emit a deterministic order.
Controlled Enums
Many template fields use enum: with a fixed set of values. Choose exactly one value from the listed set. Do not invent new enum values.
Template Conformance
Every task specifies an answer_template.json payload. The output JSON must use the exact top-level keys, field names, and types defined in the template. If a field is optional and no data exists, use null for nullable fields or an empty array [] for array fields.
API Navigation
The EHR environment exposes these endpoint families. See references/api_endpoints.md for the full endpoint inventory with paths, parameters, and response field notes.
Primary Lookup Flow
For any task involving a patient, start with the patient detail endpoint, then pull clinical lists in parallel:
GET /api/patients/{patient_id} — demographics, MRN, name, DOB
GET /api/patients/{patient_id}/conditions — active/inactive conditions with ICD-10 codes and normalized_keys
GET /api/patients/{patient_id}/medications — drug records with normalized_keys
GET /api/patients/{patient_id}/allergies — allergen records with normalized_keys
For tasks involving encounters, documents, immunizations, or disclosures, also pull:
GET /api/patients/{patient_id}/encounters
GET /api/patients/{patient_id}/documents
GET /api/patients/{patient_id}/immunizations
GET /api/patients/{patient_id}/disclosures
GET /api/patients/{patient_id}/service-requests
Provider Lookup
Use GET /api/providers to list all providers and GET /api/providers/{provider_id} for a single provider. Each provider record includes name, role, service_line, facility, phone, fax.
ICD-10 Validation
Use GET /api/icd10/{code} to look up a diagnosis code. The response includes code, description, chapter, and laterality fields. Validate that:
- The code exists and resolves (not unknown)
- Its chapter is appropriate for the service line (e.g. Musculoskeletal for orthopedics, Circulatory for cardiology)
- Its description and laterality match the referral narrative
Duplicate and Referral Endpoints
GET /api/duplicates/candidates and GET /api/duplicates/{candidate_id} for duplicate-chart review
GET /api/referrals and GET /api/referrals/{referral_id} for referral detail
GET /api/audit-logs for audit trail records
GET /api/service-codes and GET /api/service-codes/{code} for service code validation
Request Strategies
- Fetch all patient endpoints simultaneously — they are independent.
- Fetch all referral/search endpoints in parallel when auditing a batch.
- When validating a batch of referrals, batch ICD-10 lookups in parallel.
- Use the full response payloads; do not truncate or filter prematurely.
Task-Type Workflows
1. Duplicate-Chart Merge Readiness
Steps:
- Fetch the duplicate candidate from
/api/duplicates/{candidate_id}. Note match_signals, conflict_signals, and the two patient_ids.
- Fetch patient demographics for both patients in parallel.
- Fetch conditions, medications, and allergies for both patients in parallel. Filter to
status: "active".
- Compute the union of active normalized_keys across both patients for conditions, medications, and allergies.
- Reconcile: compare the duplicate-candidate preview listed keys against the actual patient endpoint results. Any key present in a patient endpoint but absent from the duplicate preview goes into the
*_added_from_active_endpoints arrays.
- Identify identity signals: match which demographic fields agree vs. conflict, noting exact matches (same value) and surface-level mismatches (variant names, address abbreviations). Derive match_signals and conflict_signals from the evidence — prefer the duplicate candidate's own signal lists, then supplement with demographic field comparisons.
- Pull documents and audit logs. Include only documents relevant to identity or external continuity (e.g. shared external specialist documents, merge-specific documents). Exclude unrelated chart summaries.
- Select the canonical merge target: the record with active clinical data and identity primacy. The other record is the merge source.
- Determine disposition:
merge_ready (strong match, few/no conflicts), merge_ready_with_conflict_review, needs_manual_review, or do_not_merge.
- Pick the specialist provider contact from the provider directory — typically the provider on the shared external continuity document or the primary care provider on the target record.
2. Referral Coordination Packet
Steps:
- Fetch the referral from
/api/referrals/{referral_id}. Extract patient_id, service_line, diagnosis_code, narrative, authorization_status, urgency, referral_status.
- Fetch patient detail and active conditions, medications, and allergies in parallel.
- Look up the primary diagnosis code via
/api/icd10/{code}. Validate: code exists, chapter matches the service line, description matches the narrative.
- Build the active diagnosis list from the patient conditions and the referral intake narrative. Mark referral-relevant diagnoses (those tied to the service line or the referral reason).
- Assess allergy readiness: pull patient allergies, mark statuses, and check if a documented allergy statement exists in the referral form.
- Find the most recent relevant encounter. Look for office visits near the referral date where diagnosis codes and medications mentioned align with the referral reason. Prefer signed encounters.
- Check required documents: echocardiogram (for cardiology), office notes, authorization records, medication lists. Flag missing documents.
- Identify the receiving provider from the referral
performer_provider_id and the provider directory.
- Build medication highlights: pull active medications, tag those relevant to the referral (e.g. diuretics for heart failure, antihypertensives for blood pressure).
- Fill the
referral_letter_fields: choose the single best enum value for each letter section based on the evidence gathered.
3. Care Transition Packet
Steps:
- Fetch patient detail and the target recipient provider.
- Fetch active conditions, medications, allergies in parallel. Extract normalized_keys, sort alphabetically.
- Fetch all encounters. Select the four most recent handoff-relevant encounters by date, newest first. Exclude encounters that are stale, outside the surgical handoff window, or unrelated.
- Fetch immunizations. Select the single most recent immunization by date.
- Fetch disclosures. Check for one that matches the target provider ID and has
status: "permitted" for the handoff purpose.
- Derive risk flags from clinical evidence:
cognitive_memory_loss: condition key memory_loss present
fall_risk_note_required: lower-extremity OA conditions (hip, knee) plus relevant medications
hypertension: condition key hypertension present
insulin_dependent_diabetes: diabetes_type_2 + insulin medication
latex_allergy: allergy key latex present
perioperative_glucose_plan_needed: diabetes + insulin, especially when a recent care-transition encounter exists
- Build risk flag evidence objects: for each flag, populate condition_keys, medication_keys, and encounter_ids from the records that support the flag.
- Determine packet readiness:
ready if no blockers, ready_with_risk_flags if risk flags exist but no blockers, not_ready if critical data is missing or disclosure is not permitted.
4. Service-Request Quality Review
Steps:
- Fetch the duplicate candidate to assess merge vs. no-merge for the underlying patients.
- Fetch the ServiceRequest from
/api/patients/{patient_id}/service-requests and filter for the given SR-* ID.
- Validate service code via
/api/service-codes/{code}.
- Validate each reason code via
/api/icd10/{code}: check validity, chapter, and whether it matches the patient active condition evidence.
- Assess SBAR coverage: the ServiceRequest narrative body is expected to contain Situation, Background, Assessment, and Recommendation sections. Check which sections are present.
- Output the duplicate review decision:
merge, review_hold, or do_not_merge with match/conflict signals.
5. Batch Referral Audit
Steps:
- Fetch all referrals via
GET /api/referrals. Filter to the target batch by batch_id.
- Count total rows and unique patients for the batch summary.
- For each referral, look up its ICD-10 code in parallel. Flag as
out_of_range_chapter if the ICD-10 chapter differs from the expected service-line chapter (e.g. non-Musculoskeletal codes in an orthopedics batch). Flag as unknown_code if the code does not resolve.
- Detect laterality and narrative mismatches: compare the ICD-10 description (and laterality, if present) against the referral narrative. Flag
laterality_mismatch when the ICD-10 code implies a different side than the narrative describes, narrative_mismatch when the code description does not match the narrative topic, and missing_laterality when the code carries laterality data but the narrative omits it. Do not flag codes already in the out-of-range list — each referral appears in at most one of the two mismatch lists.
- Detect duplicates: referrals with the same patient_id and same diagnosis_code are candidate duplicates. Group under a
DUP-REF-* group ID with type same_patient_resubmission.
- Detect insurance anomalies: two different patients sharing the same insurance ID across referrals in the batch. Do not merge these; flag for insurance-membership verification with type
shared_insurance_different_patients.
- Build follow-up queues: sort referral IDs into
authorization_missing, authorization_pending, records_request (missing office notes), and imaging_follow_up (missing or pending imaging).
- Assign tiers:
- Tier 1: urgent coding or duplicate-blocker referrals (duplicate primary, laterality mismatches on urgent referrals)
- Tier 2: routine coding, authorization, or document blockers
- Tier 3: administrative document-completion items with no clinical urgency
- Assign owner providers from the provider directory — typically the orthopedic surgeon listed on the referral or the performer provider on the referral record.
- Compute summary counts for all categories: total rows, unique patients, urgency counts, mismatch counts, queue sizes, and tier counts.
Reference Files
- api_endpoints.md — Complete inventory of available REST endpoints with paths, parameters, and response field notes.
- normalization_conventions.md — Detailed rules for normalized_keys, sorting, set semantics, and distractor handling.
1---2name: ehr-quality-governance-133description: Navigate a FHIR-style EHR quality-governance REST API to produce normalized clinical packets. Use when a task involves preparing merge-readiness packets, referral coordination documents, care-transition summaries, service-request quality reviews, or batch referral audits against a healthcare API. Covers duplicate-chart review, active clinical-list reconciliation, ICD-10 validation, identity-signal analysis, encounter selection for handoffs, allergy-readiness checks, authorization tracking, provider-directory lookup, document/audit evidence gathering, and risk-flag derivation. Recognize triggers like EHR quality governance, duplicate merge packet, referral coordination, care transition packet, orthopedic referral audit, or any prompt referencing a TASK_ENV_BASE_URL healthcare API with patient/condition/medication/allergy/encounter/document/ICD-10/provider endpoints.4metadata:5 source: https://skillmd.com/skills/prism-shadow/ehr-quality-governance-136---78# EHR Quality Governance910## Core Concepts1112### Task Environment URL1314Prompts use `TASK_ENV_BASE_URL` as a placeholder. Replace it with the actual base URL from `environment_access.md` or the task-provided value before making any API call.1516### Normalized Keys1718Every condition, medication, and allergy record returned by the patient endpoints carries a `normalized_key` field. This is a lowercase, underscore-delimited string (e.g. `hypertension`, `right_knee_oa`, `insulin_glargine`, `latex`). These keys are the primary identifiers for clinical list operations. Always sort arrays of normalized keys alphabetically.1920### Active vs. Inactive Records2122Clinical list endpoints return records with a `status` field. For conditions, medications, and allergies, filter to `"active"` status for current clinical context. Inactive, `"entered-in-error"`, and `"resolved"` records are distractors and go into excluded/distractor arrays when the template asks for them.2324### Sorting and Set Semantics2526Arrays that the template marks as sorted or as sets must be sorted alphabetically (ascending) unless the template explicitly states otherwise (e.g. encounter arrays sorted by date newest-first). For arrays of objects, sort by the designated sort key (typically `referral_id`, `code`, or `group_id`). Set semantics mean an array is treated as unordered at comparison time, but you must still emit a deterministic order.2728### Controlled Enums2930Many template fields use `enum:` with a fixed set of values. Choose exactly one value from the listed set. Do not invent new enum values.3132### Template Conformance3334Every task specifies an `answer_template.json` payload. The output JSON must use the exact top-level keys, field names, and types defined in the template. If a field is optional and no data exists, use `null` for nullable fields or an empty array `[]` for array fields.3536---3738## API Navigation3940The EHR environment exposes these endpoint families. See [references/api_endpoints.md](references/api_endpoints.md) for the full endpoint inventory with paths, parameters, and response field notes.4142### Primary Lookup Flow4344For any task involving a patient, start with the patient detail endpoint, then pull clinical lists in parallel:45461. `GET /api/patients/{patient_id}` — demographics, MRN, name, DOB472. `GET /api/patients/{patient_id}/conditions` — active/inactive conditions with ICD-10 codes and normalized_keys483. `GET /api/patients/{patient_id}/medications` — drug records with normalized_keys494. `GET /api/patients/{patient_id}/allergies` — allergen records with normalized_keys5051For tasks involving encounters, documents, immunizations, or disclosures, also pull:5253- `GET /api/patients/{patient_id}/encounters`54- `GET /api/patients/{patient_id}/documents`55- `GET /api/patients/{patient_id}/immunizations`56- `GET /api/patients/{patient_id}/disclosures`57- `GET /api/patients/{patient_id}/service-requests`5859### Provider Lookup6061Use `GET /api/providers` to list all providers and `GET /api/providers/{provider_id}` for a single provider. Each provider record includes `name`, `role`, `service_line`, `facility`, `phone`, `fax`.6263### ICD-10 Validation6465Use `GET /api/icd10/{code}` to look up a diagnosis code. The response includes `code`, `description`, `chapter`, and `laterality` fields. Validate that:6667- The code exists and resolves (not unknown)68- Its chapter is appropriate for the service line (e.g. Musculoskeletal for orthopedics, Circulatory for cardiology)69- Its description and laterality match the referral narrative7071### Duplicate and Referral Endpoints7273- `GET /api/duplicates/candidates` and `GET /api/duplicates/{candidate_id}` for duplicate-chart review74- `GET /api/referrals` and `GET /api/referrals/{referral_id}` for referral detail75- `GET /api/audit-logs` for audit trail records76- `GET /api/service-codes` and `GET /api/service-codes/{code}` for service code validation7778### Request Strategies7980- Fetch all patient endpoints simultaneously — they are independent.81- Fetch all referral/search endpoints in parallel when auditing a batch.82- When validating a batch of referrals, batch ICD-10 lookups in parallel.83- Use the full response payloads; do not truncate or filter prematurely.8485---8687## Task-Type Workflows8889### 1. Duplicate-Chart Merge Readiness9091Steps:92931. Fetch the duplicate candidate from `/api/duplicates/{candidate_id}`. Note `match_signals`, `conflict_signals`, and the two `patient_ids`.942. Fetch patient demographics for both patients in parallel.953. Fetch conditions, medications, and allergies for both patients in parallel. Filter to `status: "active"`.964. Compute the union of active normalized_keys across both patients for conditions, medications, and allergies.975. Reconcile: compare the duplicate-candidate preview listed keys against the actual patient endpoint results. Any key present in a patient endpoint but absent from the duplicate preview goes into the `*_added_from_active_endpoints` arrays.986. Identify identity signals: match which demographic fields agree vs. conflict, noting exact matches (same value) and surface-level mismatches (variant names, address abbreviations). Derive match_signals and conflict_signals from the evidence — prefer the duplicate candidate's own signal lists, then supplement with demographic field comparisons.997. Pull documents and audit logs. Include only documents relevant to identity or external continuity (e.g. shared external specialist documents, merge-specific documents). Exclude unrelated chart summaries.1008. Select the canonical merge target: the record with active clinical data and identity primacy. The other record is the merge source.1019. Determine disposition: `merge_ready` (strong match, few/no conflicts), `merge_ready_with_conflict_review`, `needs_manual_review`, or `do_not_merge`.10210. Pick the specialist provider contact from the provider directory — typically the provider on the shared external continuity document or the primary care provider on the target record.103104### 2. Referral Coordination Packet105106Steps:1071081. Fetch the referral from `/api/referrals/{referral_id}`. Extract `patient_id`, `service_line`, `diagnosis_code`, `narrative`, `authorization_status`, `urgency`, `referral_status`.1092. Fetch patient detail and active conditions, medications, and allergies in parallel.1103. Look up the primary diagnosis code via `/api/icd10/{code}`. Validate: code exists, chapter matches the service line, description matches the narrative.1114. Build the active diagnosis list from the patient conditions and the referral intake narrative. Mark referral-relevant diagnoses (those tied to the service line or the referral reason).1125. Assess allergy readiness: pull patient allergies, mark statuses, and check if a documented allergy statement exists in the referral form.1136. Find the most recent relevant encounter. Look for office visits near the referral date where diagnosis codes and medications mentioned align with the referral reason. Prefer signed encounters.1147. Check required documents: echocardiogram (for cardiology), office notes, authorization records, medication lists. Flag missing documents.1158. Identify the receiving provider from the referral `performer_provider_id` and the provider directory.1169. Build medication highlights: pull active medications, tag those relevant to the referral (e.g. diuretics for heart failure, antihypertensives for blood pressure).11710. Fill the `referral_letter_fields`: choose the single best enum value for each letter section based on the evidence gathered.118119### 3. Care Transition Packet120121Steps:1221231. Fetch patient detail and the target recipient provider.1242. Fetch active conditions, medications, allergies in parallel. Extract normalized_keys, sort alphabetically.1253. Fetch all encounters. Select the four most recent handoff-relevant encounters by date, newest first. Exclude encounters that are stale, outside the surgical handoff window, or unrelated.1264. Fetch immunizations. Select the single most recent immunization by date.1275. Fetch disclosures. Check for one that matches the target provider ID and has `status: "permitted"` for the handoff purpose.1286. Derive risk flags from clinical evidence:129 - `cognitive_memory_loss`: condition key `memory_loss` present130 - `fall_risk_note_required`: lower-extremity OA conditions (hip, knee) plus relevant medications131 - `hypertension`: condition key `hypertension` present132 - `insulin_dependent_diabetes`: `diabetes_type_2` + insulin medication133 - `latex_allergy`: allergy key `latex` present134 - `perioperative_glucose_plan_needed`: diabetes + insulin, especially when a recent care-transition encounter exists1357. Build risk flag evidence objects: for each flag, populate condition_keys, medication_keys, and encounter_ids from the records that support the flag.1368. Determine packet readiness: `ready` if no blockers, `ready_with_risk_flags` if risk flags exist but no blockers, `not_ready` if critical data is missing or disclosure is not permitted.137138### 4. Service-Request Quality Review139140Steps:1411421. Fetch the duplicate candidate to assess merge vs. no-merge for the underlying patients.1432. Fetch the ServiceRequest from `/api/patients/{patient_id}/service-requests` and filter for the given `SR-*` ID.1443. Validate service code via `/api/service-codes/{code}`.1454. Validate each reason code via `/api/icd10/{code}`: check validity, chapter, and whether it matches the patient active condition evidence.1465. Assess SBAR coverage: the ServiceRequest narrative body is expected to contain Situation, Background, Assessment, and Recommendation sections. Check which sections are present.1476. Output the duplicate review decision: `merge`, `review_hold`, or `do_not_merge` with match/conflict signals.148149### 5. Batch Referral Audit150151Steps:1521531. Fetch all referrals via `GET /api/referrals`. Filter to the target batch by `batch_id`.1542. Count total rows and unique patients for the batch summary.1553. For each referral, look up its ICD-10 code in parallel. Flag as `out_of_range_chapter` if the ICD-10 chapter differs from the expected service-line chapter (e.g. non-Musculoskeletal codes in an orthopedics batch). Flag as `unknown_code` if the code does not resolve.1564. Detect laterality and narrative mismatches: compare the ICD-10 description (and laterality, if present) against the referral narrative. Flag `laterality_mismatch` when the ICD-10 code implies a different side than the narrative describes, `narrative_mismatch` when the code description does not match the narrative topic, and `missing_laterality` when the code carries laterality data but the narrative omits it. Do not flag codes already in the out-of-range list — each referral appears in at most one of the two mismatch lists.1575. Detect duplicates: referrals with the same patient_id and same diagnosis_code are candidate duplicates. Group under a `DUP-REF-*` group ID with type `same_patient_resubmission`.1586. Detect insurance anomalies: two different patients sharing the same insurance ID across referrals in the batch. Do not merge these; flag for insurance-membership verification with type `shared_insurance_different_patients`.1597. Build follow-up queues: sort referral IDs into `authorization_missing`, `authorization_pending`, `records_request` (missing office notes), and `imaging_follow_up` (missing or pending imaging).1608. Assign tiers:161 - **Tier 1**: urgent coding or duplicate-blocker referrals (duplicate primary, laterality mismatches on urgent referrals)162 - **Tier 2**: routine coding, authorization, or document blockers163 - **Tier 3**: administrative document-completion items with no clinical urgency1649. Assign owner providers from the provider directory — typically the orthopedic surgeon listed on the referral or the performer provider on the referral record.16510. Compute summary counts for all categories: total rows, unique patients, urgency counts, mismatch counts, queue sizes, and tier counts.166167---168169## Reference Files170171- [api_endpoints.md](references/api_endpoints.md) — Complete inventory of available REST endpoints with paths, parameters, and response field notes.172- [normalization_conventions.md](references/normalization_conventions.md) — Detailed rules for normalized_keys, sorting, set semantics, and distractor handling.