EHR Quality-Governance Packet Builder
Produce normalized JSON packets for healthcare quality-governance workflows by
querying a shared read-only EHR REST API. Every task provides a concrete
answer template (often named answer_template.json or embedded in the prompt)
and points at a task-environment base URL. The solver's job is to gather
evidence through the API, reconcile it against the template's controlled
vocabularies, and emit strictly conformant JSON.
API orientation
The task environment provides these endpoint families at <TASK_ENV_BASE_URL>.
All are read-only GETs. Replace {id} placeholders with real identifiers
found in upstream responses.
| Scope |
Endpoints |
| Patients |
/api/patients, /api/patients/{id}, /api/patients/{id}/conditions, /api/patients/{id}/medications, /api/patients/{id}/allergies, /api/patients/{id}/encounters, /api/patients/{id}/immunizations, /api/patients/{id}/documents, /api/patients/{id}/service-requests, /api/patients/{id}/disclosures |
| Duplicates |
/api/duplicates/candidates, /api/duplicates/{candidate_id} |
| Referrals |
/api/referrals, /api/referrals/{referral_id} |
| Audit |
/api/audit-logs |
| Coding |
/api/icd10, /api/icd10/{code} |
| Providers |
/api/providers, /api/providers/{provider_id} |
| Service codes |
/api/service-codes, /api/service-codes/{code} |
Retrieval pattern: Start with the primary object (patient, duplicate
candidate, referral, or referral batch). Every response contains IDs that
branch into further endpoints: a patient record yields a provider_id you look
up; a duplicate candidate yields two patient_id values to cross-reference; a
referral carries diagnosis_code strings to validate against ICD-10. Follow
these chains until every required field in the answer template has endpoint
evidence behind it.
When the task names a family of endpoints as "relevant" or "available", treat
that as the authority list. Endpoints outside the listed families are not part
of the task environment for that run, even if they appear in other examples.
Core conventions that apply across all packet types
Normalized keys
Conditions, medications, and allergies each carry a normalized_key field in
their endpoint records. This key is the canonical, stable identifier used
throughout the answer template for:
- clinical union arrays (
active_condition_keys, active_medication_keys,
active_allergy_keys),
- active-list reconciliation deltas,
- risk-flag evidence mapping,
- excluded-distractor arrays.
Always use the normalized_key value, never the display name or code, when the
answer template asks for a condition/medication/allergy key.
Active vs. inactive records
Most endpoints return a status field. When the template calls for "active"
lists, filter to records whose status is "active". Records with other
statuses (inactive, entered-in-error, resolved, etc.) are stale records;
include them only in explicit "excluded" or "distractor" arrays when the
template has that slot. If the template does not have an excluded/distractor
section, stale records are simply omitted.
Alphabetical sorting
Arrays described as "sets", "sorted alphabetically", or "sorted ascending"
must be ordered by their string values using standard lexicographic sort
(case-sensitive, ASCII order). This applies to:
condition_keys, medication_keys, allergy_keys,
reason_codes, match_signals, conflict_signals,
document_ids, audit_ids, referral_ids,
blocking_issue_codes, missing_sections, sections_present,
risk_flags and nested evidence arrays.
Object arrays of referrals are sorted by referral_id ascending. Encounter
arrays are sorted newest-to-oldest by date unless the template says otherwise.
Controlled vocabulary (enums)
Most decision fields use fixed enum values defined in the answer template.
Never invent a value outside the template's allowed list. When the template
provides allowed_values for a field, pick only from that list. Common
recurring enums include:
- Disposition / decision:
ready_to_merge, merge, do_not_merge,
review_hold, needs_review, confirmed_duplicate, not_duplicate.
- Service lines:
cardiology, orthopedics, pulmonology,
neurology, skilled_nursing, oncology, primary_care.
- Readiness:
ready, ready_with_review_note, ready_with_risk_flags,
blocked, not_ready, ready_to_send, hold_for_*.
- Risk flags: the six canonical values
cognitive_memory_loss,
fall_risk_note_required, hypertension, insulin_dependent_diabetes,
latex_allergy, perioperative_glucose_plan_needed.
- ICD-10 validation:
valid_matches_narrative,
valid_but_narrative_mismatch, invalid_code, wrong_service_chapter.
- Mismatch types:
laterality_mismatch, narrative_mismatch,
missing_laterality.
- Tier reasons:
urgent_coding_or_duplicate_blocker,
routine_coding_auth_or_document_blocker,
administrative_document_completion.
Evidence citation
Every decision in the packet must be traceable to an endpoint response. Cite
specific IDs: document IDs for required documents, audit IDs for audit history,
encounter IDs for handoff encounters, provider IDs for contacts, immunization
IDs for latest immunization. If a field like document_ids or audit_ids is
empty in the evidence, emit an empty array [] rather than omitting the key.
Answer template conformance
The answer template (whether a standalone JSON file or inlined in the prompt)
is the authoritative output schema. Rules for working with it:
- Emit every top-level key the template marks as
required_top_level_keys or
lists at the top level.
- Do not add extra top-level keys the template does not define.
- When the template says
"required_value": "train_NNN", emit that exact
literal string for the task_id field.
- Use the types, enums, and ordering rules exactly as stated.
- When a field allows
null, use null (not a string "null") when there is
genuinely no value from the evidence.
- Emit only the JSON object. Do not wrap it in markdown fences unless the
output channel requires them.
Workflow-specific patterns
Duplicate-chart merge readiness
- Fetch the duplicate candidate via
/api/duplicates/{candidate_id}. Note
the two patient IDs and any pre-computed match/conflict signals the
candidate record provides.
- Fetch each patient's demographics, conditions, medications, allergies,
documents, and service-requests from the patient-scoped endpoints.
- Build the active-key unions by taking the union of both patients' active
normalized_key values for conditions, medications, and allergies.
- Reconcile against the duplicate candidate's own clinical preview (if one
exists): keys present in the patient endpoints but absent from the
duplicate preview go into
*_added_from_active_endpoints arrays. The
authoritative source is the patient active-list endpoints over the
duplicate preview.
- Identity signals: collect match signals and conflict signals from the
duplicate candidate record, from demographic comparison, and from external
document evidence (e.g., a shared cardiology document on one patient's
record that ties the identities together). Use the template's
allowed_values for signal labels.
- Document/audit evidence: include documents that relate to identity
matching or external continuity (not routine chart summaries). Include
audit log entries that reference the duplicate candidate. Exclude
document types that the task's selection policy excludes.
- Determine the canonical target (the patient with the longer or more
complete active record, or the one the duplicate record already points to)
and source (the shell or less-complete record).
- Set disposition based on signal strength: strong match + few conflicts
means
ready_to_merge; significant conflicts mean needs_review; clear
mismatch means do_not_merge.
- Provider contacts: look up the specialist tied to the key external
evidence document, plus the primary care provider from the target patient
record.
Referral coordination
- Fetch the referral via
/api/referrals/{referral_id}. Extract the
patient ID, diagnosis code(s), batch ID, service line, and status.
- Fetch the patient's conditions, medications, allergies, encounters, and
documents.
- Build the active-diagnosis list from active conditions, marking each
referral_relevant based on whether its code matches the referral's
primary/supporting codes or narrative.
- Validate the primary diagnosis code against
/api/icd10/{code}. Check:
- validity (does the code exist?)
- chapter match (is the chapter appropriate for the service line?
Cardiology means Circulatory; Orthopedics means Musculoskeletal)
- narrative match (does the ICD-10 description align with the referral's
written narrative or the patient's active conditions?)
- Allergy readiness: gather active allergies.
complete_documented if
allergy records exist and are consistent; incomplete_needs_clarification
if the referral form and patient chart disagree; no_known_allergies if
records explicitly state none.
- Recent encounter evidence: pick the encounter whose date, diagnosis codes,
medications, and care-plan tag best align with the referral's purpose.
The signed status must be
signed for the encounter to count as ready
evidence.
- Required documents: check for an echocardiogram (cardiology) or relevant
imaging report, plus an office note. A document is "received" when a
record with matching type exists at the patient's document endpoint and
has
status: "final".
- Receiving provider: identify by matching the referral's target provider or
the service line's specialist from
/api/providers.
- Authorization: check the referral's authorization status (from the
referral detail or an authorization sub-record). Overall readiness is
ready_to_send only when authorization is approved, all required
documents are present, allergies are documented, and codes are valid.
- Referral letter fields: each
*_choice is a single string selected from
the template's allowed values. The choice must be the one that most
accurately reflects the evidence gathered in the steps above.
Care transition packet
- Fetch the patient and verify the recipient provider exists via
/api/providers/{provider_id}.
- Gather active conditions, medications, and allergies; emit their
normalized_key values sorted alphabetically.
- Handoff encounters: fetch all encounters, then select exactly four.
Selection: prioritize encounters with types like
care_transition or
office_visit within a 90-day lookback window, signed, and related to
the transition's service line. Sort selected encounters newest-to-oldest
by date. Track excluded encounters (stale, outside-window, or unrelated)
in the excluded_encounter_ids array.
- Latest immunization: the immunization with the most recent date from the
patient's immunization endpoint.
- Applicable disclosure: fetch disclosures, filter to the one whose
recipient_provider_id matches the recipient provider. It must be
permitted for the packet to be ready.
- Risk flags: derive from the allowed_values list. For each flag, collect
supporting evidence from active conditions, active medications, and
encounters. A flag is present when the evidence supports it:
cognitive_memory_loss means a condition with normalized_key
memory_loss or equivalent.
fall_risk_note_required means bilateral lower-extremity OA conditions
or recent fall-related encounters.
hypertension means active hypertension condition.
insulin_dependent_diabetes means diabetes_type_2 condition plus an
active insulin medication.
latex_allergy means active latex allergy.
perioperative_glucose_plan_needed means diabetes_type_2 condition in
a surgical handoff context.
- Packet readiness:
ready when all required sections have evidence and the
disclosure is permitted; ready_with_risk_flags when risk flags are
present but nothing blocks sending; not_ready when a required piece is
missing.
Quality-governance case review (duplicate + ServiceRequest)
- Fetch the duplicate candidate via
/api/duplicates/{candidate_id}.
Determine candidate_status (confirmed_duplicate, needs_review, or
not_duplicate) and decision (merge, review_hold, do_not_merge)
from the match/conflict signal balance.
- Strong identity match with no conflicting laterality problems means lean
merge. Conflicting laterality (one patient has left-knee problems, the
other right-knee) is a strong
review_hold signal even when
demographics match.
- When decision is
review_hold, merge_target_patient_id and
merge_source_patient_id are null.
- Fetch the ServiceRequest via the patient's service-request endpoint.
Validate every field against the template's allowed enums. Pay special
attention to
service_code_valid (validate against
/api/service-codes/{code}) and reason_code_validation (validate each
diagnosis code against /api/icd10/{code}, checking validity, chapter,
and whether the code's description matches patient evidence).
- SBAR coverage: check whether the ServiceRequest includes Situation,
Background, Assessment, and Recommendation sections.
complete is true
only when all four are present.
Batch referral audit
- Fetch the referral batch via
/api/referrals with appropriate query
parameters to isolate the named batch. Count rows and unique patients.
- Validate every referral's diagnosis code against
/api/icd10/{code}:
- Codes whose chapter is not the expected chapter for the service line
(e.g.,
Injury instead of Musculoskeletal for orthopedics) are
out_of_range_chapter.
- Codes not found in the ICD-10 directory are
unknown_code.
- Laterality and narrative mismatch: for each referral, compare the ICD-10
description to the referral's
diagnosis_narrative.
laterality_mismatch: the ICD-10 code specifies one side (e.g., left
medial meniscus tear) but the narrative mentions the opposite side or
a different joint.
narrative_mismatch: the narrative describes a condition unrelated to
the code (e.g., "lumbar radiculopathy" for a knee meniscus tear code).
missing_laterality: the narrative omits a laterality marker present
in the code description.
A referral can carry multiple mismatch types.
- Duplicate detection: group referrals by
patient_id. When the same
patient has multiple referrals in the batch with the same diagnosis code
or overlapping clinical intent, they form a duplicate group of type
same_patient_resubmission. The tiering policy assigns all rows in the
group as tier_1_duplicate_blockers. Same-patient referrals that are
genuinely separate clinical reviews (different body parts or conditions)
go in separate_same_patient_referral_ids.
- Insurance anomalies: when two different patients share the same
insurance_id and both appear in the batch, flag as
shared_insurance_different_patients. This is a verification item, not
a merge recommendation.
- Follow-up queues: classify each referral by what it lacks:
authorization_missing: no authorization record at all.
authorization_pending: authorization exists but not yet approved.
records_request: office-note document missing.
imaging_follow_up: imaging report missing or not final.
A referral can appear in multiple queues.
- Action plan tiers:
- Tier 1 (immediate): duplicate-blocker rows or referrals with both
coding errors and missing critical documents or authorizations. Assign
to the batch's primary ortho provider.
- Tier 2 (short-term): referrals with coding mismatches, missing
authorizations, or missing documents that are not duplicates. Spread
across available ortho providers.
- Tier 3 (administrative): referrals that only need document completion
with no coding or authorization issues.
- Summary counts: compute each integer from the arrays populated above. The
validated_ready_no_follow_up_count is the number of referrals with no
coding issues, no mismatches, complete documents, and approved
authorization -- the ones that need no action at all.
ICD-10 chapter mapping for service lines
When validating whether a diagnosis code belongs to the right service line,
use this mapping:
| Service line |
Expected ICD-10 chapter |
orthopedics |
Musculoskeletal |
cardiology |
Circulatory |
pulmonology |
Respiratory |
neurology |
Nervous System |
oncology |
Neoplasms |
The ICD-10 endpoint's chapter field gives the actual chapter for a code.
Compare it against the expected chapter above. A mismatch means the code
is out of range for that service line.
Document selection policy
Not every document belongs in a packet. When a packet needs document
evidence, include only documents that:
- relate to identity matching or external continuity (for merge packets),
- are clinically required for the referral or transition (echo for
cardiology, office note for any referral, imaging for orthopedics),
- have status
final (preliminary or cancelled documents are not
ready evidence).
Exclude: chart summaries, generic administrative documents, and documents
whose type is listed in excluded_document_types by the template.
General troubleshooting
- Missing patient data: If a patient endpoint returns fewer records than
expected, do not fabricate. The answer reflects only what the API returns.
- Null fields: When an optional field has no value in the API evidence,
emit
null only if the template explicitly types the field as
["string", "null"] or similar. Otherwise omit or use an empty array.
- Ambiguous identities: When duplicate-candidate signals are mixed (some
match, some conflict), lean toward
needs_review / review_hold. Cite
the specific conflict signals that prevent a clean merge.
- Enum not found: If the evidence doesn't cleanly fit any allowed enum
value, re-read the evidence more carefully -- the design intent is that
exactly one value applies. Do not invent new values.
1---2name: ehr-quality-governance-33description: Build normalized EHR quality-governance JSON packets by querying a shared read-only FHIR-style REST API. Use this skill whenever the task involves duplicate-chart merge readiness, referral coordination, care-transition packets, quality-governance case review, or batch referral audits against an EHR environment. Trigger on mentions of EHR, FHIR, duplicate candidates, referral packets, care transitions, quality governance, clinical data reconciliation, ICD-10 validation, provider lookup, or answer_template.json with clinical/administrative keys.4metadata:5 source: https://skillmd.com/skills/prism-shadow/ehr-quality-governance-36---78# EHR Quality-Governance Packet Builder910Produce normalized JSON packets for healthcare quality-governance workflows by11querying a shared read-only EHR REST API. Every task provides a concrete12answer template (often named `answer_template.json` or embedded in the prompt)13and points at a task-environment base URL. The solver's job is to gather14evidence through the API, reconcile it against the template's controlled15vocabularies, and emit strictly conformant JSON.1617## API orientation1819The task environment provides these endpoint families at `<TASK_ENV_BASE_URL>`.20All are read-only GETs. Replace `{id}` placeholders with real identifiers21found in upstream responses.2223| Scope | Endpoints |24|---|---|25| Patients | `/api/patients`, `/api/patients/{id}`, `/api/patients/{id}/conditions`, `/api/patients/{id}/medications`, `/api/patients/{id}/allergies`, `/api/patients/{id}/encounters`, `/api/patients/{id}/immunizations`, `/api/patients/{id}/documents`, `/api/patients/{id}/service-requests`, `/api/patients/{id}/disclosures` |26| Duplicates | `/api/duplicates/candidates`, `/api/duplicates/{candidate_id}` |27| Referrals | `/api/referrals`, `/api/referrals/{referral_id}` |28| Audit | `/api/audit-logs` |29| Coding | `/api/icd10`, `/api/icd10/{code}` |30| Providers | `/api/providers`, `/api/providers/{provider_id}` |31| Service codes | `/api/service-codes`, `/api/service-codes/{code}` |3233**Retrieval pattern**: Start with the primary object (patient, duplicate34candidate, referral, or referral batch). Every response contains IDs that35branch into further endpoints: a patient record yields a `provider_id` you look36up; a duplicate candidate yields two `patient_id` values to cross-reference; a37referral carries `diagnosis_code` strings to validate against ICD-10. Follow38these chains until every required field in the answer template has endpoint39evidence behind it.4041When the task names a family of endpoints as "relevant" or "available", treat42that as the authority list. Endpoints outside the listed families are not part43of the task environment for that run, even if they appear in other examples.4445## Core conventions that apply across all packet types4647### Normalized keys4849Conditions, medications, and allergies each carry a `normalized_key` field in50their endpoint records. This key is the canonical, stable identifier used51throughout the answer template for:5253- clinical union arrays (`active_condition_keys`, `active_medication_keys`,54 `active_allergy_keys`),55- active-list reconciliation deltas,56- risk-flag evidence mapping,57- excluded-distractor arrays.5859Always use the `normalized_key` value, never the display name or code, when the60answer template asks for a condition/medication/allergy key.6162### Active vs. inactive records6364Most endpoints return a `status` field. When the template calls for "active"65lists, filter to records whose `status` is `"active"`. Records with other66statuses (inactive, entered-in-error, resolved, etc.) are stale records;67include them only in explicit "excluded" or "distractor" arrays when the68template has that slot. If the template does not have an excluded/distractor69section, stale records are simply omitted.7071### Alphabetical sorting7273Arrays described as "sets", "sorted alphabetically", or "sorted ascending"74must be ordered by their string values using standard lexicographic sort75(case-sensitive, ASCII order). This applies to:7677- `condition_keys`, `medication_keys`, `allergy_keys`,78- `reason_codes`, `match_signals`, `conflict_signals`,79- `document_ids`, `audit_ids`, `referral_ids`,80- `blocking_issue_codes`, `missing_sections`, `sections_present`,81- `risk_flags` and nested evidence arrays.8283Object arrays of referrals are sorted by `referral_id` ascending. Encounter84arrays are sorted newest-to-oldest by date unless the template says otherwise.8586### Controlled vocabulary (enums)8788Most decision fields use fixed enum values defined in the answer template.89Never invent a value outside the template's allowed list. When the template90provides `allowed_values` for a field, pick only from that list. Common91recurring enums include:9293- **Disposition / decision**: `ready_to_merge`, `merge`, `do_not_merge`,94 `review_hold`, `needs_review`, `confirmed_duplicate`, `not_duplicate`.95- **Service lines**: `cardiology`, `orthopedics`, `pulmonology`,96 `neurology`, `skilled_nursing`, `oncology`, `primary_care`.97- **Readiness**: `ready`, `ready_with_review_note`, `ready_with_risk_flags`,98 `blocked`, `not_ready`, `ready_to_send`, `hold_for_*`.99- **Risk flags**: the six canonical values `cognitive_memory_loss`,100 `fall_risk_note_required`, `hypertension`, `insulin_dependent_diabetes`,101 `latex_allergy`, `perioperative_glucose_plan_needed`.102- **ICD-10 validation**: `valid_matches_narrative`,103 `valid_but_narrative_mismatch`, `invalid_code`, `wrong_service_chapter`.104- **Mismatch types**: `laterality_mismatch`, `narrative_mismatch`,105 `missing_laterality`.106- **Tier reasons**: `urgent_coding_or_duplicate_blocker`,107 `routine_coding_auth_or_document_blocker`,108 `administrative_document_completion`.109110### Evidence citation111112Every decision in the packet must be traceable to an endpoint response. Cite113specific IDs: document IDs for required documents, audit IDs for audit history,114encounter IDs for handoff encounters, provider IDs for contacts, immunization115IDs for latest immunization. If a field like `document_ids` or `audit_ids` is116empty in the evidence, emit an empty array `[]` rather than omitting the key.117118### Answer template conformance119120The answer template (whether a standalone JSON file or inlined in the prompt)121is the authoritative output schema. Rules for working with it:122123- Emit every top-level key the template marks as `required_top_level_keys` or124 lists at the top level.125- Do not add extra top-level keys the template does not define.126- When the template says `"required_value": "train_NNN"`, emit that exact127 literal string for the `task_id` field.128- Use the types, enums, and ordering rules exactly as stated.129- When a field allows `null`, use `null` (not a string `"null"`) when there is130 genuinely no value from the evidence.131- Emit only the JSON object. Do not wrap it in markdown fences unless the132 output channel requires them.133134## Workflow-specific patterns135136### Duplicate-chart merge readiness1371381. Fetch the duplicate candidate via `/api/duplicates/{candidate_id}`. Note139 the two patient IDs and any pre-computed match/conflict signals the140 candidate record provides.1412. Fetch each patient's demographics, conditions, medications, allergies,142 documents, and service-requests from the patient-scoped endpoints.1433. Build the active-key unions by taking the union of both patients' active144 `normalized_key` values for conditions, medications, and allergies.1454. Reconcile against the duplicate candidate's own clinical preview (if one146 exists): keys present in the patient endpoints but absent from the147 duplicate preview go into `*_added_from_active_endpoints` arrays. The148 authoritative source is the patient active-list endpoints over the149 duplicate preview.1505. Identity signals: collect match signals and conflict signals from the151 duplicate candidate record, from demographic comparison, and from external152 document evidence (e.g., a shared cardiology document on one patient's153 record that ties the identities together). Use the template's154 `allowed_values` for signal labels.1556. Document/audit evidence: include documents that relate to identity156 matching or external continuity (not routine chart summaries). Include157 audit log entries that reference the duplicate candidate. Exclude158 document types that the task's selection policy excludes.1597. Determine the canonical target (the patient with the longer or more160 complete active record, or the one the duplicate record already points to)161 and source (the shell or less-complete record).1628. Set disposition based on signal strength: strong match + few conflicts163 means `ready_to_merge`; significant conflicts mean `needs_review`; clear164 mismatch means `do_not_merge`.1659. Provider contacts: look up the specialist tied to the key external166 evidence document, plus the primary care provider from the target patient167 record.168169### Referral coordination1701711. Fetch the referral via `/api/referrals/{referral_id}`. Extract the172 patient ID, diagnosis code(s), batch ID, service line, and status.1732. Fetch the patient's conditions, medications, allergies, encounters, and174 documents.1753. Build the active-diagnosis list from active conditions, marking each176 `referral_relevant` based on whether its code matches the referral's177 primary/supporting codes or narrative.1784. Validate the primary diagnosis code against `/api/icd10/{code}`. Check:179 - validity (does the code exist?)180 - chapter match (is the chapter appropriate for the service line?181 Cardiology means Circulatory; Orthopedics means Musculoskeletal)182 - narrative match (does the ICD-10 description align with the referral's183 written narrative or the patient's active conditions?)1845. Allergy readiness: gather active allergies. `complete_documented` if185 allergy records exist and are consistent; `incomplete_needs_clarification`186 if the referral form and patient chart disagree; `no_known_allergies` if187 records explicitly state none.1886. Recent encounter evidence: pick the encounter whose date, diagnosis codes,189 medications, and care-plan tag best align with the referral's purpose.190 The signed status must be `signed` for the encounter to count as ready191 evidence.1927. Required documents: check for an echocardiogram (cardiology) or relevant193 imaging report, plus an office note. A document is "received" when a194 record with matching type exists at the patient's document endpoint and195 has `status: "final"`.1968. Receiving provider: identify by matching the referral's target provider or197 the service line's specialist from `/api/providers`.1989. Authorization: check the referral's authorization status (from the199 referral detail or an authorization sub-record). Overall readiness is200 `ready_to_send` only when authorization is approved, all required201 documents are present, allergies are documented, and codes are valid.20210. Referral letter fields: each `*_choice` is a single string selected from203 the template's allowed values. The choice must be the one that most204 accurately reflects the evidence gathered in the steps above.205206### Care transition packet2072081. Fetch the patient and verify the recipient provider exists via209 `/api/providers/{provider_id}`.2102. Gather active conditions, medications, and allergies; emit their211 `normalized_key` values sorted alphabetically.2123. Handoff encounters: fetch all encounters, then select exactly four.213 Selection: prioritize encounters with types like `care_transition` or214 `office_visit` within a 90-day lookback window, signed, and related to215 the transition's service line. Sort selected encounters newest-to-oldest216 by date. Track excluded encounters (stale, outside-window, or unrelated)217 in the `excluded_encounter_ids` array.2184. Latest immunization: the immunization with the most recent date from the219 patient's immunization endpoint.2205. Applicable disclosure: fetch disclosures, filter to the one whose221 `recipient_provider_id` matches the recipient provider. It must be222 `permitted` for the packet to be ready.2236. Risk flags: derive from the allowed_values list. For each flag, collect224 supporting evidence from active conditions, active medications, and225 encounters. A flag is present when the evidence supports it:226 - `cognitive_memory_loss` means a condition with `normalized_key`227 `memory_loss` or equivalent.228 - `fall_risk_note_required` means bilateral lower-extremity OA conditions229 or recent fall-related encounters.230 - `hypertension` means active `hypertension` condition.231 - `insulin_dependent_diabetes` means `diabetes_type_2` condition plus an232 active insulin medication.233 - `latex_allergy` means active `latex` allergy.234 - `perioperative_glucose_plan_needed` means `diabetes_type_2` condition in235 a surgical handoff context.2367. Packet readiness: `ready` when all required sections have evidence and the237 disclosure is permitted; `ready_with_risk_flags` when risk flags are238 present but nothing blocks sending; `not_ready` when a required piece is239 missing.240241### Quality-governance case review (duplicate + ServiceRequest)2422431. Fetch the duplicate candidate via `/api/duplicates/{candidate_id}`.244 Determine candidate_status (`confirmed_duplicate`, `needs_review`, or245 `not_duplicate`) and decision (`merge`, `review_hold`, `do_not_merge`)246 from the match/conflict signal balance.247 - Strong identity match with no conflicting laterality problems means lean248 merge. Conflicting laterality (one patient has left-knee problems, the249 other right-knee) is a strong `review_hold` signal even when250 demographics match.251 - When decision is `review_hold`, `merge_target_patient_id` and252 `merge_source_patient_id` are `null`.2532. Fetch the ServiceRequest via the patient's service-request endpoint.254 Validate every field against the template's allowed enums. Pay special255 attention to `service_code_valid` (validate against256 `/api/service-codes/{code}`) and `reason_code_validation` (validate each257 diagnosis code against `/api/icd10/{code}`, checking validity, chapter,258 and whether the code's description matches patient evidence).2593. SBAR coverage: check whether the ServiceRequest includes Situation,260 Background, Assessment, and Recommendation sections. `complete` is true261 only when all four are present.262263### Batch referral audit2642651. Fetch the referral batch via `/api/referrals` with appropriate query266 parameters to isolate the named batch. Count rows and unique patients.2672. Validate every referral's diagnosis code against `/api/icd10/{code}`:268 - Codes whose chapter is not the expected chapter for the service line269 (e.g., `Injury` instead of `Musculoskeletal` for orthopedics) are270 `out_of_range_chapter`.271 - Codes not found in the ICD-10 directory are `unknown_code`.2723. Laterality and narrative mismatch: for each referral, compare the ICD-10273 description to the referral's `diagnosis_narrative`.274 - `laterality_mismatch`: the ICD-10 code specifies one side (e.g., left275 medial meniscus tear) but the narrative mentions the opposite side or276 a different joint.277 - `narrative_mismatch`: the narrative describes a condition unrelated to278 the code (e.g., "lumbar radiculopathy" for a knee meniscus tear code).279 - `missing_laterality`: the narrative omits a laterality marker present280 in the code description.281 A referral can carry multiple mismatch types.2824. Duplicate detection: group referrals by `patient_id`. When the same283 patient has multiple referrals in the batch with the same diagnosis code284 or overlapping clinical intent, they form a duplicate group of type285 `same_patient_resubmission`. The tiering policy assigns all rows in the286 group as `tier_1_duplicate_blockers`. Same-patient referrals that are287 genuinely separate clinical reviews (different body parts or conditions)288 go in `separate_same_patient_referral_ids`.2895. Insurance anomalies: when two different patients share the same290 `insurance_id` and both appear in the batch, flag as291 `shared_insurance_different_patients`. This is a verification item, not292 a merge recommendation.2936. Follow-up queues: classify each referral by what it lacks:294 - `authorization_missing`: no authorization record at all.295 - `authorization_pending`: authorization exists but not yet approved.296 - `records_request`: office-note document missing.297 - `imaging_follow_up`: imaging report missing or not final.298 A referral can appear in multiple queues.2997. Action plan tiers:300 - **Tier 1 (immediate)**: duplicate-blocker rows or referrals with both301 coding errors and missing critical documents or authorizations. Assign302 to the batch's primary ortho provider.303 - **Tier 2 (short-term)**: referrals with coding mismatches, missing304 authorizations, or missing documents that are not duplicates. Spread305 across available ortho providers.306 - **Tier 3 (administrative)**: referrals that only need document completion307 with no coding or authorization issues.3088. Summary counts: compute each integer from the arrays populated above. The309 `validated_ready_no_follow_up_count` is the number of referrals with no310 coding issues, no mismatches, complete documents, and approved311 authorization -- the ones that need no action at all.312313## ICD-10 chapter mapping for service lines314315When validating whether a diagnosis code belongs to the right service line,316use this mapping:317318| Service line | Expected ICD-10 chapter |319|---|---|320| `orthopedics` | Musculoskeletal |321| `cardiology` | Circulatory |322| `pulmonology` | Respiratory |323| `neurology` | Nervous System |324| `oncology` | Neoplasms |325326The ICD-10 endpoint's `chapter` field gives the actual chapter for a code.327Compare it against the expected chapter above. A mismatch means the code328is out of range for that service line.329330## Document selection policy331332Not every document belongs in a packet. When a packet needs document333evidence, include only documents that:334335- relate to identity matching or external continuity (for merge packets),336- are clinically required for the referral or transition (echo for337 cardiology, office note for any referral, imaging for orthopedics),338- have status `final` (preliminary or cancelled documents are not339 ready evidence).340341Exclude: chart summaries, generic administrative documents, and documents342whose type is listed in `excluded_document_types` by the template.343344## General troubleshooting345346- **Missing patient data**: If a patient endpoint returns fewer records than347 expected, do not fabricate. The answer reflects only what the API returns.348- **Null fields**: When an optional field has no value in the API evidence,349 emit `null` only if the template explicitly types the field as350 `["string", "null"]` or similar. Otherwise omit or use an empty array.351- **Ambiguous identities**: When duplicate-candidate signals are mixed (some352 match, some conflict), lean toward `needs_review` / `review_hold`. Cite353 the specific conflict signals that prevent a clean merge.354- **Enum not found**: If the evidence doesn't cleanly fit any allowed enum355 value, re-read the evidence more carefully -- the design intent is that356 exactly one value applies. Do not invent new values.