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

# AI Compliance Advisor - Prompts Reference

> Module: GR Core - AI Compliance Advisor (GR-06) Audience: Developers, Technical Administrators Last Updated: 2025-12-14

**Module:** GR Core - AI Compliance Advisor (GR-06)\
**Audience:** Developers, Technical Administrators\
**Last Updated:** 2025-12-14

***

## Overview

This document provides technical reference for the AI prompts and schemas used in the GR-06 AI Compliance Advisor. Understanding these prompts helps interpret AI outputs and customize behavior.

***

## Prompt Templates

### Compliance Chat System Prompt

**Location:** `src/cores/gr/ai/prompts.ts` → `COMPLIANCE_CHAT_PROMPT`

**Purpose:** General compliance chat assistant

**Specializations:**

* CARF (Commission on Accreditation of Rehabilitation Facilities)
* Joint Commission accreditation
* State licensing requirements for behavioral health and recovery housing
* CMS (Centers for Medicare & Medicaid Services) regulations
* HIPAA privacy and security requirements
* SAMHSA guidelines for substance use treatment

**Guidelines Enforced:**

* Provides clear, actionable guidance
* References specific regulatory standards when applicable
* Identifies potential compliance risks
* Considers organizational context
* Never provides legal advice
* Uses anonymized references for cases
* Flags state/accreditor variations

***

### Requirement Identification Prompt

**Location:** `src/cores/gr/ai/prompts.ts` → `REQUIREMENT_IDENTIFICATION_PROMPT`

**Purpose:** Analyze organizational context and identify applicable regulatory requirements

**Output Structure:**
For each requirement identified:

1. Clear title and description
2. Regulatory body (CARF, Joint Commission, State, CMS, SAMHSA, HIPAA)
3. Specific reference code (e.g., "CARF 1.A.1", "42 CFR Part 2")
4. Priority (critical, high, medium, low)
5. Confidence score (0-100)

**Focus Areas:**

* Directly applicable requirements
* Currently in effect or upcoming
* Commonly cited in audits
* High-risk for non-compliance

**Tool Called:** `extract_requirements`

***

### Gap Analysis Prompt

**Location:** `src/cores/gr/ai/prompts.ts` → `GAP_ANALYSIS_PROMPT`

**Purpose:** Analyze requirements and current compliance status to identify gaps

**Gap Types:**

| Type       | Definition                                     |
| ---------- | ---------------------------------------------- |
| `evidence` | Missing documentation or proof of compliance   |
| `check`    | Missing or incomplete compliance verification  |
| `training` | Staff training gaps related to the requirement |
| `policy`   | Missing or outdated policies/procedures        |

**Output Structure:**
For each gap:

1. Gap type classification
2. Clear description
3. Priority (critical, high, medium, low)
4. Specific recommendation
5. 2-4 concrete remediation actions

**Prioritization Criteria:**

* Likely audit citations
* Patient/resident safety risks
* Approaching deadlines
* Ease of remediation

**Tool Called:** `analyze_gaps`

***

### Audit Preparation Prompt

**Location:** `src/cores/gr/ai/prompts.ts` → `AUDIT_PREPARATION_PROMPT`

**Purpose:** Assess audit readiness and generate preparation plan

**Output Structure:**

1. **Readiness Score**: 0-100
2. **Assessment Narrative**: Current state summary
3. **Gap Areas**: Areas needing attention
4. **Potential Findings**: Likely audit citations
5. **Checklist Items**: Prioritized tasks

**Checklist Item Status:**

* `ready` - No action needed
* `needs_attention` - Some work required
* `not_ready` - Significant work needed

**Considerations:**

* Audit type (CARF survey, state inspection, CMS review)
* Historical findings
* Current compliance status
* Documentation completeness
* Staff interview readiness

**Tool Called:** `prepare_audit`

***

### Risk Assessment Prompt

**Location:** `src/cores/gr/ai/prompts.ts` → `RISK_ASSESSMENT_PROMPT`

**Purpose:** Assess risks and recommend mitigation strategies

**Likelihood Scale (1-5):**

| Score | Rating         | Description                                 |
| ----- | -------------- | ------------------------------------------- |
| 1     | Rare           | May occur only in exceptional circumstances |
| 2     | Unlikely       | Could occur at some time                    |
| 3     | Possible       | Might occur at some time                    |
| 4     | Likely         | Will probably occur                         |
| 5     | Almost Certain | Expected to occur                           |

**Impact Scale (1-5):**

| Score | Rating       | Description                                |
| ----- | ------------ | ------------------------------------------ |
| 1     | Negligible   | Minor inconvenience                        |
| 2     | Minor        | Some operational disruption                |
| 3     | Moderate     | Significant disruption, possible citations |
| 4     | Major        | Serious harm, regulatory action            |
| 5     | Catastrophic | Loss of license, legal liability           |

**Risk Rating Calculation:**

* Score = Likelihood × Impact (1-25)
* 1-4: Low
* 5-9: Medium
* 10-16: High
* 17-25: Critical

**Mitigation Strategies:**

| Strategy   | Definition                                     |
| ---------- | ---------------------------------------------- |
| `avoid`    | Eliminate the activity creating risk           |
| `reduce`   | Implement controls to reduce likelihood/impact |
| `transfer` | Transfer risk through insurance or contracts   |
| `accept`   | Accept risk with monitoring                    |

**Output Structure:**

1. Likelihood score (1-5)
2. Impact score (1-5)
3. Risk score (calculated)
4. Risk rating
5. Mitigation strategy recommendation
6. 2-5 specific mitigation actions
7. Reasoning for assessment

