> ## 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.

# Enhancements User Guide

> This guide helps clinicians and staff use Clinical Pathways (EN-28) and CDS Alert Analytics (EN-29). EN-27 (server-side CDS evaluation) operates automatically…

> **Purpose:** This guide helps clinicians and staff use Clinical Pathways (EN-28) and CDS Alert Analytics (EN-29). EN-27 (server-side CDS evaluation) operates automatically and requires no direct user interaction.

***

## Overview

The CL-08 Enhancements add three capabilities to Clinical Decision Support:

* **EN-27 — Server-Side CDS Evaluation:** Automatically checks drug interactions via the RxNav API when medications are prescribed or reconciled. Operates behind the scenes with fail-open safety.
* **EN-28 — Clinical Pathway Guidance:** Structured, step-by-step care pathways that guide clinicians through evidence-based treatment protocols.
* **EN-29 — CDS Alert Fatigue Analytics:** Dashboard showing alert override rates, acknowledgement times, and per-provider metrics to identify alert fatigue.

### Who Should Use This Guide

| Role                  | Use Case                                                         |
| --------------------- | ---------------------------------------------------------------- |
| Licensed Clinician    | View pathways assigned to patients; follow step-by-step guidance |
| Prescriber (MD/NP/PA) | Benefit from automatic drug interaction checks (EN-27)           |
| Clinical Supervisor   | Monitor CDS alert fatigue metrics; review override patterns      |
| Quality/Compliance    | Analyze alert data for quality improvement initiatives           |

***

## Prerequisites

### Permissions Required

| Permission            | Feature                        | Description                   |
| --------------------- | ------------------------------ | ----------------------------- |
| `cl.pathways.view`    | Pathway Guidance               | View pathway definitions      |
| `cl.pathways.manage`  | Pathway Management             | Create, edit, delete pathways |
| `cl.cds_rules.view`   | CDS Analytics                  | View alert fatigue dashboard  |
| `cl.cds_rules.manage` | CDS Analytics (Provider table) | View per-provider metrics     |

> **Note:** Contact your organization administrator if you don't have the required permissions.

***

## EN-27: Server-Side CDS Evaluation

### How It Works

The server-side CDS engine runs automatically when medications are evaluated. You do not need to take any action — it operates transparently.

**Key behaviors:**

1. **Drug Interaction Checks:** When a patient has 2+ active medications with RxCUI codes, the system queries the NLM RxNav API for known interactions.
2. **Drug-Allergy Checks:** Active medications are cross-referenced against the patient's allergy list using organization-defined CDS rules.
3. **Fail-Open Safety:** If the RxNav API is unavailable (timeout, network error), the system falls back to text-based rule matching. It will **never block** a workflow due to an API outage — alerts are generated on a best-effort basis.
4. **Audit Trail:** Every evaluation includes a `request_id`, timestamp, and latency measurement for compliance auditing.

### What You'll See

* **Alerts appear** in the patient chart's CDS alert panel when interactions or allergy conflicts are detected.
* **Alert severity** ranges from `moderate` to `critical` based on RxNav severity data or rule configuration.
* **Degraded mode indicator:** If the system operated in fallback mode, the evaluation response includes `degraded: true` (visible in audit logs, not directly in UI).

***

## EN-28: Clinical Pathway Guidance

### Accessing Clinical Pathways

1. Navigate to **Clinical** in the main sidebar
2. Expand **Clinical Pathways**
3. Click **Pathway Management**

### Understanding the Interface

The Pathway Management page displays all defined care pathways as expandable cards:

| Element             | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| **Pathway Name**    | The title of the care pathway (e.g., "New SUD Intake Protocol")                  |
| **Condition Type**  | The clinical condition this pathway applies to (e.g., `new_sud`, `co_occurring`) |
| **Status Badge**    | Shows **Active** (green) or **Inactive** (gray)                                  |
| **Step Count**      | Number of steps in the pathway                                                   |
| **Expand/Collapse** | Click a card to reveal the step-by-step details                                  |

### Viewing Pathway Steps

1. Click on any pathway card to expand it
2. Each step shows:
   * **Step number and title**
   * **Description** of what to do at this step
   * **Recommendations** — clinical best practices
   * **Criteria** — what must be true to consider this step complete

### Creating a New Pathway

> Requires `cl.pathways.manage` permission.

1. Click **New Pathway** in the top right
2. Fill in the required fields:
   * **Pathway Name:** A descriptive name (e.g., "Opioid Use Disorder — MAT Initiation")
   * **Condition Type:** The clinical condition category
   * **Description:** Optional overview of the pathway's purpose
3. Add steps:
   * Each step includes a title, description, recommendations, and completion criteria
   * Steps are ordered by step number
4. Click **Save**

**Result:** The pathway appears in the list and can be assigned to patient charts.

