prism-shadow EHR Quality-Governance Packet
Reusable method for producing a normalized JSON packet from a read-only EHR / referral governance API. Distilled from five governance task archetypes: duplicate-chart merge readiness, referral batch audit, care-transition handoff, service-request + duplicate-review validation, and referral coordination.
When to use
- A task points at a read-only EHR/referral API (base URL in
environment_access.md, often written<TASK_ENV_BASE_URL>in the prompt). - The prompt names object IDs (
P-...,DUP-...,REF-..., batch ids,SR-...,PRV-...) and asks for a packet / audit / summary. - Output must conform to an
answer_template.json(required keys, enums, set semantics, ordering). - Keywords: duplicate, merge readiness, referral audit, care transition, handoff, ServiceRequest, governance queue, authorization, ICD-10, SBAR.
Golden rules (read first)
answer_template.jsonis the contract. Emit exactly its required top-level keys; restrict enum fields to itsallowed_values; follow its ordering notes. Where it saysstring, emit the environment label verbatim.- The network API is the only source of truth for environment data. Resolve
the base URL from
environment_access.md. Use only the allowed GET endpoints. Never read local source files for environment data; never invent IDs, codes, or values. - Patient active-list endpoints are authoritative over the duplicate
merge_preview. Clinical-key unions come from the patients' active condition/medication/allergy endpoints, not the preview. - Only
status=activerecords count towardactive_*_keysunions; inactive /entered-in-error/ non-merge items go toexcluded_distractors. normalized_keyis the dedup key for clinical unions — union across the relevant patients, dedupe, sort ascending.- Output is JSON only — no prose, no markdown fences, no narrative SOP text. Arrays that are sets: dedupe + sort per the template.
Workflow
- Intake. Read
prompt.txt(extract every object ID + service line / batch / date context),payloads/answer_template.json(the contract — seereferences/output_contract.md), and any otherpayloads/*.json. - Resolve access. Read
environment_access.mdfor the base URL and allowed endpoints. Map<TASK_ENV_BASE_URL>to that base URL. - Gather evidence. Fetch each named object and its related sub-resources.
Use
references/endpoints_and_shapes.mdfor paths and field shapes. For a full patient bundle, runscripts/fetch_patient_bundle.sh <base_url> <pid>. - Validate codes. ICD-10 via
/api/icd10(chapter,requires_laterality,expected_terms); service codes via/api/service-codes(active, service-line match). Seereferences/reasoning_playbooks.md. - Reason per archetype. Identify the archetype and apply its playbook in
references/reasoning_playbooks.md. Compose playbooks when a task spans concerns (e.g. a referral audit still validates ICD-10; a merge packet still reconciles clinical lists). - Normalize output. Build the single JSON object per
references/output_contract.md. Dedupe + sort set arrays; usenull(not"") where the type isstring or nulland evidence is absent. - Self-check. Run the 7-point checklist in
references/output_contract.mdbefore returning.
Archetype → playbook map
| If the task is… | Playbook | Key output sections |
|---|---|---|
Duplicate-chart merge readiness (DUP-..., 2 patients, merge_packet_request.json) |
§1 | merge/merge_decision, clinical_unions, active_list_reconciliation, identity_signals, evidence, packet_contact |
Referral batch audit (audit for batch <BATCH>) |
§2 | invalid_or_out_of_range_code_referrals, laterality_or_narrative_mismatch_referrals, duplicate_groups, follow_up_queues, action_plan, summary_counts |
Care-transition handoff (addressed to a provider, handoff_encounters) |
§3 | active_*_keys, handoff_encounters, source_selection, latest_immunization, disclosure, risk_flags, packet_readiness |
Service-request + duplicate-review validation (SR-..., DUP-..., SBAR) |
§4 | duplicate_review, service_request, sbar_coverage |
Referral coordination (single REF-... + patient, referral_letter_fields) |
§5 | active_diagnoses, referral_code_set, allergy_readiness, required_document_evidence, authorization_readiness, medication_highlights, referral_letter_fields |
Critical reasoning shortcuts (most-missed steps)
- Merge disposition: strong matches + only minor conflicts
(
address_abbreviation,name_variant,suffix_discrepancy) → ready/merge; anyopposite_laterality_problem,different_dob, or null target/source withneeds_review→ review/do_not_merge. Leave target/source null when not assigned (if the type allows). *_keys_added_from_active_endpoints= keys in the endpoint union but missing frommerge_preview— reconcile preview vs truth.- ICD-10 validity for an orthopedic batch: chapter must be
Musculoskeletal; laterality codes require the narrative's side to matchexpected_terms. - Duplicate vs separate: same patient + same clinical intent = duplicate
group (
consolidate_under_original); same patient + distinct clinical concerns = separate review, NOT a duplicate. Shared insurance across different patients = verify, do not merge. - Tiering: Tier 1 = urgent or duplicate-blocker; Tier 2 = routine with coding/auth/document blocker; Tier 3 = administrative document completion.
- Document evidence: identity / external-continuity documents only; exclude chart summaries and clinical notes. Audit evidence: only events for the involved patients bearing on this review.
References
references/endpoints_and_shapes.md— allowed endpoints + record field shapes.references/reasoning_playbooks.md— the five archetype playbooks + code validation, duplicate/insurance logic, tiering.references/output_contract.md— normalization rules, ordering, exclusions, self-check checklist.scripts/fetch_patient_bundle.sh— gather all sub-resources for one patient.