Intake Coordination Skill
This skill teaches a systematic workflow for solving healthcare intake coordination tasks that use a shared REST API portal. The tasks involve gathering data across patients, referrals, transfers, documents, charts, programs, ICD codes, and pharmacies, then applying classification rules and assembling a controlled-vocabulary JSON response per an answer template.
Workflow
Phase 1 — Discover the API shape
- Call
GET / and GET /health at the task environment base URL to confirm the portal is reachable and to discover any root-level metadata.
- The portal serves these standard endpoints. Every task will use a subset:
GET /patients — list all patients
GET /patients/{patient_id} — single patient detail
GET /referrals — list all referrals
GET /referrals/{referral_id} — single referral detail
GET /transfers — list all transfers
GET /transfers/{transfer_id} — single transfer detail
GET /documents — list all documents
GET /chart/{patient_id} — patient chart record
GET /programs/{program_code}/candidates — program enrollment candidates
GET /icd/{code} — ICD-10 code metadata including chapter
GET /pharmacies — in-network pharmacy directory
POST /query — SQL-like query endpoint for cross-referencing
Phase 2 — Read the answer template
Every task includes an answer_template.json (or similarly-named payload file) that defines:
- The exact JSON shape required (top-level keys, nested structures).
- Controlled-vocabulary enum values for every classification field. Use only these values.
- Sort ordering rules (typically ascending by ID for lists, unordered-set semantics for reason-code arrays).
- Which fields are required vs. nullable.
- Special validation notes like "uppercase IDs exactly as shown by the portal."
Read the template thoroughly before gathering any data. The template is the contract; the answer must conform to it.
Phase 3 — Gather the domain data
Based on the task domain (patients, referrals, transfers, or programs), parallel-fetch the relevant endpoints:
For patient intake tasks:
- Fetch the roster or target list from payload files.
GET /patients or GET /patients/{id} for each target patient.
GET /chart/{patient_id} for clinical data (risks, vitals, labs, problems, diagnoses, medications).
GET /pharmacies for pharmacy network data.
GET /documents filtered to relevant patients for document/benefit records.
GET /icd/{code} for any ICD codes referenced.
For referral audit tasks:
GET /referrals (or filter by batch if the API supports it).
GET /patients/{id} for each patient linked to a referral.
GET /documents to find records and imaging attached to referrals.
GET /icd/{code} for each ICD code on each referral.
- Cross-reference referral insurance IDs across patients; same insurance ID on different patients is an anomaly.
For transfer review tasks:
GET /transfers filtered to the batch.
GET /transfers/{transfer_id} for detail (packet documents, requested start date).
GET /documents for document freshness checks.
GET /patients/{id} and GET /chart/{id} for clinical context.
For program enrollment tasks:
GET /programs/{program_code}/candidates for the candidate list.
GET /chart/{patient_id} for each candidate to check eligibility criteria, consent, chart readiness.
Use POST /query for cross-referencing. The /query endpoint accepts SQL-like syntax and is the preferred way to join records across domains without fetching and filtering manually. Examples of useful queries:
- Find all documents for patients in a specific roster.
- Find referrals that share an insurance ID.
- Find stale documents based on date thresholds.
- Cross-reference pharmacy IDs against the network.
Phase 4 — Classify each item
Apply classification rules consistently. Every value must come from the answer template's allowed enum set.
Insurance status
| Status |
Condition |
valid |
Insurance record present, active, coverage includes the service line |
invalid |
Insurance record present but expired, denied, or service line excluded |
missing |
No insurance record found |
Prescription benefit (PBM) status
| Status |
Condition |
valid |
PBM record present, active, policy matches |
invalid |
PBM record present but invalid, expired, or policy mismatch |
missing |
No PBM record found |
Pharmacy network status
Cross-reference the patient's pharmacy ID against GET /pharmacies. The pharmacy endpoint returns in-network pharmacies.
| Status |
Condition |
in_network |
Pharmacy found in the in-network directory |
out_of_network |
Pharmacy ID present but not in the directory |
unknown |
No pharmacy associated with the patient |
Lifestyle risk
Derived from patient chart indicators: smoking status, BMI, activity level, substance use, and social determinants documented in the chart.
| Level |
Interpretation |
low |
No significant lifestyle risk indicators |
medium |
One or two moderate indicators |
high |
Multiple or severe indicators |
Overall risk
Aggregate of insurance validity, clinical markers from chart, lifestyle risk, PBM status, and pharmacy network status. When any component is at its worst level, overall risk elevates.
| Level |
Interpretation |
low |
All components normal, no clinical flags |
medium |
Some components suboptimal but manageable |
high |
Multiple components compromised or severe clinical flags |
Registration / Readiness status
| Status |
Meaning |
approved / ready |
All checks passed, no blockers |
hold / blocked |
Hard blockers without clinical ambiguity |
clinical_review / under_review |
Issues requiring clinical judgment or clarification |
rejected / admin_followup |
Unresolvable blockers or administrative follow-up needed |
Blocker / Issue / Reason codes
The answer template defines the exact set of allowed codes for each task type. Derive each code from specific evidence:
- Coverage codes (
coverage_expired, coverage_pending, excluded_service_line): From insurance record fields.
- PBM codes (
pbm_invalid, pbm_missing, pbm_policy_mismatch): From PBM/benefit record fields.
- Contact codes (
emergency_contact_missing, preferred_contact_unavailable, missing_address): From patient demographic fields.
- Pharmacy codes (
pharmacy_out_of_network, pharmacy_unknown): From pharmacy cross-reference.
- Risk codes (
overall_risk_high): When overall risk is high.
- ICD codes (
icd_chapter_mismatch, narrative_mismatch, laterality_mismatch): From ICD cross-reference. Use GET /icd/{code} to get the chapter, then compare against the expected specialty chapter.
- Document codes (
missing_records, missing_imaging): From document cross-reference. A referral/transfer with no attached records or imaging.
- Authorization codes (
auth_blocker): From referral authorization field. Statuses: pending, denied, not_submitted.
- Duplicate codes (
duplicate_referral, shared_insurance_anomaly): Same patient has multiple referrals; same insurance ID on different patients.
- Schedule codes (
already_scheduled, scheduled_before_clearance): An appointment exists before the referral was cleared.
- Program codes (
meets_dmhtn_criteria, consent_declined, consent_missing, chart_not_active, stale_active_problems, missing_recent_vitals, missing_recent_labs, missing_medication_list, wrong_target_condition, missing_active_dmhtn_diagnosis, recent_hospitalization_high_touch, low_adherence_high_touch, ckd_biweekly_monitoring, recent_ed_high_touch): From chart and candidate data.
ICD chapter mismatch detection
The /icd/{code} endpoint returns an ICD-10 chapter range (e.g., S00-T88 for injury codes, M00-M99 for musculoskeletal). Orthopedic referrals expect musculoskeletal chapter codes. Pulmonary referrals expect respiratory chapter codes (J00-J99). Primary care expects codes from common outpatient chapters. A code outside the expected chapter for the service line is a icd_chapter_mismatch.
Common ICD-10 chapter ranges:
A00-B99 — Infectious
C00-D49 — Neoplasms
E00-E89 — Endocrine
F01-F99 — Mental
G00-G99 — Nervous
I00-I99 — Circulatory
J00-J99 — Respiratory
K00-K95 — Digestive
M00-M99 — Musculoskeletal
N00-N99 — Genitourinary
R00-R99 — Symptoms
S00-T88 — Injury
Z00-Z99 — Factors influencing health
Document freshness
Documents have received dates and freshness limits. Compare received_date + freshness_limit_days against the task reference date (typically the as-of date or the requested service/start date). If the document is older than its freshness limit relative to the reference date, it is stale.
Common freshness limits observed in the domain:
hbsag — 30 days
monthly_labs — 30 days
ppd_or_cxr — 30 days
history_physical — 365 days
Always read the freshness limit from the document or transfer record; do not hardcode values.
Duplicate detection
- Group referrals/transfers by patient ID. If a patient has more than one referral in the batch, they form a duplicate group.
- Group referrals by insurance ID. If the same insurance ID appears on referrals for different patients, that is a shared insurance anomaly.
- The primary referral in a duplicate group is typically the earliest or lowest-ID one. The recommendation is
consolidate_to_primary unless records show the referrals are for genuinely separate clinical needs (then keep_separate).
Capacity and feasibility
For transfer intake, the portal returns capacity data: chairs open, capacity status (available/unavailable). Feasibility logic:
- Packet complete + capacity available on requested start →
ready_on_requested_start
- Packet incomplete + capacity available →
packet_not_ready_capacity_available
- Packet incomplete + capacity unavailable →
packet_not_ready_capacity_unavailable
- Packet complete + capacity unavailable →
capacity_unavailable
Follow-up cadence
From program enrollment or referral action plans:
| Cadence |
Trigger |
weekly |
High-touch (recent hospitalization, ED visit, low adherence) |
biweekly |
CKD monitoring or moderate risk |
monthly |
Standard stable enrollment |
deferred |
On hold pending chart/consent completion |
none |
Rejected or ineligible |
Outreach channel
Preferred contact method from patient record. If not specified, default based on patient demographics. Portal and email are common for engaged patients; phone for high-risk; SMS for younger demographics.
Priority tiering
| Tier |
Meaning |
tier_1_immediate |
Urgent referrals with clinical discrepancies that affect patient safety or scheduling |
tier_2_short_term |
Routine follow-up needed within days to weeks |
tier_3_administrative |
Administrative issues only, no clinical urgency |
Phase 5 — Assemble the output
- Start with the answer template as the structural skeleton.
- Fill each field with the gathered and classified data.
- Sorting rules: Patient/referral/transfer lists in ascending ID order. Reason-code and blocker-code arrays are unordered sets — list them alphabetically or in the order they were discovered, but do not assign meaning to order.
- Use exact IDs: Referral IDs, patient IDs, insurance IDs, transfer IDs, group IDs must match the portal exactly, preserving case.
- Integer counts: Summary counts must be exact integers that add up correctly. Every count must reconcile: the sum of status counts must equal total items, and cross-tabulation counts must match their constituent lists.
- Null vs. empty:
null only where the template allows it and the data is genuinely absent. Use [] for empty lists, 0 for zero counts.
- Return only the JSON object. No prose, no markdown wrapping, no explanation.
Phase 6 — Verify
Before finalizing, run these checks:
Common pitfalls
- Missing the template's enum values: Never invent a reason code. If a finding doesn't match any allowed value, re-examine the data and the template's definition of each code.
- Sort order violations: When the template says "ascending by referral_id", sort strictly. When it says "unordered set", order does not matter but consistency is good practice.
- Wrong chapter for ICD codes: The portal returns the actual chapter; do not guess from the code prefix. An injury code may map to chapter
S00-T88 even when the treating specialty (e.g., orthopedics) normally works within chapter M00-M99. Always query the portal instead of guessing.
- Including patients not in the target batch: Filter to only the roster/batch IDs specified in the task prompt or payload.
- Summary count errors: Double-check every count. A mismatch between the list length and the summary count is the most common mistake.
- Hardcoding freshness thresholds: Always read the freshness limit from the portal data; limits can vary by document type.
- Overlooking the
/query endpoint: For complex cross-referencing, POST /query is faster and less error-prone than fetching all records and filtering manually.
1---2name: intake-coordinator3description: Solve healthcare intake coordination tasks against a REST API portal. Navigate patient/referral/transfer/chart/program endpoints, cross-reference records, interpret answer templates, apply classification rules, and assemble controlled-vocabulary JSON output.4metadata:5 source: https://skillmd.com/skills/prism-shadow/intake-coordinator6---78# Intake Coordination Skill910This skill teaches a systematic workflow for solving healthcare intake coordination tasks that use a shared REST API portal. The tasks involve gathering data across patients, referrals, transfers, documents, charts, programs, ICD codes, and pharmacies, then applying classification rules and assembling a controlled-vocabulary JSON response per an answer template.1112## Workflow1314### Phase 1 — Discover the API shape15161. Call `GET /` and `GET /health` at the task environment base URL to confirm the portal is reachable and to discover any root-level metadata.172. The portal serves these standard endpoints. Every task will use a subset:18 - `GET /patients` — list all patients19 - `GET /patients/{patient_id}` — single patient detail20 - `GET /referrals` — list all referrals21 - `GET /referrals/{referral_id}` — single referral detail22 - `GET /transfers` — list all transfers23 - `GET /transfers/{transfer_id}` — single transfer detail24 - `GET /documents` — list all documents25 - `GET /chart/{patient_id}` — patient chart record26 - `GET /programs/{program_code}/candidates` — program enrollment candidates27 - `GET /icd/{code}` — ICD-10 code metadata including chapter28 - `GET /pharmacies` — in-network pharmacy directory29 - `POST /query` — SQL-like query endpoint for cross-referencing3031### Phase 2 — Read the answer template3233Every task includes an `answer_template.json` (or similarly-named payload file) that defines:34- The exact JSON shape required (top-level keys, nested structures).35- Controlled-vocabulary enum values for every classification field. Use **only** these values.36- Sort ordering rules (typically ascending by ID for lists, unordered-set semantics for reason-code arrays).37- Which fields are required vs. nullable.38- Special validation notes like "uppercase IDs exactly as shown by the portal."3940Read the template thoroughly before gathering any data. The template is the contract; the answer must conform to it.4142### Phase 3 — Gather the domain data4344Based on the task domain (patients, referrals, transfers, or programs), parallel-fetch the relevant endpoints:4546**For patient intake tasks:**47- Fetch the roster or target list from payload files.48- `GET /patients` or `GET /patients/{id}` for each target patient.49- `GET /chart/{patient_id}` for clinical data (risks, vitals, labs, problems, diagnoses, medications).50- `GET /pharmacies` for pharmacy network data.51- `GET /documents` filtered to relevant patients for document/benefit records.52- `GET /icd/{code}` for any ICD codes referenced.5354**For referral audit tasks:**55- `GET /referrals` (or filter by batch if the API supports it).56- `GET /patients/{id}` for each patient linked to a referral.57- `GET /documents` to find records and imaging attached to referrals.58- `GET /icd/{code}` for each ICD code on each referral.59- Cross-reference referral insurance IDs across patients; same insurance ID on different patients is an anomaly.6061**For transfer review tasks:**62- `GET /transfers` filtered to the batch.63- `GET /transfers/{transfer_id}` for detail (packet documents, requested start date).64- `GET /documents` for document freshness checks.65- `GET /patients/{id}` and `GET /chart/{id}` for clinical context.6667**For program enrollment tasks:**68- `GET /programs/{program_code}/candidates` for the candidate list.69- `GET /chart/{patient_id}` for each candidate to check eligibility criteria, consent, chart readiness.7071**Use `POST /query` for cross-referencing.** The `/query` endpoint accepts SQL-like syntax and is the preferred way to join records across domains without fetching and filtering manually. Examples of useful queries:72- Find all documents for patients in a specific roster.73- Find referrals that share an insurance ID.74- Find stale documents based on date thresholds.75- Cross-reference pharmacy IDs against the network.7677### Phase 4 — Classify each item7879Apply classification rules consistently. Every value must come from the answer template's allowed enum set.8081#### Insurance status8283| Status | Condition |84|--------|-----------|85| `valid` | Insurance record present, active, coverage includes the service line |86| `invalid` | Insurance record present but expired, denied, or service line excluded |87| `missing` | No insurance record found |8889#### Prescription benefit (PBM) status9091| Status | Condition |92|--------|-----------|93| `valid` | PBM record present, active, policy matches |94| `invalid` | PBM record present but invalid, expired, or policy mismatch |95| `missing` | No PBM record found |9697#### Pharmacy network status9899Cross-reference the patient's pharmacy ID against `GET /pharmacies`. The pharmacy endpoint returns in-network pharmacies.100101| Status | Condition |102|--------|-----------|103| `in_network` | Pharmacy found in the in-network directory |104| `out_of_network` | Pharmacy ID present but not in the directory |105| `unknown` | No pharmacy associated with the patient |106107#### Lifestyle risk108109Derived from patient chart indicators: smoking status, BMI, activity level, substance use, and social determinants documented in the chart.110111| Level | Interpretation |112|-------|---------------|113| `low` | No significant lifestyle risk indicators |114| `medium` | One or two moderate indicators |115| `high` | Multiple or severe indicators |116117#### Overall risk118119Aggregate of insurance validity, clinical markers from chart, lifestyle risk, PBM status, and pharmacy network status. When any component is at its worst level, overall risk elevates.120121| Level | Interpretation |122|-------|---------------|123| `low` | All components normal, no clinical flags |124| `medium` | Some components suboptimal but manageable |125| `high` | Multiple components compromised or severe clinical flags |126127#### Registration / Readiness status128129| Status | Meaning |130|--------|---------|131| `approved` / `ready` | All checks passed, no blockers |132| `hold` / `blocked` | Hard blockers without clinical ambiguity |133| `clinical_review` / `under_review` | Issues requiring clinical judgment or clarification |134| `rejected` / `admin_followup` | Unresolvable blockers or administrative follow-up needed |135136#### Blocker / Issue / Reason codes137138The answer template defines the exact set of allowed codes for each task type. Derive each code from specific evidence:139140- **Coverage codes** (`coverage_expired`, `coverage_pending`, `excluded_service_line`): From insurance record fields.141- **PBM codes** (`pbm_invalid`, `pbm_missing`, `pbm_policy_mismatch`): From PBM/benefit record fields.142- **Contact codes** (`emergency_contact_missing`, `preferred_contact_unavailable`, `missing_address`): From patient demographic fields.143- **Pharmacy codes** (`pharmacy_out_of_network`, `pharmacy_unknown`): From pharmacy cross-reference.144- **Risk codes** (`overall_risk_high`): When overall risk is `high`.145- **ICD codes** (`icd_chapter_mismatch`, `narrative_mismatch`, `laterality_mismatch`): From ICD cross-reference. Use `GET /icd/{code}` to get the chapter, then compare against the expected specialty chapter.146- **Document codes** (`missing_records`, `missing_imaging`): From document cross-reference. A referral/transfer with no attached records or imaging.147- **Authorization codes** (`auth_blocker`): From referral authorization field. Statuses: `pending`, `denied`, `not_submitted`.148- **Duplicate codes** (`duplicate_referral`, `shared_insurance_anomaly`): Same patient has multiple referrals; same insurance ID on different patients.149- **Schedule codes** (`already_scheduled`, `scheduled_before_clearance`): An appointment exists before the referral was cleared.150- **Program codes** (`meets_dmhtn_criteria`, `consent_declined`, `consent_missing`, `chart_not_active`, `stale_active_problems`, `missing_recent_vitals`, `missing_recent_labs`, `missing_medication_list`, `wrong_target_condition`, `missing_active_dmhtn_diagnosis`, `recent_hospitalization_high_touch`, `low_adherence_high_touch`, `ckd_biweekly_monitoring`, `recent_ed_high_touch`): From chart and candidate data.151152#### ICD chapter mismatch detection153154The `/icd/{code}` endpoint returns an ICD-10 chapter range (e.g., `S00-T88` for injury codes, `M00-M99` for musculoskeletal). Orthopedic referrals expect musculoskeletal chapter codes. Pulmonary referrals expect respiratory chapter codes (`J00-J99`). Primary care expects codes from common outpatient chapters. A code outside the expected chapter for the service line is a `icd_chapter_mismatch`.155156Common ICD-10 chapter ranges:157- `A00-B99` — Infectious158- `C00-D49` — Neoplasms159- `E00-E89` — Endocrine160- `F01-F99` — Mental161- `G00-G99` — Nervous162- `I00-I99` — Circulatory163- `J00-J99` — Respiratory164- `K00-K95` — Digestive165- `M00-M99` — Musculoskeletal166- `N00-N99` — Genitourinary167- `R00-R99` — Symptoms168- `S00-T88` — Injury169- `Z00-Z99` — Factors influencing health170171#### Document freshness172173Documents have received dates and freshness limits. Compare `received_date + freshness_limit_days` against the task reference date (typically the as-of date or the requested service/start date). If the document is older than its freshness limit relative to the reference date, it is stale.174175Common freshness limits observed in the domain:176- `hbsag` — 30 days177- `monthly_labs` — 30 days178- `ppd_or_cxr` — 30 days179- `history_physical` — 365 days180181Always read the freshness limit from the document or transfer record; do not hardcode values.182183#### Duplicate detection1841851. Group referrals/transfers by patient ID. If a patient has more than one referral in the batch, they form a duplicate group.1862. Group referrals by insurance ID. If the same insurance ID appears on referrals for different patients, that is a shared insurance anomaly.1873. The primary referral in a duplicate group is typically the earliest or lowest-ID one. The recommendation is `consolidate_to_primary` unless records show the referrals are for genuinely separate clinical needs (then `keep_separate`).188189#### Capacity and feasibility190191For transfer intake, the portal returns capacity data: chairs open, capacity status (`available`/`unavailable`). Feasibility logic:192- Packet complete + capacity available on requested start → `ready_on_requested_start`193- Packet incomplete + capacity available → `packet_not_ready_capacity_available`194- Packet incomplete + capacity unavailable → `packet_not_ready_capacity_unavailable`195- Packet complete + capacity unavailable → `capacity_unavailable`196197#### Follow-up cadence198199From program enrollment or referral action plans:200201| Cadence | Trigger |202|---------|---------|203| `weekly` | High-touch (recent hospitalization, ED visit, low adherence) |204| `biweekly` | CKD monitoring or moderate risk |205| `monthly` | Standard stable enrollment |206| `deferred` | On hold pending chart/consent completion |207| `none` | Rejected or ineligible |208209#### Outreach channel210211Preferred contact method from patient record. If not specified, default based on patient demographics. Portal and email are common for engaged patients; phone for high-risk; SMS for younger demographics.212213#### Priority tiering214215| Tier | Meaning |216|------|---------|217| `tier_1_immediate` | Urgent referrals with clinical discrepancies that affect patient safety or scheduling |218| `tier_2_short_term` | Routine follow-up needed within days to weeks |219| `tier_3_administrative` | Administrative issues only, no clinical urgency |220221### Phase 5 — Assemble the output2222231. Start with the answer template as the structural skeleton.2242. Fill each field with the gathered and classified data.2253. **Sorting rules**: Patient/referral/transfer lists in ascending ID order. Reason-code and blocker-code arrays are unordered sets — list them alphabetically or in the order they were discovered, but do not assign meaning to order.2264. **Use exact IDs**: Referral IDs, patient IDs, insurance IDs, transfer IDs, group IDs must match the portal exactly, preserving case.2275. **Integer counts**: Summary counts must be exact integers that add up correctly. Every count must reconcile: the sum of status counts must equal total items, and cross-tabulation counts must match their constituent lists.2286. **Null vs. empty**: `null` only where the template allows it and the data is genuinely absent. Use `[]` for empty lists, `0` for zero counts.2297. Return only the JSON object. No prose, no markdown wrapping, no explanation.230231### Phase 6 — Verify232233Before finalizing, run these checks:234235- [ ] Every required top-level key from the template is present.236- [ ] Every list is sorted per the template's ordering rule.237- [ ] Every enum value is from the template's allowed set.238- [ ] Summary counts reconcile: sum of status counts equals total items.239- [ ] No patient/referral/transfer from the target batch is missing.240- [ ] No extra patients/referrals/transfers beyond the target batch are included.241- [ ] All IDs match the portal exactly (case, punctuation).242- [ ] JSON is valid (no trailing commas, no unquoted keys).243- [ ] Response is JSON only — no surrounding prose.244245## Common pitfalls2462471. **Missing the template's enum values**: Never invent a reason code. If a finding doesn't match any allowed value, re-examine the data and the template's definition of each code.2482. **Sort order violations**: When the template says "ascending by referral_id", sort strictly. When it says "unordered set", order does not matter but consistency is good practice.2493. **Wrong chapter for ICD codes**: The portal returns the actual chapter; do not guess from the code prefix. An injury code may map to chapter `S00-T88` even when the treating specialty (e.g., orthopedics) normally works within chapter `M00-M99`. Always query the portal instead of guessing.2504. **Including patients not in the target batch**: Filter to only the roster/batch IDs specified in the task prompt or payload.2515. **Summary count errors**: Double-check every count. A mismatch between the list length and the summary count is the most common mistake.2526. **Hardcoding freshness thresholds**: Always read the freshness limit from the portal data; limits can vary by document type.2537. **Overlooking the `/query` endpoint**: For complex cross-referencing, `POST /query` is faster and less error-prone than fetching all records and filtering manually.