Clinic Decision Support
A solver for producing structured clinical decision-support results from a
synthetic clinic FHIR-like REST API. The API models a small outpatient clinic
with patients, cases, observations, imaging, medications, allergies, problems,
social determinants, care-registry entries, and protocols.
Task structure
Every task provides:
- A prompt naming a target case ID (e.g.
CASE-RESP-140) and a task type.
The prompt references <TASK_ENV_BASE_URL>, which is the root URL of the
clinic API runtime.
- An answer template (
answer_template.json) that defines the exact JSON
shape to return: required top-level keys, allowed enum values, numeric
precision, nullability, and ordering rules. The answer MUST match this
template exactly.
Read both files before making any API calls. The template tells you exactly
what the evaluator expects; every field constraint in it is a scoring rule.
Core workflow
1. Read the prompt and the answer template
Load input/payloads/answer_template.json (or wherever the prompt points you).
Note every required key, every enum constraint, every precision rule.
The prompt always names a case ID. Copy it into the output under case_id
exactly as given.
2. Orient through the API
Start with a single call to the case detail endpoint to discover what data is
attached and to find the patient ID:
GET {base}/api/cases/{case_id}
This often returns the richest payload: a nested object with case, findings
(flat key-value clinical facts), inline observations, imaging, patient
summary, allergies, medications, problems, and sdoh. Read it thoroughly
before drilling into other endpoints.
3. Pull supporting data
After reading the case detail, pull additional data from these endpoints as
needed by the template:
| Endpoint |
When to use |
GET /api/patients/{patient_id} |
When you need the full patient record with medications, problems, allergies, and sdoh merged into one response. Often redundant with the case detail, but sometimes carries extra fields. |
GET /api/observations?patient_id=X or ?case_id=X |
When the template requires observations not included inline in the case detail, or when you need to filter by code/date/status. |
GET /api/imaging?patient_id=X |
When imaging records are needed and not inline in the case detail. |
GET /api/medications?patient_id=X |
For a complete active medication list. |
GET /api/allergies?patient_id=X |
For the active allergy list. |
GET /api/problems?patient_id=X |
For active problem-list conditions. |
GET /api/sdoh?patient_id=X |
For social-determinant domains (transportation, financial, food, housing). |
GET /api/care-registry?patient_id=X |
For risk scores, dialysis schedules, chronic-condition counts, recent admissions. |
GET /api/protocols |
To list available protocols. |
GET /api/protocols/{protocol_id} |
To read the decision rules, thresholds, controlled codes, and constraints for a protocol. |
Do not wait for permission between calls; pull everything you need in parallel
where possible.
4. Read the relevant protocol
The case detail's case_type field or the prompt itself usually signals which
protocol applies. Fetch it and read its body carefully. Protocols carry:
- Authoritative statuses (e.g., only
"final" observations count).
- Controlled codes mapping template entries (like
CXR-2V, K, CBC_BASIC)
to LOINC or local codes used in observations.
- Thresholds and decision rules (oxygen saturation, potassium levels, risk
scores, symptom lists).
- Follow-up timing, return precautions, restriction lists.
- Exclusion rules (e.g., excluded observation statuses, urgent-branch
triggers).
Apply these rules directly to the data you gathered. Do not guess thresholds;
read them from the protocol.
5. Collect evidence IDs
The template always expects an evidence_ids array. Collect stable identifiers
from the API responses:
- The case ID itself (always include first).
- Observation IDs for key lab/vital/imaging results used in the decision.
- Imaging IDs when imaging was reviewed.
- In care-management tasks, include care-registry and observation IDs.
Use the exact observation_id, imaging_id, or case_id values from the API
responses. Do not invent identifiers.
6. Fill the template precisely
Work key by key through the template. For every field:
- Enums: Use only values listed in
allowed_values. Copy them exactly,
including underscores and casing. If the protocol implies a value not in the
allowed list, re-read the template — the allowed values are the complete
universe the evaluator accepts.
- Numbers: Match the precision in the template (e.g.,
"one decimal place"
means 3.2, not 3.20 or 3). Follow round_to_nearest rules from
protocols when computing doses.
- Nulls: Only use
null when the template explicitly permits it (a field
with "type": ["integer", "null"] or "type": "string_or_null"). When a
medication or dose is not applicable, use null only if the template allows
it; otherwise use a placeholder like "not_recommended" when that is an
allowed enum.
- Lists: Respect set semantics when noted (order does not matter), but sort
chronologically when the template says to (e.g., matched observation IDs
ascending by effective_time).
- Booleans: Use JSON
true/false, never strings.
- Timestamps: Use ISO-8601 with trailing
Z and seconds precision
(2026-01-14T10:00:00Z). A from/to window is inclusive start, exclusive
end unless the template says otherwise.
7. Return only the JSON object
Do not wrap the output in markdown fences, do not add commentary, do not
include extra top-level keys. The evaluator parses the raw response. If the
template says "output_rule": "Return exactly one JSON object...", follow it.
Task-type specifics
Observation-window retrieval
When the template has window, lab_found, matched_observation_ids, and
excluded_observation_ids:
- Read the template for the window bounds (
from/to) and the target code
(always "K" for serum potassium in this system).
- Pull observations for the patient. Filter by:
code matching the target code.
status equal to "final". Exclude preliminary, canceled,
entered-in-error.
effective_time inside the window (inclusive start, exclusive end).
patient_id matching the target patient.
- Sort matched observations by
effective_time ascending, then by
observation_id ascending.
- Identify the latest final (the last one in the sorted list) for the
latest_final field.
- Collect excluded observations: any that share the target code or patient
but fail because of date, status, or a different code. Sort excluded IDs
by
effective_time then observation_id.
- Determine the
protocol_gate from the latest final's value against protocol
thresholds. The protocol OBS-WINDOW-2026 defines observation-window rules;
the potassium protocol K-REPLETION-2026 defines potassium thresholds.
Potassium replacement
When the template includes latest_potassium, replacement_required, and
medication_order:
- Find the latest final serum potassium observation (code
"K") for the
patient, regardless of window. Use this for latest_potassium.
- Check the urgent branch first: potassium below 3.0 mmol/L, dialysis-
dependent ESRD, ECG abnormality, or arrhythmia symptoms trigger urgent
escalation. Do not compute a routine oral dose if any urgent trigger fires.
- If the urgent branch does not apply and potassium is below the target (3.5
mmol/L), compute the oral dose: 10 mEq per 0.1 mmol/L below target, rounded
to the nearest 10 mEq. Example: K = 3.1 → deficit = 0.4 mmol/L → 40 mEq.
- Check contraindications: eGFR, dialysis status, arrhythmia symptoms. If a
contraindication applies, set
potassium_plan to hold_due_to_contraindication
or urgent_escalation as appropriate.
- Set the follow-up lab to the next morning (protocol says "next morning final
serum potassium"). Use LOINC
2823-3 and schedule the timestamp for the
morning of the day after current_time.
Care-management routing
When the template includes risk_tier, program, priority_problems,
numeric_anchors, and source_provenance:
- Pull the care-registry for the patient:
risk_score, chronic_condition_count,
dialysis_schedule, recent_admission_date, medication_count.
- Pull problems, medications, and sdoh.
- Apply protocol
CM-HIGH-RISK-2026 thresholds:
risk_tier: "high" when risk_score ≥ 0.75 with supporting triggers;
"moderate" otherwise if risk_score ≥ 0.5; "low" below that.
program: "complex_care_management" when risk_score ≥ 0.75 AND
supporting triggers are met (chronic conditions ≥ 3, recent admission,
dialysis/advanced CKD, heart failure, uncontrolled diabetes).
- Map problems to
priority_problems enum values. Map sdoh domains to
referrals (transportation → transportation_benefits, financial/food →
social_worker, ≥ 2 moderate-or-severe sdoh domains → social_worker).
- Build
source_provenance.chart_facts from what came from structured API
data (risk score, labs, vitals). Build member_disclosure_needed from
facts the patient reported (barriers, fatigue, preferences) that are not
in the structured chart data.
- Set
care_plan_minima based on protocol: 3 problems minimum, weekly follow-
up required, member-stated priority required, at least 2 disciplines.
outreach_stance: use "permission_based_plain_language" when sdoh data
shows the member is reluctant or when barriers suggest sensitivity.
Common pitfalls
- Not reading the case detail first.
/api/cases/{case_id} returns findings
(flat key-value clinical facts) that are often the fastest path to clinical
context. Skipping it means extra API calls for the same data.
- Using preliminary or canceled observations. Protocols only accept
status: "final". Always filter out preliminary, canceled, and
entered-in-error observations.
- Active vs. inactive allergies. Only active allergies constrain medication
choices. Check the
status field.
- Computing potassium dose without checking the urgent branch. Always
evaluate the urgent branch before computing a routine oral dose.
- Wrong timestamp format. Use ISO-8601 with trailing
Z and seconds.
2026-04-07T14:30:00Z, not 2026-04-07T14:30Z or 2026-04-07 14:30:00.
- Extra keys or commentary in output. The evaluator parses the JSON object
directly. Any extra text, markdown fences, or additional keys cause failures.
- Misreading the answer template's allowed values. An enum field only
accepts the exact strings listed. If the protocol says "moderate risk" but
the template allows
"moderate", use the template's value.
- Not using the protocol's controlled codes. The protocol maps template
entries to actual observation codes.
CBC_BASIC may not appear directly in
observations; the protocol tells you how to locate it.
API reference
All endpoints are read-only unless noted. Query parameters use standard
?key=value syntax.
| Method |
Path |
Description |
| GET |
/api/cases |
List all cases (paginated, with count and items) |
| GET |
/api/cases/{case_id} |
Single case with nested findings, observations, imaging, allergies, etc. |
| GET |
/api/patients |
List all patients |
| GET |
/api/patients/{patient_id} |
Single patient with nested medications, allergies, problems, sdoh |
| GET |
/api/observations |
List observations; filter with ?patient_id= or ?case_id= |
| GET |
/api/medications |
List medications; filter with ?patient_id= |
| GET |
/api/allergies |
List allergies; filter with ?patient_id= |
| GET |
/api/problems |
List problems; filter with ?patient_id= |
| GET |
/api/imaging |
List imaging studies; filter with ?patient_id= |
| GET |
/api/care-registry |
List registry entries; filter with ?patient_id= |
| GET |
/api/sdoh |
List social-determinant observations; filter with ?patient_id= |
| GET |
/api/protocols |
List available protocols |
| GET |
/api/protocols/{protocol_id} |
Single protocol with decision rules and thresholds |
| POST |
/api/query |
Authenticated query endpoint (requires a token; not used in standard tasks) |
List endpoints return { "count": N, "items": [...] } with limit and
offset. Single-resource endpoints return a flat object.
The case detail endpoint (/api/cases/{case_id}) includes findings: an array
of { "finding_key", "finding_value", "source_id" } objects that encode
clinical context. These are often the most efficient way to get symptom
presence/absence, encounter time, and allergy constraints.
Protocols include authoritative_statuses (always ["final"]),
controlled_codes mapping template labels to observation codes, threshold
values, and decision rules. Read the protocol body carefully before making
clinical determinations.
1---2name: clinic-decision-support-73description: >4 Use when the user needs to produce a structured, protocol-driven clinical5 decision-support result from a synthetic clinic FHIR-like REST API. This6 includes respiratory assessments, pediatric head-injury triage, potassium7 replacement orders, care-management routing, observation-window retrieval,8 and any similar workflow where a case ID and a strict JSON answer template9 are provided. Trigger on phrases such as "clinical decision support",10 "protocol assessment", "clinic case", "synthetic clinic", "answer template",11 "structured JSON response", "FHIR", or mentions of clinic case IDs and12 runtime environments.13metadata:14 source: https://skillmd.com/skills/prism-shadow/clinic-decision-support-715---1617# Clinic Decision Support1819A solver for producing structured clinical decision-support results from a20synthetic clinic FHIR-like REST API. The API models a small outpatient clinic21with patients, cases, observations, imaging, medications, allergies, problems,22social determinants, care-registry entries, and protocols.2324## Task structure2526Every task provides:2728- A **prompt** naming a target case ID (e.g. `CASE-RESP-140`) and a task type.29 The prompt references `<TASK_ENV_BASE_URL>`, which is the root URL of the30 clinic API runtime.31- An **answer template** (`answer_template.json`) that defines the exact JSON32 shape to return: required top-level keys, allowed enum values, numeric33 precision, nullability, and ordering rules. The answer MUST match this34 template exactly.3536Read both files before making any API calls. The template tells you exactly37what the evaluator expects; every field constraint in it is a scoring rule.3839## Core workflow4041### 1. Read the prompt and the answer template4243Load `input/payloads/answer_template.json` (or wherever the prompt points you).44Note every required key, every enum constraint, every precision rule.4546The prompt always names a **case ID**. Copy it into the output under `case_id`47exactly as given.4849### 2. Orient through the API5051Start with a single call to the case detail endpoint to discover what data is52attached and to find the patient ID:5354```55GET {base}/api/cases/{case_id}56```5758This often returns the richest payload: a nested object with `case`, `findings`59(flat key-value clinical facts), inline `observations`, `imaging`, `patient`60summary, `allergies`, `medications`, `problems`, and `sdoh`. Read it thoroughly61before drilling into other endpoints.6263### 3. Pull supporting data6465After reading the case detail, pull additional data from these endpoints as66needed by the template:6768| Endpoint | When to use |69|---|---|70| `GET /api/patients/{patient_id}` | When you need the full patient record with medications, problems, allergies, and sdoh merged into one response. Often redundant with the case detail, but sometimes carries extra fields. |71| `GET /api/observations?patient_id=X` or `?case_id=X` | When the template requires observations not included inline in the case detail, or when you need to filter by code/date/status. |72| `GET /api/imaging?patient_id=X` | When imaging records are needed and not inline in the case detail. |73| `GET /api/medications?patient_id=X` | For a complete active medication list. |74| `GET /api/allergies?patient_id=X` | For the active allergy list. |75| `GET /api/problems?patient_id=X` | For active problem-list conditions. |76| `GET /api/sdoh?patient_id=X` | For social-determinant domains (transportation, financial, food, housing). |77| `GET /api/care-registry?patient_id=X` | For risk scores, dialysis schedules, chronic-condition counts, recent admissions. |78| `GET /api/protocols` | To list available protocols. |79| `GET /api/protocols/{protocol_id}` | To read the decision rules, thresholds, controlled codes, and constraints for a protocol. |8081Do not wait for permission between calls; pull everything you need in parallel82where possible.8384### 4. Read the relevant protocol8586The case detail's `case_type` field or the prompt itself usually signals which87protocol applies. Fetch it and read its `body` carefully. Protocols carry:8889- **Authoritative statuses** (e.g., only `"final"` observations count).90- **Controlled codes** mapping template entries (like `CXR-2V`, `K`, `CBC_BASIC`)91 to LOINC or local codes used in observations.92- **Thresholds** and decision rules (oxygen saturation, potassium levels, risk93 scores, symptom lists).94- **Follow-up timing**, return precautions, restriction lists.95- **Exclusion rules** (e.g., excluded observation statuses, urgent-branch96 triggers).9798Apply these rules directly to the data you gathered. Do not guess thresholds;99read them from the protocol.100101### 5. Collect evidence IDs102103The template always expects an `evidence_ids` array. Collect stable identifiers104from the API responses:105106- The case ID itself (always include first).107- Observation IDs for key lab/vital/imaging results used in the decision.108- Imaging IDs when imaging was reviewed.109- In care-management tasks, include care-registry and observation IDs.110111Use the exact `observation_id`, `imaging_id`, or `case_id` values from the API112responses. Do not invent identifiers.113114### 6. Fill the template precisely115116Work key by key through the template. For every field:117118- **Enums**: Use only values listed in `allowed_values`. Copy them exactly,119 including underscores and casing. If the protocol implies a value not in the120 allowed list, re-read the template — the allowed values are the complete121 universe the evaluator accepts.122- **Numbers**: Match the precision in the template (e.g., `"one decimal place"`123 means `3.2`, not `3.20` or `3`). Follow `round_to_nearest` rules from124 protocols when computing doses.125- **Nulls**: Only use `null` when the template explicitly permits it (a field126 with `"type": ["integer", "null"]` or `"type": "string_or_null"`). When a127 medication or dose is not applicable, use `null` only if the template allows128 it; otherwise use a placeholder like `"not_recommended"` when that is an129 allowed enum.130- **Lists**: Respect set semantics when noted (order does not matter), but sort131 chronologically when the template says to (e.g., matched observation IDs132 ascending by effective_time).133- **Booleans**: Use JSON `true`/`false`, never strings.134- **Timestamps**: Use ISO-8601 with trailing `Z` and seconds precision135 (`2026-01-14T10:00:00Z`). A `from`/`to` window is inclusive start, exclusive136 end unless the template says otherwise.137138### 7. Return only the JSON object139140Do not wrap the output in markdown fences, do not add commentary, do not141include extra top-level keys. The evaluator parses the raw response. If the142template says `"output_rule": "Return exactly one JSON object..."`, follow it.143144## Task-type specifics145146### Observation-window retrieval147148When the template has `window`, `lab_found`, `matched_observation_ids`, and149`excluded_observation_ids`:1501511. Read the template for the window bounds (`from`/`to`) and the target code152 (always `"K"` for serum potassium in this system).1532. Pull observations for the patient. Filter by:154 - `code` matching the target code.155 - `status` equal to `"final"`. Exclude `preliminary`, `canceled`,156 `entered-in-error`.157 - `effective_time` inside the window (inclusive start, exclusive end).158 - `patient_id` matching the target patient.1593. Sort matched observations by `effective_time` ascending, then by160 `observation_id` ascending.1614. Identify the **latest final** (the last one in the sorted list) for the162 `latest_final` field.1635. Collect excluded observations: any that share the target code or patient164 but fail because of date, status, or a different code. Sort excluded IDs165 by `effective_time` then `observation_id`.1666. Determine the `protocol_gate` from the latest final's value against protocol167 thresholds. The protocol `OBS-WINDOW-2026` defines observation-window rules;168 the potassium protocol `K-REPLETION-2026` defines potassium thresholds.169170### Potassium replacement171172When the template includes `latest_potassium`, `replacement_required`, and173`medication_order`:1741751. Find the latest final serum potassium observation (code `"K"`) for the176 patient, regardless of window. Use this for `latest_potassium`.1772. Check the **urgent branch first**: potassium below 3.0 mmol/L, dialysis-178 dependent ESRD, ECG abnormality, or arrhythmia symptoms trigger urgent179 escalation. Do not compute a routine oral dose if any urgent trigger fires.1803. If the urgent branch does not apply and potassium is below the target (3.5181 mmol/L), compute the oral dose: 10 mEq per 0.1 mmol/L below target, rounded182 to the nearest 10 mEq. Example: K = 3.1 → deficit = 0.4 mmol/L → 40 mEq.1834. Check contraindications: eGFR, dialysis status, arrhythmia symptoms. If a184 contraindication applies, set `potassium_plan` to `hold_due_to_contraindication`185 or `urgent_escalation` as appropriate.1865. Set the follow-up lab to the next morning (protocol says "next morning final187 serum potassium"). Use LOINC `2823-3` and schedule the timestamp for the188 morning of the day after `current_time`.189190### Care-management routing191192When the template includes `risk_tier`, `program`, `priority_problems`,193`numeric_anchors`, and `source_provenance`:1941951. Pull the care-registry for the patient: `risk_score`, `chronic_condition_count`,196 `dialysis_schedule`, `recent_admission_date`, `medication_count`.1972. Pull problems, medications, and sdoh.1983. Apply protocol `CM-HIGH-RISK-2026` thresholds:199 - `risk_tier`: `"high"` when risk_score ≥ 0.75 with supporting triggers;200 `"moderate"` otherwise if risk_score ≥ 0.5; `"low"` below that.201 - `program`: `"complex_care_management"` when risk_score ≥ 0.75 AND202 supporting triggers are met (chronic conditions ≥ 3, recent admission,203 dialysis/advanced CKD, heart failure, uncontrolled diabetes).2044. Map problems to `priority_problems` enum values. Map sdoh domains to205 `referrals` (transportation → `transportation_benefits`, financial/food →206 `social_worker`, ≥ 2 moderate-or-severe sdoh domains → `social_worker`).2075. Build `source_provenance.chart_facts` from what came from structured API208 data (risk score, labs, vitals). Build `member_disclosure_needed` from209 facts the patient reported (barriers, fatigue, preferences) that are not210 in the structured chart data.2116. Set `care_plan_minima` based on protocol: 3 problems minimum, weekly follow-212 up required, member-stated priority required, at least 2 disciplines.2137. `outreach_stance`: use `"permission_based_plain_language"` when sdoh data214 shows the member is reluctant or when barriers suggest sensitivity.215216## Common pitfalls217218- **Not reading the case detail first.** `/api/cases/{case_id}` returns findings219 (flat key-value clinical facts) that are often the fastest path to clinical220 context. Skipping it means extra API calls for the same data.221- **Using preliminary or canceled observations.** Protocols only accept222 `status: "final"`. Always filter out `preliminary`, `canceled`, and223 `entered-in-error` observations.224- **Active vs. inactive allergies.** Only active allergies constrain medication225 choices. Check the `status` field.226- **Computing potassium dose without checking the urgent branch.** Always227 evaluate the urgent branch before computing a routine oral dose.228- **Wrong timestamp format.** Use ISO-8601 with trailing `Z` and seconds.229 `2026-04-07T14:30:00Z`, not `2026-04-07T14:30Z` or `2026-04-07 14:30:00`.230- **Extra keys or commentary in output.** The evaluator parses the JSON object231 directly. Any extra text, markdown fences, or additional keys cause failures.232- **Misreading the answer template's allowed values.** An enum field only233 accepts the exact strings listed. If the protocol says "moderate risk" but234 the template allows `"moderate"`, use the template's value.235- **Not using the protocol's controlled codes.** The protocol maps template236 entries to actual observation codes. `CBC_BASIC` may not appear directly in237 observations; the protocol tells you how to locate it.238239## API reference240241All endpoints are read-only unless noted. Query parameters use standard242`?key=value` syntax.243244| Method | Path | Description |245|--------|------|-------------|246| GET | `/api/cases` | List all cases (paginated, with `count` and `items`) |247| GET | `/api/cases/{case_id}` | Single case with nested findings, observations, imaging, allergies, etc. |248| GET | `/api/patients` | List all patients |249| GET | `/api/patients/{patient_id}` | Single patient with nested medications, allergies, problems, sdoh |250| GET | `/api/observations` | List observations; filter with `?patient_id=` or `?case_id=` |251| GET | `/api/medications` | List medications; filter with `?patient_id=` |252| GET | `/api/allergies` | List allergies; filter with `?patient_id=` |253| GET | `/api/problems` | List problems; filter with `?patient_id=` |254| GET | `/api/imaging` | List imaging studies; filter with `?patient_id=` |255| GET | `/api/care-registry` | List registry entries; filter with `?patient_id=` |256| GET | `/api/sdoh` | List social-determinant observations; filter with `?patient_id=` |257| GET | `/api/protocols` | List available protocols |258| GET | `/api/protocols/{protocol_id}` | Single protocol with decision rules and thresholds |259| POST | `/api/query` | Authenticated query endpoint (requires a token; not used in standard tasks) |260261List endpoints return `{ "count": N, "items": [...] }` with `limit` and262`offset`. Single-resource endpoints return a flat object.263264The case detail endpoint (`/api/cases/{case_id}`) includes `findings`: an array265of `{ "finding_key", "finding_value", "source_id" }` objects that encode266clinical context. These are often the most efficient way to get symptom267presence/absence, encounter time, and allergy constraints.268269Protocols include `authoritative_statuses` (always `["final"]`),270`controlled_codes` mapping template labels to observation codes, threshold271values, and decision rules. Read the protocol body carefully before making272clinical determinations.