prior-auth-review-skill

What this skill does

# Prior Authorization Review Skill

## Overview

This skill automates the payer review process for prior authorization (PA) requests. It processes clinical documentation, validates medical necessity against coverage policies, and generates authorization decisions with supporting rationale.

**Target Users:** Health insurance payer organizations (Medicare Advantage, Commercial, Medicaid MCOs)

**Value Proposition:** Reduce PA review time from 30-60 minutes to under 5 minutes. Enable auto-approval for 40-60% of clear-cut cases.

---

## Architecture

This skill uses a **simplified 2-subskill workflow**:

```
Subskill 1: Intake & Assessment
  ↓ (validates data, extracts clinical info, assesses medical necessity)
Subskill 2: Decision & Notification
  ↓ (generates auth decision with provider notification)

ONLY REVIEW THE SUBSKILL FILES WHEN THEY ARE NEEDED, DONT PRE-READ THE WHOLE SKILL ON BOOTUP

Output: Authorization Decision Package
```

### Waypoint Files

```
waypoints/
├── assessment.json          # Subskill 1 output (consolidated)
└── decision.json           # Subskill 2 output (final decision)
```

---

## Prerequisites

### Required MCP Servers

This skill requires 3 healthcare MCP connectors:

1. **CMS Coverage MCP Connector** - Medicare coverage policies (NCDs, LCDs)
2. **ICD-10 MCP Connector** - Diagnosis code validation and lookup
3. **NPI MCP Connector** - Healthcare provider verification via NPPES

