> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Clinical Decision Support — Admin Guide

> Clinical Decision Support (CDS) provides automated, configurable alerts when clinicians perform actions that may affect patient safety. CDS rules trigger point…

## Overview

Clinical Decision Support (CDS) provides automated, configurable alerts when clinicians perform actions that may affect patient safety. CDS rules trigger point-of-care alerts for drug interactions, drug allergies, medication monitoring gaps, and documentation gaps.

***

## Getting Started

### Accessing CDS Rules

1. Navigate to **Clinical** → **CDS Rules** (`/cl/cds-rules`)
2. You must have the `cl.cds_rules.view` permission to see the list
3. You must have the `cl.cds_rules.manage` permission to create, edit, or delete rules

### Who Can Manage Rules?

By default, only **Organization Administrators** have the `cl.cds_rules.manage` permission. Staff members can view rules but cannot modify them. This can be adjusted through the Permissions administration panel.

***

## Creating a CDS Rule

1. Click **"Add Rule"** on the CDS Rules page
2. Fill in the required fields:

### General Settings

| Field         | Description                                                  | Required |
| ------------- | ------------------------------------------------------------ | -------- |
| Rule Name     | Descriptive name (e.g., "Opioid-Benzodiazepine Interaction") | ✅        |
| Rule Type     | Category of the rule (see below)                             | ✅        |
| Trigger Event | When the rule should be evaluated                            | ✅        |
| Severity      | Alert priority level                                         | ✅        |
| Hard Stop     | If enabled, blocks the action until acknowledged             | ❌        |
| Active        | Whether the rule is currently enforced                       | ✅        |

### Rule Types

| Type                      | Description                                | Condition Fields               |
| ------------------------- | ------------------------------------------ | ------------------------------ |
| **Drug Interaction**      | Detects concurrent use of two drug classes | Drug Class A, Drug Class B     |
| **Drug Allergy**          | Flags medications matching a known allergy | Drug Class                     |
| **Medication Monitoring** | Alerts when lab monitoring is overdue      | Lab Test (LOINC), Days Overdue |
| **Documentation Gap**     | Flags missing or overdue documentation     | Note Type, Hours Overdue       |
| **Quality Measure**       | HEDIS/CMS quality measure gaps             | Measure ID (future)            |

### Condition Parameters

Parameters change based on the selected rule type:

* **Drug Interaction:** Enter two drug class names (e.g., "Opioid" and "Benzodiazepine"). The engine checks if the patient has active medications matching both classes.
* **Drug Allergy:** Enter one drug class name. The engine checks if the patient has both an active allergy AND an active medication matching that class.
* **Medication Monitoring:** Enter the LOINC code for the lab test and the number of days after which it's considered overdue.
* **Documentation Gap:** Enter the note type and maximum hours before it's flagged as overdue.

### Action Settings

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| Action Type    | `alert` (show warning), `block` (hard stop), `suggest` (recommendation) |
| Title          | Short alert title shown to clinicians                                   |
| Message        | Detailed alert message                                                  |
| Recommendation | Optional guidance for the clinician                                     |

***

## Severity Levels

| Severity     | Color              | Description                  | Recommended Use                         |
| ------------ | ------------------ | ---------------------------- | --------------------------------------- |
| **Critical** | Red (destructive)  | Life-threatening risk        | Contraindicated drug combinations       |
| **Major**    | Orange (warning)   | Significant clinical concern | Known interactions with serious effects |
| **Moderate** | Yellow (secondary) | Important but manageable     | Monitoring reminders, dose adjustments  |
| **Minor**    | Gray (muted)       | Low-priority awareness       | Documentation reminders                 |
| **Info**     | Blue (muted)       | Informational only           | Best practice suggestions               |

***

## Hard Stop Rules

When a rule has **Hard Stop** enabled:

1. The clinician sees a **blocking modal** that cannot be dismissed
2. They must either:
   * **Acknowledge** the alert (for non-hard-stop alerts)
   * **Override with reason** — a clinical justification is required