**Tool Called:** `assess_risk`

***

## Structured Output Schemas

### Requirement Suggestion Schema

**Location:** `src/cores/gr/ai/schemas.ts` → `requirementSuggestionSchema`

```typescript theme={null}
{
  suggestions: [{
    title: string,          // Clear title for the requirement
    description: string,    // Detailed description
    regulatoryBody: string, // CARF, Joint Commission, State, CMS, SAMHSA, HIPAA
    referenceCode?: string, // Specific reference code
    priority: 'critical' | 'high' | 'medium' | 'low',
    confidence: number      // 0-100
  }]
}
```

***

### Gap Analysis Schema

**Location:** `src/cores/gr/ai/schemas.ts` → `gapAnalysisSchema`

```typescript theme={null}
{
  gaps: [{
    type: 'evidence' | 'check' | 'training' | 'policy',
    description: string,
    priority: 'critical' | 'high' | 'medium' | 'low',
    recommendation: string,
    suggestedActions: string[]  // 2-4 items
  }]
}
```

***

### Audit Preparation Schema

**Location:** `src/cores/gr/ai/schemas.ts` → `auditPrepSchema`

```typescript theme={null}
{
  readinessScore: number,        // 0-100
  assessment: string,            // Narrative assessment
  gapAreas: string[],            // Key areas needing attention
  potentialFindings: string[],   // Potential audit findings
  checklistItems: [{
    item: string,
    status: 'ready' | 'needs_attention' | 'not_ready',
    priority: 'high' | 'medium' | 'low'
  }]
}
```

***

### Risk Assessment Schema

**Location:** `src/cores/gr/ai/schemas.ts` → `riskAssessmentSchema`

```typescript theme={null}
{
  likelihood: number,      // 1-5
  impact: number,          // 1-5
  riskScore: number,       // 1-25 (likelihood × impact)
  riskRating: 'low' | 'medium' | 'high' | 'critical',
  reasoning: string,
  suggestedStrategy: 'avoid' | 'reduce' | 'transfer' | 'accept',
  suggestedActions: string[],  // 2-5 items
  confidence: number           // 0-100
}
```

***

## Context Building

### buildComplianceContext Function

**Location:** `src/cores/gr/ai/prompts.ts` → `buildComplianceContext()`

**Purpose:** Build context string for AI prompts based on organization data

**Parameters:**

```typescript theme={null}
{
  organizationType?: string,  // e.g., "Recovery Housing"
  accreditations?: string[],  // e.g., ["CARF", "State License"]
  state?: string,             // e.g., "California"
  services?: string[]         // e.g., ["Residential Treatment", "Outpatient"]
}
```

**Output Format:**

```
Organization Type: Recovery Housing
Accreditations: CARF, State License
State: California
Services: Residential Treatment, Outpatient
```

***

## Module Context

All GR AI hooks pass module context to Platform AI:

```typescript theme={null}
{
  module: 'gr',
  feature: 'compliance-advisor' | 'gap-analysis' | 'audit-prep' | 'risk-assessment'
}
```

This enables:

* Module-specific rate limiting
* Usage tracking per module
* Feature-level analytics

***

## AI Hooks Reference

### useAIComplianceChat

**Purpose:** Interactive compliance chat
**Platform Hook:** `useAIChat`
**System Prompt:** `COMPLIANCE_CHAT_PROMPT`

### useAIRequirementIdentification

**Purpose:** Identify applicable requirements
**Platform Hook:** `useAIStructuredOutput`
**System Prompt:** `REQUIREMENT_IDENTIFICATION_PROMPT`
**Schema:** `requirementSuggestionSchema`

### useAIGapAnalysis

**Purpose:** Analyze compliance gaps
**Platform Hook:** `useAIStructuredOutput`
**System Prompt:** `GAP_ANALYSIS_PROMPT`
**Schema:** `gapAnalysisSchema`

### useAIAuditPreparation

**Purpose:** Audit readiness assessment
**Platform Hook:** `useAIStructuredOutput`
**System Prompt:** `AUDIT_PREPARATION_PROMPT`
**Schema:** `auditPrepSchema`

### useAIRiskAssessment

**Purpose:** Risk assessment
**Platform Hook:** `useAIStructuredOutput`
**System Prompt:** `RISK_ASSESSMENT_PROMPT`
**Schema:** `riskAssessmentSchema`

***

## PHI Protection

All AI prompts enforce PHI protection:

* System prompts instruct AI to use anonymized references
* The Platform AI layer includes PHI detection
* Identifiable information is blocked before reaching AI

**Example anonymization:**

* ❌ "John Smith in Room 204"
* ✅ "Resident R-001"

***

## Error Handling

AI hooks should handle these errors:

| Error Code | Meaning          | User Message                                  |
| ---------- | ---------------- | --------------------------------------------- |
| 429        | Rate limited     | "AI is busy. Please try again in a moment."   |
| 402        | Credits depleted | "AI credits depleted. Contact administrator." |
| 500        | AI service error | "AI service temporarily unavailable."         |

***

## Customization Options (Future)

Potential future customization points:

* Organization-specific prompt additions
* Custom regulatory body definitions
* State-specific requirement overrides
* Custom risk matrix thresholds

***

## Related Documentation

* [AI User Guide](./ai-compliance-user-guide.md)
* [AI Admin Guide](./ai-compliance-admin-guide.md)
* [Platform AI Integration](../architecture/integrations/index.md)