***

## EN-29: CDS Alert Fatigue Analytics

### Accessing the Dashboard

1. Navigate to **Clinical** in the main sidebar
2. Expand **CDS Analytics** (under Admin section)
3. Click **Alert Fatigue Dashboard**

### Understanding the Dashboard

#### Summary Cards

Four cards at the top provide at-a-glance metrics:

| Card                | What It Shows                                                        |
| ------------------- | -------------------------------------------------------------------- |
| **Total Alerts**    | Number of CDS alerts triggered in the selected time window           |
| **Override Rate**   | Percentage of alerts overridden by clinicians (flagged red if > 50%) |
| **Total Overrides** | Raw count of overridden alerts                                       |
| **Avg. Ack Time**   | Average time from alert trigger to clinician acknowledgement         |

#### Time Window Selector

Use the dropdown in the top right to filter data:

* **Last 7 days** — Recent activity
* **Last 30 days** — Default view, monthly trends
* **Last 90 days** — Quarterly analysis

#### Override Rate by Rule Chart

A bar chart showing the override rate for each CDS rule. Higher bars indicate rules that clinicians frequently override — a potential sign of alert fatigue or overly sensitive rules.

#### Alerts by Rule Table

Detailed breakdown per rule:

* **Rule name**
* **Alert count** and **Override count**
* **Override Rate** (highlighted red if > 50%)
* **Avg. Ack Time** — How quickly clinicians respond

#### Alerts by Provider Table

> Requires `cl.cds_rules.manage` permission.

Shows per-provider metrics with display names (resolved from user profiles):

* **Provider name**
* **Alert count**, **Override count**, **Override Rate**
* **Avg. Ack Time**

### Interpreting the Data

| Metric                     | Healthy Range | Action if Out of Range                                      |
| -------------------------- | ------------- | ----------------------------------------------------------- |
| Override Rate              | \< 30%        | Review rule sensitivity; consider deactivating noisy rules  |
| Avg. Ack Time              | \< 5 minutes  | Investigate workflow bottlenecks; ensure alerts are visible |
| Total Alerts (high volume) | Varies        | May indicate over-broad rules or high patient acuity        |

***

## Tips and Best Practices

### Do's

* ✅ Review the Alert Fatigue Dashboard weekly to catch emerging patterns
* ✅ Use pathway steps as a checklist during patient encounters
* ✅ Report false-positive alerts to your admin so rules can be tuned
* ✅ Check the Override Rate by Provider to identify training opportunities

### Don'ts

* ❌ Don't override alerts without reading the alert message
* ❌ Don't ignore high override rates — they may indicate configuration issues
* ❌ Don't create duplicate pathways for the same condition type

***

## Troubleshooting

### Issue: "Access Denied" on Pathways Page

**Symptoms:** Shield icon with "You don't have permission to access this page"

**Cause:** Your role doesn't include `cl.pathways.manage` permission.

**Solution:** Contact your organization administrator to assign the `cl.pathways.manage` permission to your role.

***

### Issue: CDS Analytics Shows No Data

**Symptoms:** All summary cards show 0, empty state messages appear.

**Cause:** No CDS alerts have been triggered in the selected time window, or CDS rules are not yet configured.

**Solution:**

1. Verify CDS rules are configured at **Clinical** → **CDS Rules**
2. Try expanding the time window to **Last 90 days**
3. Confirm rules are set to **Active**

***

### Issue: Provider Table Shows UUID Instead of Name

**Symptoms:** Provider column shows truncated identifiers like "4832659c…"

**Cause:** The provider's profile doesn't have a `full_name` set.

**Solution:** Ask your administrator to update the provider's profile name in **Settings** → **Users**.

***

## Related Documentation

* **Admin Guide:** `docs/guides/cl/cl-08-cds-enhancements-admin-guide.md`
* **Specification:** `specs/cl/specs/CL-08-ENHANCEMENTS.md`
* **CDS Rule Management:** Navigate to Clinical → CDS Rules in the application

***

## Glossary

| Term              | Definition                                                                              |
| ----------------- | --------------------------------------------------------------------------------------- |
| **CDS**           | Clinical Decision Support — automated alerts that help clinicians make safer decisions  |
| **Override**      | When a clinician acknowledges an alert but proceeds with the flagged action             |
| **Alert Fatigue** | Desensitization to alerts due to high volume, leading to important alerts being ignored |
| **RxNav**         | NIH National Library of Medicine API for drug interaction data                          |
| **RxCUI**         | RxNorm Concept Unique Identifier — a standardized drug code                             |
| **Pathway**       | A structured, step-by-step clinical protocol for a specific condition                   |
| **Degraded Mode** | When the external API is unavailable; the system falls back to local rule matching      |

***

**Last Updated:** 2026-02-26\
**Questions?** Contact your organization administrator.