3. The override reason is permanently recorded in the audit trail

**Best Practice:** Reserve hard stops for critical safety rules (e.g., contraindicated drug combinations). Excessive hard stops lead to "alert fatigue" and reduced clinical effectiveness.

***

## Alert Lifecycle

```
Rule Triggered → Alert Created → Clinician Sees Alert
                                       ↓
                              ┌─────────┴─────────┐
                              ↓                     ↓
                         Acknowledge            Override
                         (dismiss)          (with reason)
                              ↓                     ↓
                         Alert Closed          Alert Closed
                                            + Audit Record
```

### Alert Actions

| Action          | Who Can Do It                   | What Happens                                         |
| --------------- | ------------------------------- | ---------------------------------------------------- |
| **Acknowledge** | Any clinician with chart access | Alert marked as acknowledged with timestamp          |
| **Override**    | Any clinician with chart access | Alert marked as overridden with reason and timestamp |

Both actions are **immutable** — once acknowledged or overridden, the action cannot be undone. This ensures a complete audit trail for compliance.

***

## Audit & Compliance

### What Is Tracked

* Every alert trigger (rule ID, chart ID, severity, timestamp)
* Every acknowledgment (who, when)
* Every override (who, when, reason)
* Domain events published: `cds_alert_triggered`, `cds_rule_overridden`

### Reviewing Overrides

Overridden alerts can be reviewed by:

1. Viewing the **CDS Alerts Panel** on any patient chart
2. Filtering alerts to show overridden items
3. Reviewing the override reason and clinician who overrode

### Regulatory Compliance

CDS alerts support compliance with:

* **Joint Commission** medication safety standards
* **CMS Conditions of Participation** for medication management
* **AHCCCS AMPM** behavioral health documentation requirements
* **42 CFR Part 2** — alert payloads contain IDs only, no PHI

***

## Managing Alert Fatigue

### Recommended Practices

1. **Start conservative** — begin with a small number of critical rules
2. **Monitor override rates** — high override rates indicate rules may be too aggressive
3. **Use appropriate severity** — not every alert needs to be "critical"
4. **Limit hard stops** — reserve for truly dangerous situations
5. **Review and adjust** — regularly review active rules and deactivate those with low clinical value
6. **Site-specific rules** — use the optional site\_id field to scope rules to specific locations

### Deactivating a Rule

1. Navigate to **CDS Rules** → find the rule
2. Click **Edit**
3. Uncheck **Active**
4. Save — the rule will no longer trigger new alerts

Existing alerts from the rule remain in the system for audit purposes.

***

## Permissions Reference

| Permission Key        | Description                       | Default Roles              |
| --------------------- | --------------------------------- | -------------------------- |
| `cl.cds_rules.view`   | View CDS rules list               | org\_admin, manager, staff |
| `cl.cds_rules.manage` | Create, edit, delete CDS rules    | org\_admin                 |
| `cl.cds_alerts.view`  | View CDS alerts on patient charts | org\_admin, manager, staff |

***

## Troubleshooting

| Issue                         | Solution                                                                |
| ----------------------------- | ----------------------------------------------------------------------- |
| Rules not firing              | Verify the rule is **Active** and matches the correct **Trigger Event** |
| Too many alerts               | Reduce rule sensitivity or deactivate low-value rules                   |
| Cannot create rules           | Verify you have the `cl.cds_rules.manage` permission                    |
| Alerts not appearing on chart | Verify you have the `cl.cds_alerts.view` permission                     |
| Override reason not saving    | Ensure the reason field is not empty — it's required for overrides      |

***

## Technical Notes

* CDS evaluation runs **client-side** in Phase 1 (simple text matching)
* Future phases will add **server-side evaluation** via edge functions for external API calls (RxNav, FDB)
* Alert data is stored in `cl_cds_alerts` with no DELETE policy (audit retention)
* Domain events integrate with the Forms & Workflow (FW) automation engine