**For detailed tool usage, parameters, and CMS web resources, see [references/01-intake-assessment.md](references/01-intake-assessment.md#prerequisites).**

### MCP Invocation Notifications

During execution, the skill displays notifications before and after each MCP connector call:
- Before: "Verifying provider credentials via NPI MCP Connector..."
- After: "NPI MCP Connector completed successfully - Provider verified: Dr. [Name]"
- Before: "Validating diagnosis codes via ICD-10 MCP Connector..."
- After: "ICD-10 MCP Connector completed successfully - [N] codes validated"
- Before: "Searching coverage policies via CMS Coverage MCP Connector..."
- After: "CMS Coverage MCP Connector completed successfully - Found policy: [Policy ID]"
- Before: "Validating procedure codes via CMS Fee Schedule..."
- After: "CPT/HCPCS codes validated via CMS Fee Schedule - [N] codes checked"

### File Structure

See README.md File Organization section for complete directory structure and file descriptions.

---

## Decision Policy

This skill enforces a **decision policy rubric** that determines the outcome when validation checks fail. The policy balances regulatory compliance, patient safety, and operational efficiency.

**See [references/rubric.md](references/rubric.md) for:**
- Complete decision policy matrix (STRICT vs LENIENT enforcement)
- Detailed decision logic flow and pseudocode
- Override authority rules
- Customization examples (lenient mode, strict compliance mode, auto-approval mode)

**Quick Summary:**
- **STRICT policies** → Automatic DENY (provider verification, invalid codes, criteria NOT_MET)
- **LENIENT policies** → Automatic PEND (insufficient evidence, missing policy)
- **Default fallback** → PEND (when unclear)

To customize decision logic for your organization, edit [references/rubric.md](references/rubric.md).

---

## How to Use

### Process PA Request

Simply invoke the skill:

```
Use the prior-auth-review-skill
```

The skill will:
1. Check for incomplete requests (auto-resume if found)
2. Collect PA request details
3. Execute Subskill 1: Intake & Assessment
4. Execute Subskill 2: Decision & Notification
5. Output authorization decision package

---

## Execution Flow

When this skill is invoked:

### Startup: Check MCP Configuration

**Before proceeding, verify required MCP connectors are available.**

Check for the following MCP connectors:
1. **CMS Coverage MCP** - Required for coverage policy lookup
2. **ICD-10 MCP** - Required for diagnosis code validation
3. **NPI MCP** - Required for provider verification

**If any MCP connectors are not configured:**

Display error and exit:
> "Missing required MCP connectors: [list missing connectors]. This skill requires all three healthcare MCP connectors to function. Please configure the missing connectors and try again. See README Prerequisites for setup instructions."

Exit skill.

**If all MCP connectors are available:** Proceed silently to next step.

---

### Startup: Request Input Files

**Prompt the user to provide input files or use sample data.**

Display the following prompt:

```
Prior Authorization Review requires the following input files:

REQUIRED FILES:
1. Prior Authorization Request Form (PDF) - Contains member info, requested service, provider details
2. Clinical Notes / H&P (PDF) - History and physical examination documentation
3. Diagnostic Imaging Reports (PDF) - CT, MRI, X-ray, or other imaging results
4. Laboratory Results (PDF) - Relevant lab work supporting medical necessity
5. Additional Supporting Documentation (PDF, optional) - PFTs, specialist consults, etc.

OPTIONS:
(A) Upload your own files - Provide paths to each required document
(B) Use sample files - Load pre-configured sample case (CT-guided lung biopsy)

Enter your choice (A/B): ___
```

**If user selects (A) - Upload own files:**
- Prompt for path to each required file
- Validate files exist and are readable
- Store file paths for use in Subskill 1
- Set `using_sample_files = False`

**If user selects (B) - Use sample files:**
- Load sample files from `assets/sample/`:
  - `01_Prior_Auth_Request_Form.pdf`
  - `02_Clinical_Notes_H_and_P.pdf`
  - `03_CT_Chest_Report.pdf`
  - `04_Laboratory_Results.pdf`
  - `05_Pulmonary_Function_Tests.pdf`
- Display: "Loading sample case: CT-guided transbronchial lung biopsy for 1.2cm RUL nodule"
- Set `using_sample_files = True`
- **Demo mode note:** When sample files are used, the sample data contains demo NPI (`1234567890`) and sample member ID (`1EG4-TE5-MK72`). This combination triggers demo mode, which skips the NPI MCP lookup for this specific provider only. All other MCP calls (ICD-10 validation, CMS Coverage policy search) execute normally.

---

### Startup: Check for Existing Request

**Check if `waypoints/assessment.json` exists:**

- **If exists and incomplete:**
  ```
  Found incomplete PA request: [Request ID]
  Resume this request? (Y/N): ___
  ```
  - If **Y**: Load assessment and continue to Subskill 2
  - If **N**: Archive and start new

- **If does not exist:**
  - Start from Subskill 1

### Subskill 1: Intake & Assessment

**Execute:** Read and follow `references/01-intake-assessment.md`

**What it does:**
1. Collect PA request information
2. Validate provider credentials and codes (parallel MCP calls)
3. Search coverage policies
4. Extract clinical data
5. Assess medical necessity against policy criteria
6. Generate recommendation (APPROVE/DENY/PEND)

**Output:** `waypoints/assessment.json` (consolidated)

**Duration:** 3-4 minutes

**Ask user:**
```
Ready to proceed to Subskill 2? (Y/N): ___
```
- If **Y**: Continue to Subskill 2
- If **N**: Save and exit

### Subskill 2: Decision & Notification

**Execute:** Read and follow `references/02-decision-notification.md`

**What it does:**
1. Load assessment from Subskill 1
2. Confirm or override recommendation
3. Generate decision-specific content:
   - **Approval:** Auth number, validity dates, limitations
   - **Denial:** Specific reasons, policy references, appeal rights
   - **Pend:** Documentation requests, submission deadline
4. Create provider notification letter
5. Document audit trail

**Output:**
- `waypoints/decision.json` (final decision)
- `outputs/notification_letter.txt` (provider notification)

**Duration:** 1-2 minutes

### Final Summary

Display a concise completion message with:
- Request details (ID, member, service, decision outcome)
- Authorization number and validity dates (if approved)
- Files generated (waypoints and notification)
- Next steps based on decision type

Offer user