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

# Integration Documentation: PM-50 — AI-Powered Denial Prediction & Prevention

> Created: 2026-04-07 Status: \U0001F4DD Planned

**Spec:** PM-50\
**Created:** 2026-04-07\
**Status:** 📝 Planned

***

## Overview

PM-50 provides ML-based claim denial prediction as a pre-submission advisory layer. It integrates into the PM-08 claim submission queue, complements PM-18 rule-based scrubbing, reads documentation completeness metadata from CL-36 via Platform Integration Layer, and uses PF-96 jurisdiction profiles for payer/state-specific context.

***

## Integration Points

### Platform Foundation Dependencies

| PF Feature                    | Integration Type           | Usage                                                                         |
| ----------------------------- | -------------------------- | ----------------------------------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct dependency          | Tenant isolation, site-scoped predictions                                     |
| PF-02 (RBAC)                  | Direct dependency          | Permission checks for billing specialist and revenue cycle director roles     |
| PF-10 (Notifications)         | Platform Integration Layer | Send documentation request notifications to clinical team                     |
| PF-96 (Jurisdiction Profiles) | Platform Integration Layer | Read payer/state-specific parameters (filing deadlines, modifier conventions) |

### Same-Core Dependencies

| PM Feature                | Integration Type    | Usage                                                                                   |
| ------------------------- | ------------------- | --------------------------------------------------------------------------------------- |
| PM-08 (Claims Management) | Shared UI surface   | Risk scores displayed in claim submission queue; scoring triggered on claim queue entry |
| PM-18 (Claim Scrubbing)   | Sequential pipeline | PM-18 scrubbing runs first (rule-based), PM-50 adds ML-based prediction after           |
| PM-29 (Denial Management) | Data feedback       | PM-29 denial outcomes feed PM-50 retraining pipeline (actual\_outcome field)            |

### Cross-Core Dependencies

| Feature                        | Integration Type                                   | Usage                                                                                                                                                          |
| ------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CL-36 (Clinical Documentation) | Platform Integration Layer (`@/platform/clinical`) | Read documentation completeness metadata (note section count, word count, required section presence, diagnosis specificity); no PHI content crosses into PM-50 |

***

## Events Published

| Event Name                              | Publisher | Subscribers                        | Status     |
| --------------------------------------- | --------- | ---------------------------------- | ---------- |
| `pm.denial_prediction.created`          | PM-50     | None (available for GR dashboards) | 📝 Planned |
| `pm.denial_prediction.outcome_recorded` | PM-50     | None (available for analytics)     | 📝 Planned |

### Event Payload Schemas

**`pm.denial_prediction.created`:**

```typescript theme={null}
{
  prediction_id: string;
  claim_id: string;
  risk_level: 'low' | 'medium' | 'high';
  organization_id: string;
}
```

**`pm.denial_prediction.outcome_recorded`:**

```typescript theme={null}
{
  prediction_id: string;
  claim_id: string;
  actual_outcome: 'paid' | 'denied';
  organization_id: string;
}
```

***

## Edge Functions

| Function                    | Purpose                                                       | Auth                |
| --------------------------- | ------------------------------------------------------------- | ------------------- |
| `predict-denial-risk`       | Receive claim features, return risk score + reasons + actions | `verifyOrgAccess()` |
| `retrain-denial-model`      | Cron-triggered monthly retraining using historical outcomes   | Service role (cron) |
| `denial-prediction-metrics` | Return aggregated model performance metrics for dashboard     | `verifyOrgAccess()` |

***

## Platform Integration Layer Usage

* **`@/platform/notifications`** — Send documentation request to clinical team (FR-3.2)
* **`@/platform/clinical`** — Read documentation completeness metadata from CL-36 (FR-3.1); PM-50 implements stub/adapter returning null signals when CL-36 unavailable

***

## Data Flow

```
PM-08 (Claim enters queue) → PM-18 (Rule-based scrub) → PM-50 (ML prediction)
                                                              ↓
                                                    Risk Score + Actions
                                                              ↓
                                                    Biller Review (UI)
                                                    ├─ Acknowledge → Submit
                                                    ├─ Hold → Investigate
                                                    ├─ Correct → Re-queue
                                                    └─ Override → Submit with reason
```

***

## Security Boundaries

* No PHI crosses into PM-50 — only categorical/aggregate features and completeness metadata
* All prediction data scoped to organization via RLS with SECURITY DEFINER helper
* Model training data never crosses organization boundaries
* Edge functions validate org access via `verifyOrgAccess()` from `_shared/auth.ts`

***

## References

* **Spec:** `specs/pm/specs/PM-50-ai-denial-prediction-prevention.md`
* **Related:** PM-08, PM-18, PM-29, PM-49, CL-36, PF-96
* **Events:** `docs/architecture/integrations/EVENT_CONTRACTS.md`
* **Platform layers:** `docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md`