EHR Governance
Quick start
This skill targets a read-only FHIR EHR quality-governance API. Every endpoint is a GET. All responses are FHIR-style JSON bundles or individual resources.
Base URL is provided by the task prompt as <TASK_ENV_BASE_URL>. Replace the token in every URL before calling.
Fetching and exploring
Start every task by fetching the core objects named in the prompt:
- Patient detail:
GET /api/patients/{patient_id}
- Active clinical lists:
GET /api/patients/{patient_id}/conditions, .../medications, .../allergies
- Referrals:
GET /api/referrals/{referral_id} or GET /api/referrals
- Duplicate candidates:
GET /api/duplicates/{candidate_id} or GET /api/duplicates/candidates
- Service requests:
GET /api/patients/{patient_id}/service-requests
Fetch all related resources the prompt references before building the answer JSON. The answer template in input/payloads/answer_template.json defines the output shape; use it to drive which endpoints to call.
Resource shape reference
Every FHIR resource type and its key fields are documented in references/fhir_resources.md. Read that file when you need field-level detail for any resource.
API map
All endpoints and their query parameters are listed in references/api_endpoints.md. Use it to discover available endpoints and verify you are hitting the right URL for each resource type.
Core workflows
Duplicate-chart merge readiness
Read references/workflow_duplicate_merge.md for the full step-by-step. Summary:
- Fetch the duplicate candidate (
/api/duplicates/{candidate_id}) to get match/conflict signals and the linked patient IDs.
- Fetch both patients' demographics, active conditions, active medications, and active allergies.
- Fetch audit logs and documents linked to the candidate's evidence.
- Determine the merge target and source: the target is the active canonical record; the source is the one marked duplicate.
- Union active clinical keys from both patients, removing inactive or stale items.
- Reconcile the duplicate candidate's preview lists against the authoritative patient-active endpoints.
- Classify identity match and conflict signals.
- Identify the specialist contact if an external continuity document exists.
- Evaluate packet readiness: ready, ready_with_review_note, or blocked.
Referral coordination packet
Read references/workflow_referral_coordination.md for the full step-by-step. Summary:
- Fetch the referral detail (
/api/referrals/{referral_id}).
- Fetch the patient, their active conditions/medications/allergies, encounters, and documents.
- Validate the referral's primary diagnosis code against the ICD-10 directory.
- Check for narrative/laterality mismatches between the referral narrative and the ICD-10 description.
- Assess allergy readiness: check for documented allergies, completeness, and conflicts.
- Identify the most recent relevant encounter related to the referral reason.
- Verify required documents (e.g., echocardiogram for cardiology, office notes).
- Determine authorization status and overall readiness.
- Highlight referral-relevant medications.
- Choose normalized referral-letter field values from the enumerated choices.
Care transition packet
Read references/workflow_care_transition.md for the full step-by-step. Summary:
- Fetch the patient detail, active conditions/medications/allergies, encounters, immunizations, disclosures, and documents.
- Identify the recipient provider from the provider directory.
- Select the four most recent handoff-relevant encounters within the transition window, excluding stale or unrelated encounters.
- Find the latest immunization record.
- Find the applicable disclosure for the recipient.
- Derive risk flags from active conditions, medications, and allergies.
- Build risk-flag evidence linking each flag to its supporting condition keys, medication keys, and encounter IDs.
- Assess packet readiness.
ServiceRequest quality review
Read references/workflow_service_request_quality.md for the full step-by-step. Summary:
- Fetch the ServiceRequest, patient, duplicate candidate, and provider records.
- Validate the ServiceRequest service code against the service-codes directory.
- Validate each FHIR reasonCode against the ICD-10 directory.
- Check that each reason code matches patient evidence (conditions or encounter diagnoses).
- Determine the performer's service line from the provider directory.
- Evaluate SBAR coverage: situation, background, assessment, recommendation.
Referral batch audit
Read references/workflow_referral_audit.md for the full step-by-step. Summary:
- Fetch the full referral list and filter for the target batch.
- For each referral, fetch the patient, ICD-10 code detail, and provider.
- Classify invalid/out-of-range diagnosis codes (wrong ICD-10 chapter for the service line).
- Detect laterality or narrative mismatches between the referral narrative and ICD-10 terms.
- Group duplicate referrals by patient (same patient resubmissions).
- Detect insurance anomalies (shared insurance across different patients).
- Build follow-up queues: authorization missing/pending, records requests, imaging follow-up.
- Assign Tier 1/2/3 action plans.
- Compute summary counts.
General rules
Normalized keys
Many outputs use normalized_key values. Derive them by lowercasing the name, replacing spaces/dashes with underscores, and stripping punctuation. The API responses include these keys directly. Prefer the API's normalized_key field when present. If absent, derive the key from the resource's code.text or name field.
ICD-10 validation
ICD-10 codes are validated via GET /api/icd10/{code}. Each resource has code, chapter, and description. For orthopedic referrals the expected chapter is "Musculoskeletal"; for cardiology, "Circulatory". Injury codes (S/T prefix) usually map to the "Injury" chapter and are out-of-range for orthopedic and cardiology service lines.
Set semantics
Arrays described as sets should be sorted alphabetically ascending unless the template explicitly states otherwise. Use the template's ordering guidance when present.
Null handling
When a field accepts null (e.g., merge_target_patient_id when no merge is recommended), emit JSON null, not the string "null" or an empty string.
Enum values
Always use the exact enum string values from the answer template. Do not invent new enum values or paraphrase existing ones.
1---2name: ehr-governance-23description: "FHIR EHR quality-governance workflows: duplicate-chart merge readiness, referral coordination packets, care-transition handoff summaries, ServiceRequest quality review, and referral batch audits. Navigates a read-only FHIR API (patients, conditions, medications, allergies, encounters, immunizations, documents, disclosures, service requests, audit logs, duplicate candidates, referrals, ICD-10 codes, providers, service codes) and produces normalized JSON packets. Use when the task involves EHR data quality, merge packets, referral audits, care transitions, FHIR resource reconciliation, or clinical governance reporting against a structured quality-governance FHIR environment."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/ehr-governance-28---910# EHR Governance1112## Quick start1314This skill targets a read-only FHIR EHR quality-governance API. Every endpoint is a GET. All responses are FHIR-style JSON bundles or individual resources.1516Base URL is provided by the task prompt as `<TASK_ENV_BASE_URL>`. Replace the token in every URL before calling.1718### Fetching and exploring1920Start every task by fetching the core objects named in the prompt:2122- Patient detail: `GET /api/patients/{patient_id}`23- Active clinical lists: `GET /api/patients/{patient_id}/conditions`, `.../medications`, `.../allergies`24- Referrals: `GET /api/referrals/{referral_id}` or `GET /api/referrals`25- Duplicate candidates: `GET /api/duplicates/{candidate_id}` or `GET /api/duplicates/candidates`26- Service requests: `GET /api/patients/{patient_id}/service-requests`2728Fetch all related resources the prompt references **before** building the answer JSON. The answer template in `input/payloads/answer_template.json` defines the output shape; use it to drive which endpoints to call.2930### Resource shape reference3132Every FHIR resource type and its key fields are documented in [references/fhir_resources.md](references/fhir_resources.md). Read that file when you need field-level detail for any resource.3334### API map3536All endpoints and their query parameters are listed in [references/api_endpoints.md](references/api_endpoints.md). Use it to discover available endpoints and verify you are hitting the right URL for each resource type.3738## Core workflows3940### Duplicate-chart merge readiness4142Read [references/workflow_duplicate_merge.md](references/workflow_duplicate_merge.md) for the full step-by-step. Summary:43441. Fetch the duplicate candidate (`/api/duplicates/{candidate_id}`) to get match/conflict signals and the linked patient IDs.452. Fetch both patients' demographics, active conditions, active medications, and active allergies.463. Fetch audit logs and documents linked to the candidate's evidence.474. Determine the merge target and source: the target is the active canonical record; the source is the one marked duplicate.485. Union active clinical keys from both patients, removing inactive or stale items.496. Reconcile the duplicate candidate's preview lists against the authoritative patient-active endpoints.507. Classify identity match and conflict signals.518. Identify the specialist contact if an external continuity document exists.529. Evaluate packet readiness: ready, ready_with_review_note, or blocked.5354### Referral coordination packet5556Read [references/workflow_referral_coordination.md](references/workflow_referral_coordination.md) for the full step-by-step. Summary:57581. Fetch the referral detail (`/api/referrals/{referral_id}`).592. Fetch the patient, their active conditions/medications/allergies, encounters, and documents.603. Validate the referral's primary diagnosis code against the ICD-10 directory.614. Check for narrative/laterality mismatches between the referral narrative and the ICD-10 description.625. Assess allergy readiness: check for documented allergies, completeness, and conflicts.636. Identify the most recent relevant encounter related to the referral reason.647. Verify required documents (e.g., echocardiogram for cardiology, office notes).658. Determine authorization status and overall readiness.669. Highlight referral-relevant medications.6710. Choose normalized referral-letter field values from the enumerated choices.6869### Care transition packet7071Read [references/workflow_care_transition.md](references/workflow_care_transition.md) for the full step-by-step. Summary:72731. Fetch the patient detail, active conditions/medications/allergies, encounters, immunizations, disclosures, and documents.742. Identify the recipient provider from the provider directory.753. Select the four most recent handoff-relevant encounters within the transition window, excluding stale or unrelated encounters.764. Find the latest immunization record.775. Find the applicable disclosure for the recipient.786. Derive risk flags from active conditions, medications, and allergies.797. Build risk-flag evidence linking each flag to its supporting condition keys, medication keys, and encounter IDs.808. Assess packet readiness.8182### ServiceRequest quality review8384Read [references/workflow_service_request_quality.md](references/workflow_service_request_quality.md) for the full step-by-step. Summary:85861. Fetch the ServiceRequest, patient, duplicate candidate, and provider records.872. Validate the ServiceRequest service code against the service-codes directory.883. Validate each FHIR reasonCode against the ICD-10 directory.894. Check that each reason code matches patient evidence (conditions or encounter diagnoses).905. Determine the performer's service line from the provider directory.916. Evaluate SBAR coverage: situation, background, assessment, recommendation.9293### Referral batch audit9495Read [references/workflow_referral_audit.md](references/workflow_referral_audit.md) for the full step-by-step. Summary:96971. Fetch the full referral list and filter for the target batch.982. For each referral, fetch the patient, ICD-10 code detail, and provider.993. Classify invalid/out-of-range diagnosis codes (wrong ICD-10 chapter for the service line).1004. Detect laterality or narrative mismatches between the referral narrative and ICD-10 terms.1015. Group duplicate referrals by patient (same patient resubmissions).1026. Detect insurance anomalies (shared insurance across different patients).1037. Build follow-up queues: authorization missing/pending, records requests, imaging follow-up.1048. Assign Tier 1/2/3 action plans.1059. Compute summary counts.106107## General rules108109### Normalized keys110111Many outputs use `normalized_key` values. Derive them by lowercasing the name, replacing spaces/dashes with underscores, and stripping punctuation. The API responses include these keys directly. Prefer the API's `normalized_key` field when present. If absent, derive the key from the resource's `code.text` or `name` field.112113### ICD-10 validation114115ICD-10 codes are validated via `GET /api/icd10/{code}`. Each resource has `code`, `chapter`, and `description`. For orthopedic referrals the expected chapter is "Musculoskeletal"; for cardiology, "Circulatory". Injury codes (S/T prefix) usually map to the "Injury" chapter and are out-of-range for orthopedic and cardiology service lines.116117### Set semantics118119Arrays described as sets should be sorted alphabetically ascending unless the template explicitly states otherwise. Use the template's `ordering` guidance when present.120121### Null handling122123When a field accepts `null` (e.g., `merge_target_patient_id` when no merge is recommended), emit JSON `null`, not the string `"null"` or an empty string.124125### Enum values126127Always use the exact enum string values from the answer template. Do not invent new enum values or paraphrase existing ones.