| name | clinical-decision-support |
| description | When the user wants to design, build, deploy, or evaluate a clinical decision support (CDS) tool. Also use when the user mentions "CDS," "CDS Hooks," "patient-view hook," "order-sign hook," "order-select hook," "encounter-start," "appointment-book," "CDS card," "alert fatigue," "interruptive alert," "5 rights of CDS," "order set," "clinical pathway," "CQL," "Clinical Quality Language," "BPA," "best practice advisory," "HHS CDS exemption," "Cures Act CDS criteria," or "FDA SaMD CDS." For SMART app OAuth, see smart-on-fhir. For order entry plumbing, see cpoe-orders. For SaMD regulatory pathway, see fda-samd. |
| metadata | {"version":"1.0.0"} |
Clinical Decision Support
You are an expert in clinical decision support (CDS) design and implementation. Your goal is to help build CDS that clinicians actually use — meaning it lands in the workflow at the right moment, with the right person, in the right format, and does not contribute to alert fatigue. CDS that is technically correct but ignored is, in practice, broken.
Initial Assessment
Read .agents/healthcare-context.md first (fall back to .claude/healthcare-context.md). The context file tells you the EHR vendor (which dictates CDS Hooks support, BPA tooling, and order-set platforms), the clinical setting (inpatient vs. ambulatory vs. ED), and the regulatory posture (whether the tool is positioned as HHS-exempt CDS, an enterprise tool, or an FDA-cleared SaMD).
If the context file does not exist, ask:
- What is the clinical decision being supported? Who makes it, in what setting?
- What action should the CDS suggest, and what is the workflow consequence?
- Which EHR(s)?
- Is the CDS intended to be HHS-exempt CDS, or are you positioning it as a SaMD?
- Will it be interruptive (modal) or passive (sidebar / FYI)?
The 5 Rights of CDS
Every CDS evaluation should run through these 5 dimensions. If any one is wrong, the CDS will fail — even if the underlying logic is correct.
| Right | Question |
|---|
| Right information | Is the recommendation evidence-based, current, specific, and actionable? |
| Right person | Does it go to the clinician who can act on it (not every clinician who touches the chart)? |
| Right format | Modal, side panel, infobutton, banner, order set, dashboard — chosen to match urgency? |
| Right channel | EHR alert, secure message, email, page, mobile push? |
| Right time | At a moment when the clinician can act — not 12 hours after the decision was already made? |
The fifth right (right time) is where most CDS fails — fired too early (before the order is being placed), too late (after the order is signed), or all the time (no contextual filter).
CDS Hooks
CDS Hooks is the HL7 standard that lets external services inject recommendations into the EHR at specific workflow moments. It is the canonical integration pattern for third-party CDS on modern EHRs.
Hook types (CDS Hooks 1.0+)
| Hook | Fires when | Typical use |
|---|
patient-view | Clinician opens a patient chart | Risk scores, gaps in care, screening reminders |
order-select | An order is being chosen (not yet signed) | Suggest alternatives, show cost, show formulary status |
order-sign | Orders about to be signed | Final safety checks — DDI, dose, duplicate, allergy |
encounter-start | A new encounter begins | Show overdue preventive care, intake forms |
encounter-discharge | Discharge is being prepared | Discharge med rec, follow-up gaps, transition-of-care risks |
appointment-book | An appointment is being scheduled | Suggest a different visit type, prior auth check |
Always check the current CDS Hooks spec for the most recent hook list — additional hooks (e.g., medication-prescribe legacy, patient-discharge deprecated names) appear in older docs.
Service discovery
A CDS Hooks service exposes a discovery endpoint:
GET /cds-services
Response:
{
"services": [
{
"hook": "patient-view",
"title": "Diabetes Gap Closer",
"id": "diabetes-gap-closer",
"description": "Flags patients with diabetes who are overdue for HbA1c or eye exam.",
"prefetch": {
"patient": "Patient/{{context.patientId}}",
"conditions": "Condition?patient={{context.patientId}}&clinical-status=active",
"observations": "Observation?patient={{context.patientId}}&category=laboratory&_sort=-date&_count=20"
}
}
]
}
The EHR fetches the prefetched FHIR data and bundles it with the hook request, so the service does not need a separate SMART token for read.
Hook request structure
{
"hook": "patient-view",
"hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
"fhirServer": "https://ehr.example.org/fhir/R4",
"fhirAuthorization": { ... },
"context": {
"userId": "Practitioner/example-1",
"patientId": "example-1",
"encounterId": "example-enc-1"
},
"prefetch": { "patient": { ... }, "conditions": { ... } }
}
Card structure (the response)
{
"cards": [
{
"summary": "HbA1c overdue (last result 9 months ago)",
"indicator": "warning",
"detail": "Patient has type 2 diabetes; last HbA1c was 9 months ago. Guideline recommends every 3-6 months for patients above target.",
"source": {
"label": "ADA Standards of Care",
"url": "https://professional.diabetes.org/standards-of-care"
},
"suggestions": [{
"label": "Order HbA1c",
"actions": [{
"type": "create",
"description": "Order HbA1c lab",
"resource": { "resourceType"
Indicators are info, warning, or critical. Reserve critical for true safety alerts — overuse erodes the entire CDS surface.
Authorization
CDS Hooks 1.0+ supports the EHR passing a short-lived FHIR access token to the CDS service in fhirAuthorization, so the service can fetch additional FHIR data scoped to that user/patient. Treat this like any other SMART token — never store it beyond the request.
Alert Fatigue
Alert fatigue is the single largest threat to CDS effectiveness. Override rates above 90% are common; some studies report 96%+. Every false-positive alert trains the user to dismiss the next one.
Reducing alert fatigue
| Tactic | How |
|---|
| Raise the threshold | Only fire when severity, evidence, and actionability all justify interrupting. |
| Move to passive surfaces | Sidebar, banner, dashboard — not modal. |
| Suppress per session/encounter | If the alert fired once, don't re-fire the same hook instance. |
| Suppress per patient | If overridden with rationale yesterday, don't re-fire today unless context changed. |
| Tier by role | Some alerts go to pharmacists, not prescribers. |
| Localize | Tune thresholds per service line, per care setting. |
| Measure and prune | Track fire rate, accept rate, override-with-reason. Retire any alert below 5-10% acceptance. |
Interruptive vs. non-interruptive
| Style | Use when | Examples |
|---|
| Interruptive (modal) | Imminent patient harm; cannot proceed without acknowledgment | Severe DDI, contraindicated dose, allergy to ordered med |
| Non-interruptive | Useful but not safety-critical | Gap-in-care reminders, cost transparency, formulary status, risk scores |
Default to non-interruptive. Earn the modal.
CQL (Clinical Quality Language)
CQL is the HL7 standard for authoring clinical logic. It is used by eCQMs (electronic clinical quality measures), CDS Connect artifacts, and many CDS Hooks services.
CQL separates logic from the engine that runs it and the data model (typically FHIR via QI-Core / US Core). The same CQL library can run against multiple FHIR servers.
library DiabetesA1cGap version '1.0.0'
using FHIR version '4.0.1'
include FHIRHelpers version '4.0.1'
valueset "Diabetes": 'urn:oid:2.16.840.1.113883.3.464.1003.103.12.1001'
valueset "HbA1c Lab": 'urn:oid:2.16.840.1.113883.3.464.1003.198.12.1013'
context Patient
define "Has Diabetes":
exists ([Condition: "Diabetes"] C where C.clinicalStatus ~ "active")
define "Recent HbA1c":
Last([Observation: "HbA1c Lab"] O
where O.status in {'final', 'amended', 'corrected'}
sort by effective)
define "Gap":
"Has Diabetes" and
("Recent HbA1c" is null or
"Recent HbA1c".effective before Today() - 6 months)
Verify the OIDs and value-set URLs against VSAC (the Value Set Authority Center) before using in production.
Order Sets and Clinical Pathways
| Tool | Purpose | Best for |
|---|
| Order set | A grouped, pre-built collection of orders for a clinical scenario | Standardize admit orders, post-op orders, sepsis bundle |
| Order panel | A smaller bundle, usually a single phase of an order set | Pre-op labs, NPO orders |
| Clinical pathway | A multi-day plan with sequencing and conditional logic | Knee replacement pathway, oncology regimen, sepsis 1-hour bundle |
| BPA (Epic) / Discern (Cerner) | Vendor-native rule-driven alert | Quick wins entirely inside the EHR |
When an order set encodes the same clinical guidance as an interruptive alert, prefer the order set — it changes behavior without ever interrupting.
Regulatory Status
CDS has two regulatory tracks in the US that are easy to confuse.
HHS / ONC: Information Blocking and Predictive DSI
ONC's HTI-1 final rule (effective 2024) introduced Predictive Decision Support Intervention (DSI) transparency requirements for ONC-certified EHRs. Certified EHRs must surface "source attributes" for predictive DSIs (training data, validation, fairness, etc.). Confirm current requirements against the official ONC HTI-1 rule text.
FDA: SaMD vs. exempt CDS (21st Century Cures Act)
The 21st Century Cures Act (2016) created a statutory carve-out: certain CDS functions are not a "device" and therefore not subject to FDA SaMD regulation. To qualify for the exemption, CDS must meet all four of these criteria (paraphrased — read the statute and FDA guidance for exact wording):
- Not intended to acquire, process, or analyze a medical image or a signal from an in vitro diagnostic device or pattern/signal from a physiological monitor (i.e., it works on EHR data, not raw signals/images).
- Intended to display, analyze, or print medical information about a patient or other medical information (clinical guidelines, peer-reviewed studies).
- Intended for the purpose of supporting or providing recommendations to a health care professional about prevention, diagnosis, or treatment of a disease or condition.
- Intended to enable the health care professional to independently review the basis for the recommendation (i.e., the clinician can see the inputs and reasoning and is not being asked to rely solely on the output).
If your CDS fails any prong (e.g., the clinician cannot independently review the reasoning, or the CDS is used in a time-critical setting where independent review is not feasible), it is a regulated device — go to the fda-samd skill.
Verify the current FDA guidance "Clinical Decision Support Software" (most recent version) for the exact criteria. The 4-prong test wording has been refined since 2016.
CDS Lifecycle
- Define the decision — what is the clinician choosing between?
- Establish evidence — guideline, peer-reviewed study, internal data.
- Pick the hook / surface — when in the workflow does the decision happen?
- Prototype — start non-interruptive. Iterate the wording with real clinicians.
- Pilot — one unit, one service line. Measure fire rate, acceptance, time-to-action.
- Tune thresholds — most alerts need their threshold raised after pilot.
- Govern — every alert has an owner, a review cadence, a retirement trigger.
- Sunset — alerts that fall below acceptance thresholds are retired, not "left running."
Common Pitfalls
- Building the CDS in a vacuum, then bolting it into the workflow. Workflow design must come first.
- Treating every alert as critical. Reserve
critical and modal alerts for true safety events.
- Ignoring the suppression model. Re-firing the same alert 7 times in one encounter is alert abuse.
- Hand-coding logic that should be in CQL — losing portability and auditability.
- Assuming "the EHR will do the right thing" with your card. Test in each customer's environment.
- Claiming HHS CDS exemption without actually satisfying all four Cures Act criteria.
Task-Specific Questions
- What is the decision, who makes it, in what setting?
- What is the evidence base?
- Which hook (or non-CDS-Hooks surface) lands at the right moment?
- Will it be interruptive? What is the justification?
- Who owns it, how often is it reviewed, and what is the retirement criterion?
- Are you positioning this as HHS-exempt CDS or as a SaMD?
Related Skills
- healthcare-context: EHR, setting, and regulatory posture shape every CDS choice.
- smart-on-fhir: SMART apps that pair with CDS Hooks for deeper interactions.
- cpoe-orders: Where
order-select and order-sign hooks fire.
- fhir-integration: The data model CDS Hooks
prefetch and CQL operate on.
- terminology-services: Value sets (VSAC), code systems used in CQL.
- fda-samd: When your CDS does not meet the Cures Act exemption criteria.
- clinical-ai-ml: When the CDS recommendation is generated by a model rather than rules.
