From e3f2bda9fcdb12fd9d7059a8d746e0af4cdc8ee9 Mon Sep 17 00:00:00 2001
From: "Dr. Keyur Patel" <drkeyurpatel@gmail.com>
Date: Fri, 27 Mar 2026 03:54:20 +0000
Subject: [PATCH] fix: address all CodeRabbit + Cubic review comments on PR
 #955
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeRabbit fixes (6 comments):
- All 4 skills: renamed 'When to Activate' → 'When to Use', added 'How It Works' and 'Examples' sections
- CDSS: DoseValidationResult.suggestedRange now typed as '| null'
- PHI: hyphenated 'Non-patient-sensitive'

Cubic fixes (7 issues):
- P1: CDSS weight-based check now BLOCKS when weight missing (was false-negative pass)
- P1: EMR medication safety clarified — critical = hard block, override requires documented reason
- P1: PHI logging guidance clarified — use opaque UUIDs only, not medical record numbers
- P2: CDSS validateDose now uses age and renal function params (ageAdjusted, renalAdjusted rules)
- P2: Eval CI example now enforces 95% threshold with jq + bc calculation
- P2: Eval CI example now includes --coverage --coverageThreshold on CDSS suite
- P2: CDSS suggestedRange null type fixed (same as CodeRabbit)
---
 skills/healthcare-cdss-patterns/SKILL.md  | 216 +++++++++++-----------
 skills/healthcare-emr-patterns/SKILL.md   | 127 +++++++------
 skills/healthcare-eval-harness/SKILL.md   | 165 +++++++++--------
 skills/healthcare-phi-compliance/SKILL.md | 203 +++++++++-----------
 4 files changed, 356 insertions(+), 355 deletions(-)

diff --git a/skills/healthcare-cdss-patterns/SKILL.md b/skills/healthcare-cdss-patterns/SKILL.md
index 00863466..0cb991fd 100644
--- a/skills/healthcare-cdss-patterns/SKILL.md
+++ b/skills/healthcare-cdss-patterns/SKILL.md
@@ -12,7 +12,7 @@ rollback: "git revert"
 
 Patterns for building Clinical Decision Support Systems that integrate into EMR workflows. CDSS modules are patient safety critical — zero tolerance for false negatives.
 
-## When to Activate
+## When to Use
 
 - Implementing drug interaction checking
 - Building dose validation engines
@@ -21,7 +21,15 @@ Patterns for building Clinical Decision Support Systems that integrate into EMR
 - Building medication order entry with safety checks
 - Integrating lab result interpretation with clinical context
 
-## Architecture
+## How It Works
+
+The CDSS engine is a **pure function library with zero side effects**. Input clinical data, output alerts. This makes it fully testable.
+
+Three primary modules:
+
+1. **`checkInteractions(newDrug, currentMeds, allergies)`** — Checks a new drug against current medications and known allergies. Returns severity-sorted `InteractionAlert[]`. Uses `DrugInteractionPair` data model.
+2. **`validateDose(drug, dose, route, weight, age, renalFunction)`** — Validates a prescribed dose against weight-based, age-adjusted, and renal-adjusted rules. Returns `DoseValidationResult`.
+3. **`calculateNEWS2(vitals)`** — National Early Warning Score 2 from `NEWS2Input`. Returns `NEWS2Result` with total score, risk level, and escalation guidance.
 
 ```
 EMR UI
@@ -35,84 +43,52 @@ CDSS Engine (pure functions, no side effects)
 EMR UI (displays alerts inline, blocks if critical)
 ```
 
-**Key principle:** The CDSS engine should be a pure function library with zero side effects. Input clinical data, output alerts. This makes it fully testable.
-
-## Drug Interaction Checking
-
-### Data Model
+### Drug Interaction Checking
 
 ```typescript
 interface DrugInteractionPair {
   drugA: string;           // generic name
   drugB: string;           // generic name
   severity: 'critical' | 'major' | 'minor';
-  mechanism: string;       // e.g., "CYP3A4 inhibition"
-  clinicalEffect: string;  // e.g., "Increased bleeding risk"
-  recommendation: string;  // e.g., "Avoid combination" or "Monitor INR closely"
-}
-
-interface InteractionAlert {
-  severity: 'critical' | 'major' | 'minor';
-  pair: [string, string];
-  message: string;
+  mechanism: string;
+  clinicalEffect: string;
   recommendation: string;
 }
-```
 
-### Implementation Pattern
-
-```typescript
 function checkInteractions(
   newDrug: string,
   currentMedications: string[],
   allergyList: string[]
 ): InteractionAlert[] {
   const alerts: InteractionAlert[] = [];
-
-  // Check drug-drug interactions
   for (const current of currentMedications) {
     const interaction = findInteraction(newDrug, current);
     if (interaction) {
-      alerts.push({
-        severity: interaction.severity,
-        pair: [newDrug, current],
-        message: interaction.clinicalEffect,
-        recommendation: interaction.recommendation
-      });
+      alerts.push({ severity: interaction.severity, pair: [newDrug, current],
+        message: interaction.clinicalEffect, recommendation: interaction.recommendation });
     }
   }
-
-  // Check drug-allergy interactions
   for (const allergy of allergyList) {
     if (isCrossReactive(newDrug, allergy)) {
-      alerts.push({
-        severity: 'critical',
-        pair: [newDrug, allergy],
+      alerts.push({ severity: 'critical', pair: [newDrug, allergy],
         message: `Cross-reactivity with documented allergy: ${allergy}`,
-        recommendation: 'Do not prescribe without allergy consultation'
-      });
+        recommendation: 'Do not prescribe without allergy consultation' });
     }
   }
-
-  // Sort by severity (critical first)
-  return alerts.sort((a, b) =>
-    severityOrder(a.severity) - severityOrder(b.severity)
-  );
+  return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
 }
 ```
 
-### Interaction pairs must be bidirectional
+Interaction pairs must be **bidirectional**: if Drug A interacts with Drug B, then Drug B interacts with Drug A.
 
-If Drug A interacts with Drug B, then Drug B interacts with Drug A. Store once, check both directions.
-
-## Dose Validation
+### Dose Validation
 
 ```typescript
 interface DoseValidationResult {
   valid: boolean;
   message: string;
-  suggestedRange: { min: number; max: number; unit: string };
-  factors: string[]; // what was considered (weight, age, renal function)
+  suggestedRange: { min: number; max: number; unit: string } | null;
+  factors: string[];
 }
 
 function validateDose(
@@ -121,64 +97,76 @@ function validateDose(
   route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',
   patientWeight?: number,
   patientAge?: number,
-  renalFunction?: number // eGFR
+  renalFunction?: number
 ): DoseValidationResult {
   const rules = getDoseRules(drug, route);
   if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };
+  const factors: string[] = [];
 
-  // Weight-based dosing
-  if (rules.weightBased && patientWeight) {
+  // SAFETY: if rules require weight but weight missing, BLOCK (not pass)
+  if (rules.weightBased) {
+    if (!patientWeight || patientWeight <= 0) {
+      return { valid: false, message: `Weight required for ${drug} (mg/kg drug)`,
+        suggestedRange: null, factors: ['weight_missing'] };
+    }
+    factors.push('weight');
     const maxDose = rules.maxPerKg * patientWeight;
     if (dose > maxDose) {
-      return {
-        valid: false,
-        message: `Dose ${dose}${rules.unit} exceeds max ${maxDose}${rules.unit} for ${patientWeight}kg patient`,
-        suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit },
-        factors: ['weight']
-      };
+      return { valid: false, message: `Dose exceeds max for ${patientWeight}kg`,
+        suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };
     }
   }
 
-  // Absolute max dose
-  if (dose > rules.absoluteMax) {
-    return {
-      valid: false,
-      message: `Dose ${dose}${rules.unit} exceeds absolute max ${rules.absoluteMax}${rules.unit}`,
-      suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit },
-      factors: ['absolute_max']
-    };
+  // Age-based adjustment (when rules define age brackets and age is provided)
+  if (rules.ageAdjusted && patientAge !== undefined) {
+    factors.push('age');
+    const ageMax = rules.getAgeAdjustedMax(patientAge);
+    if (dose > ageMax) {
+      return { valid: false, message: `Exceeds age-adjusted max for ${patientAge}yr`,
+        suggestedRange: { min: rules.typicalMin, max: ageMax, unit: rules.unit }, factors };
+    }
   }
 
-  return { valid: true, message: 'Within range', suggestedRange: { min: rules.typicalMin, max: rules.typicalMax, unit: rules.unit }, factors: [] };
+  // Renal adjustment (when rules define eGFR brackets and eGFR is provided)
+  if (rules.renalAdjusted && renalFunction !== undefined) {
+    factors.push('renal');
+    const renalMax = rules.getRenalAdjustedMax(renalFunction);
+    if (dose > renalMax) {
+      return { valid: false, message: `Exceeds renal-adjusted max for eGFR ${renalFunction}`,
+        suggestedRange: { min: rules.typicalMin, max: renalMax, unit: rules.unit }, factors };
+    }
+  }
+
+  // Absolute max
+  if (dose > rules.absoluteMax) {
+    return { valid: false, message: `Exceeds absolute max ${rules.absoluteMax}${rules.unit}`,
+      suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit },
+      factors: [...factors, 'absolute_max'] };
+  }
+  return { valid: true, message: 'Within range',
+    suggestedRange: { min: rules.typicalMin, max: rules.typicalMax, unit: rules.unit }, factors };
 }
 ```
 
-## Clinical Scoring: NEWS2
-
-National Early Warning Score 2 — standardized assessment of acute illness severity:
+### Clinical Scoring: NEWS2
 
 ```typescript
 interface NEWS2Input {
-  respiratoryRate: number;
-  oxygenSaturation: number;
-  supplementalOxygen: boolean;
-  temperature: number;
-  systolicBP: number;
-  heartRate: number;
+  respiratoryRate: number; oxygenSaturation: number; supplementalOxygen: boolean;
+  temperature: number; systolicBP: number; heartRate: number;
   consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive';
 }
-
 interface NEWS2Result {
   total: number;           // 0-20
   risk: 'low' | 'low-medium' | 'medium' | 'high';
   components: Record<string, number>;
-  escalation: string;      // recommended clinical action
+  escalation: string;
 }
 ```
 
-Scoring tables must match the Royal College of Physicians NEWS2 specification exactly. Any deviation is a patient safety issue.
+Scoring tables must match the Royal College of Physicians specification exactly.
 
-## Alert Severity and UI Behavior
+### Alert Severity and UI Behavior
 
 | Severity | UI Behavior | Clinician Action Required |
 |----------|-------------|--------------------------|
@@ -186,54 +174,74 @@ Scoring tables must match the Royal College of Physicians NEWS2 specification ex
 | Major | Warning banner inline. Orange. | Must acknowledge before proceeding |
 | Minor | Info note inline. Yellow. | Awareness only, no action required |
 
-**Rules:**
-- Critical alerts must NEVER be auto-dismissed
-- Critical alerts must NEVER be toast notifications
-- Override reasons must be stored in the audit trail
-- Alert fatigue is real — only use critical for genuinely dangerous situations
+Critical alerts must NEVER be auto-dismissed or implemented as toast notifications. Override reasons must be stored in the audit trail.
 
-## Testing CDSS (Zero Tolerance for False Negatives)
+### Testing CDSS (Zero Tolerance for False Negatives)
 
 ```typescript
 describe('CDSS — Patient Safety', () => {
-  // Every known interaction pair MUST fire
   INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => {
     it(`detects ${drugA} + ${drugB} (${severity})`, () => {
       const alerts = checkInteractions(drugA, [drugB], []);
       expect(alerts.length).toBeGreaterThan(0);
       expect(alerts[0].severity).toBe(severity);
     });
-
-    // Bidirectional check
     it(`detects ${drugB} + ${drugA} (reverse)`, () => {
       const alerts = checkInteractions(drugB, [drugA], []);
       expect(alerts.length).toBeGreaterThan(0);
     });
   });
-
-  // Dose validation
-  DOSE_RULES.forEach((rule) => {
-    it(`validates ${rule.drug}: ${rule.scenario}`, () => {
-      const result = validateDose(rule.drug, rule.dose, rule.route, rule.weight, rule.age);
-      expect(result.valid).toBe(rule.expectedValid);
-    });
+  it('blocks mg/kg drug when weight is missing', () => {
+    const result = validateDose('gentamicin', 300, 'iv');
+    expect(result.valid).toBe(false);
+    expect(result.factors).toContain('weight_missing');
   });
-
-  // No silent failures
   it('handles malformed drug data gracefully', () => {
     expect(() => checkInteractions('', [], [])).not.toThrow();
-    expect(() => checkInteractions(null as any, [], [])).not.toThrow();
   });
 });
 ```
 
-**Pass criteria: 100%.** A single missed interaction is a patient safety event.
+Pass criteria: 100%. A single missed interaction is a patient safety event.
 
-## Anti-Patterns
+### Anti-Patterns
 
-- ❌ Making CDSS checks optional or skippable without documented reason
-- ❌ Implementing interaction checks as toast notifications
-- ❌ Using `any` types for drug or clinical data
-- ❌ Hardcoding interaction pairs instead of using a maintainable data structure
-- ❌ Testing with mocked data only (must test with real drug names)
-- ❌ Silently catching errors in CDSS engine (must surface failures loudly)
+- Making CDSS checks optional or skippable without documented reason
+- Implementing interaction checks as toast notifications
+- Using `any` types for drug or clinical data
+- Hardcoding interaction pairs instead of using a maintainable data structure
+- Silently catching errors in CDSS engine (must surface failures loudly)
+- Skipping weight-based validation when weight is not available (must block, not pass)
+
+## Examples
+
+### Example 1: Drug Interaction Check
+
+```typescript
+const alerts = checkInteractions('warfarin', ['aspirin', 'metformin'], ['penicillin']);
+// [{ severity: 'critical', pair: ['warfarin', 'aspirin'],
+//    message: 'Increased bleeding risk', recommendation: 'Avoid combination' }]
+```
+
+### Example 2: Dose Validation
+
+```typescript
+const ok = validateDose('paracetamol', 1000, 'oral', 70, 45);
+// { valid: true, suggestedRange: { min: 500, max: 4000, unit: 'mg' } }
+
+const bad = validateDose('paracetamol', 5000, 'oral', 70, 45);
+// { valid: false, message: 'Exceeds absolute max 4000mg' }
+
+const noWeight = validateDose('gentamicin', 300, 'iv');
+// { valid: false, factors: ['weight_missing'] }
+```
+
+### Example 3: NEWS2 Scoring
+
+```typescript
+const result = calculateNEWS2({
+  respiratoryRate: 24, oxygenSaturation: 93, supplementalOxygen: true,
+  temperature: 38.5, systolicBP: 100, heartRate: 110, consciousness: 'voice'
+});
+// { total: 13, risk: 'high', escalation: 'Urgent clinical review. Consider ICU.' }
+```
diff --git a/skills/healthcare-emr-patterns/SKILL.md b/skills/healthcare-emr-patterns/SKILL.md
index a9cc79df..59ac0fd8 100644
--- a/skills/healthcare-emr-patterns/SKILL.md
+++ b/skills/healthcare-emr-patterns/SKILL.md
@@ -12,9 +12,9 @@ rollback: "git revert"
 
 Patterns for building Electronic Medical Record (EMR) and Electronic Health Record (EHR) systems. Prioritizes patient safety, clinical accuracy, and practitioner efficiency.
 
-## When to Activate
+## When to Use
 
-- Building patient encounter workflows (complaint → exam → diagnosis → prescription)
+- Building patient encounter workflows (complaint, exam, diagnosis, prescription)
 - Implementing clinical note-taking (structured + free text + voice-to-text)
 - Designing prescription/medication modules with drug interaction checking
 - Integrating Clinical Decision Support Systems (CDSS)
@@ -22,9 +22,9 @@ Patterns for building Electronic Medical Record (EMR) and Electronic Health Reco
 - Implementing audit trails for clinical data
 - Designing healthcare-accessible UIs for clinical data entry
 
-## Core Principles
+## How It Works
 
-### 1. Patient Safety First
+### Patient Safety First
 
 Every design decision must be evaluated against: "Could this harm a patient?"
 
@@ -33,9 +33,9 @@ Every design decision must be evaluated against: "Could this harm a patient?"
 - Critical vitals MUST trigger escalation workflows
 - No clinical data modification without audit trail
 
-### 2. Single-Page Encounter Flow
+### Single-Page Encounter Flow
 
-Clinical encounters should flow vertically on a single page — no tab switching during patient interaction:
+Clinical encounters should flow vertically on a single page — no tab switching:
 
 ```
 Patient Header (sticky — always visible)
@@ -53,9 +53,7 @@ Encounter Flow (vertical scroll)
 └── 9. Sign / Lock / Print
 ```
 
-### 3. Smart Template System
-
-Build templates for common presentations:
+### Smart Template System
 
 ```typescript
 interface ClinicalTemplate {
@@ -68,9 +66,9 @@ interface ClinicalTemplate {
 }
 ```
 
-**Red flags** in any template must trigger a visible, non-dismissable alert — NOT a toast notification.
+Red flags in any template must trigger a visible, non-dismissable alert — NOT a toast notification.
 
-### 4. Medication Safety Pattern
+### Medication Safety Pattern
 
 ```
 User selects drug
@@ -78,62 +76,87 @@ User selects drug
   → Check encounter medications for interactions
   → Check patient allergies
   → Validate dose against weight/age/renal function
-  → Display alerts (critical = block, major = require override reason)
-  → Log override reason if clinician proceeds
+  → If CRITICAL interaction: BLOCK prescribing entirely
+  → Clinician must document override reason to proceed past a block
+  → If MAJOR interaction: display warning, require acknowledgment
+  → Log all alerts and override reasons in audit trail
 ```
 
-Critical interactions should **block prescribing by default**. The clinician must explicitly override with a documented reason.
+Critical interactions **block prescribing by default**. The clinician must explicitly override with a documented reason stored in the audit trail. The system never silently allows a critical interaction.
 
-### 5. Locked Encounter Pattern
+### Locked Encounter Pattern
 
 Once a clinical encounter is signed:
-- No edits allowed — only addendum
-- Addendum is a new record linked to the original
+- No edits allowed — only an addendum (a separate linked record)
 - Both original and addendum appear in the patient timeline
-- Audit trail captures who signed, when, and any addenda
+- Audit trail captures who signed, when, and any addendum records
 
-## UI Patterns for Clinical Data
+### UI Patterns for Clinical Data
 
-### Vitals Display
+**Vitals Display:** Current values with normal range highlighting (green/yellow/red), trend arrows vs previous, clinical scoring auto-calculated (NEWS2, qSOFA), escalation guidance inline.
 
-- Current values with normal range highlighting (green/yellow/red)
-- Trend arrows comparing to previous measurement
-- Clinical scoring auto-calculated (NEWS2, qSOFA, MEWS)
-- Scoring result displayed inline with escalation guidance
+**Lab Results Display:** Normal range highlighting, previous value comparison, critical values with non-dismissable alert, collection/analysis timestamps, pending orders with expected turnaround.
 
-### Lab Results Display
+**Prescription PDF:** One-click generation with patient demographics, allergies, diagnosis, drug details (generic + brand, dose, route, frequency, duration), clinician signature block.
 
-- Normal range highlighting with institution-specific ranges
-- Previous value comparison (trend)
-- Critical values flagged with non-dismissable alert
-- Timestamp of collection and analysis
-- Pending orders shown with expected turnaround
+### Accessibility for Healthcare
 
-### Prescription PDF
+Healthcare UIs have stricter requirements than typical web apps:
+- 4.5:1 minimum contrast (WCAG AA) — clinicians work in varied lighting
+- Large touch targets (44x44px minimum) — for gloved/rushed interaction
+- Keyboard navigation — for power users entering data rapidly
+- No color-only indicators — always pair color with text/icon (colorblind clinicians)
+- Screen reader labels on all form fields
+- No auto-dismissing toasts for clinical alerts — clinician must actively acknowledge
 
-- One-click generation
-- Patient demographics, allergies, diagnosis
-- Drug name (generic + brand), dose, route, frequency, duration
-- Clinician signature block
-- QR code linking to digital record (optional)
+### Anti-Patterns
 
-## Accessibility for Healthcare
+- Storing clinical data in browser localStorage
+- Silent failures in drug interaction checking
+- Dismissable toasts for critical clinical alerts
+- Tab-based encounter UIs that fragment the clinical workflow
+- Allowing edits to signed/locked encounters
+- Displaying clinical data without audit trail
+- Using `any` type for clinical data structures
 
-Healthcare UIs have stricter accessibility requirements than typical web apps:
+## Examples
 
-- **4.5:1 minimum contrast** (WCAG AA) — clinicians work in varied lighting
-- **Large touch targets** (44x44px minimum) — for gloved/rushed interaction
-- **Keyboard navigation** — for power users entering data rapidly
-- **No color-only indicators** — always pair color with text/icon (colorblind clinicians)
-- **Screen reader labels** on all form fields — for voice-assisted data entry
-- **No auto-dismissing toasts** for clinical alerts — clinician must actively acknowledge
+### Example 1: Patient Encounter Flow
 
-## Anti-Patterns
+```
+Doctor opens encounter for Patient #4521
+  → Sticky header shows: "Rajesh M, 58M, Allergies: Penicillin, Active Meds: Metformin 500mg"
+  → Chief Complaint: selects "Chest Pain" template
+    → Clicks chips: "substernal", "radiating to left arm", "crushing"
+    → Red flag "crushing substernal chest pain" triggers non-dismissable alert
+  → Examination: CVS system — "S1 S2 normal, no murmur"
+  → Vitals: HR 110, BP 90/60, SpO2 94%
+    → NEWS2 auto-calculates: score 8, risk HIGH, escalation alert shown
+  → Diagnosis: searches "ACS" → selects ICD-10 I21.9
+  → Medications: selects Aspirin 300mg
+    → CDSS checks against Metformin: no interaction
+  → Signs encounter → locked, addendum-only from this point
+```
 
-- ❌ Storing clinical data in browser localStorage
-- ❌ Silent failures in drug interaction checking
-- ❌ Dismissable toasts for critical clinical alerts
-- ❌ Tab-based encounter UIs that fragment the clinical workflow
-- ❌ Allowing edits to signed/locked encounters
-- ❌ Displaying clinical data without audit trail
-- ❌ Using `any` type for clinical data structures
+### Example 2: Medication Safety Workflow
+
+```
+Doctor prescribes Warfarin for Patient #4521
+  → CDSS detects: Warfarin + Aspirin = CRITICAL interaction
+  → UI: red non-dismissable modal blocks prescribing
+  → Doctor clicks "Override with reason"
+  → Types: "Benefits outweigh risks — monitored INR protocol"
+  → Override reason + alert stored in audit trail
+  → Prescription proceeds with documented override
+```
+
+### Example 3: Locked Encounter + Addendum
+
+```
+Encounter #E-2024-0891 signed by Dr. Shah at 14:30
+  → All fields locked — no edit buttons visible
+  → "Add Addendum" button available
+  → Dr. Shah clicks addendum, adds: "Lab results received — Troponin elevated"
+  → New record E-2024-0891-A1 linked to original
+  → Timeline shows both: original encounter + addendum with timestamps
+```
diff --git a/skills/healthcare-eval-harness/SKILL.md b/skills/healthcare-eval-harness/SKILL.md
index e65cd23d..b901bb47 100644
--- a/skills/healthcare-eval-harness/SKILL.md
+++ b/skills/healthcare-eval-harness/SKILL.md
@@ -12,7 +12,7 @@ rollback: "git revert"
 
 Automated verification system for healthcare application deployments. A single CRITICAL failure blocks deployment. Patient safety is non-negotiable.
 
-## When to Activate
+## When to Use
 
 - Before any deployment of EMR/EHR applications
 - After modifying CDSS logic (drug interactions, dose validation, scoring)
@@ -21,83 +21,65 @@ Automated verification system for healthcare application deployments. A single C
 - During CI/CD pipeline configuration for healthcare apps
 - After resolving merge conflicts in clinical modules
 
-## Eval Categories
+## How It Works
 
-### 1. CDSS Accuracy (CRITICAL — 100% required)
+The eval harness runs five test categories in order. The first three (CDSS Accuracy, PHI Exposure, Data Integrity) are CRITICAL gates requiring 100% pass rate — a single failure blocks deployment. The remaining two (Clinical Workflow, Integration) are HIGH gates requiring 95%+ pass rate.
 
-Tests all clinical decision support logic:
+Each category maps to a Jest test path pattern. The CI pipeline runs CRITICAL gates with `--bail` (stop on first failure) and enforces coverage thresholds with `--coverage --coverageThreshold`.
 
-- Drug interaction pairs: every known pair must fire an alert
-- Dose validation: out-of-range doses must be flagged
-- Clinical scoring: results must match published specifications
-- No false negatives: a missed alert is a patient safety event
-- No silent failures: malformed input must error, not silently pass
+### Eval Categories
+
+**1. CDSS Accuracy (CRITICAL — 100% required)**
+
+Tests all clinical decision support logic: drug interaction pairs (both directions), dose validation rules, clinical scoring vs published specs, no false negatives, no silent failures.
 
 ```bash
-npx jest --testPathPattern='tests/cdss' --bail --ci
+npx jest --testPathPattern='tests/cdss' --bail --ci --coverage
 ```
 
-### 2. PHI Exposure (CRITICAL — 100% required)
+**2. PHI Exposure (CRITICAL — 100% required)**
 
-Tests for protected health information leaks:
-
-- API error responses contain no PHI
-- Console output contains no patient data
-- URL parameters contain no PHI
-- Browser storage contains no PHI
-- Cross-facility data isolation works (multi-tenant)
-- Unauthenticated requests return zero patient rows
-- Service role keys absent from client bundles
+Tests for protected health information leaks: API error responses, console output, URL parameters, browser storage, cross-facility isolation, unauthenticated access, service role key absence.
 
 ```bash
 npx jest --testPathPattern='tests/security/phi' --bail --ci
 ```
 
-### 3. Data Integrity (CRITICAL — 100% required)
+**3. Data Integrity (CRITICAL — 100% required)**
 
-Tests for clinical data safety:
-
-- Locked encounters cannot be modified
-- Audit trail entries exist for every write operation
-- Cascade deletes are blocked on patient records
-- Concurrent edits trigger conflict resolution
-- No orphaned records across related tables
+Tests clinical data safety: locked encounters, audit trail entries, cascade delete protection, concurrent edit handling, no orphaned records.
 
 ```bash
 npx jest --testPathPattern='tests/data-integrity' --bail --ci
 ```
 
-### 4. Clinical Workflow (HIGH — 95%+ required)
+**4. Clinical Workflow (HIGH — 95%+ required)**
 
-Tests end-to-end clinical workflows:
-
-- Complete encounter flow (complaint → exam → diagnosis → Rx → lock)
-- Template rendering and submission for all clinical templates
-- Medication set population and interaction checking
-- Drug/diagnosis search functionality
-- Prescription PDF generation
-- Red flag alert triggering
+Tests end-to-end flows: encounter lifecycle, template rendering, medication sets, drug/diagnosis search, prescription PDF, red flag alerts.
 
 ```bash
-npx jest --testPathPattern='tests/clinical' --ci
+npx jest --testPathPattern='tests/clinical' --ci 2>&1 | node scripts/check-pass-rate.js 95
 ```
 
-### 5. Integration Compliance (HIGH — 95%+ required)
+**5. Integration Compliance (HIGH — 95%+ required)**
 
-Tests external system integrations:
-
-- HL7 message parsing (v2.x)
-- FHIR resource validation (if applicable)
-- Lab result mapping to correct patients
-- Malformed message handling (no crashes)
+Tests external systems: HL7 message parsing (v2.x), FHIR validation, lab result mapping, malformed message handling.
 
 ```bash
-npx jest --testPathPattern='tests/integration' --ci
+npx jest --testPathPattern='tests/integration' --ci 2>&1 | node scripts/check-pass-rate.js 95
 ```
 
-## CI/CD Integration
+### Pass/Fail Matrix
 
-### GitHub Actions Example
+| Category | Threshold | On Failure |
+|----------|-----------|------------|
+| CDSS Accuracy | 100% | **BLOCK deployment** |
+| PHI Exposure | 100% | **BLOCK deployment** |
+| Data Integrity | 100% | **BLOCK deployment** |
+| Clinical Workflow | 95%+ | WARN, allow with review |
+| Integration | 95%+ | WARN, allow with review |
+
+### CI/CD Integration
 
 ```yaml
 name: Healthcare Safety Gate
@@ -113,9 +95,9 @@ jobs:
           node-version: '20'
       - run: npm ci
 
-      # CRITICAL gates — must pass 100%
+      # CRITICAL gates — 100% required, bail on first failure
       - name: CDSS Accuracy
-        run: npx jest --testPathPattern='tests/cdss' --bail --ci
+        run: npx jest --testPathPattern='tests/cdss' --bail --ci --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
 
       - name: PHI Exposure Check
         run: npx jest --testPathPattern='tests/security/phi' --bail --ci
@@ -123,47 +105,72 @@ jobs:
       - name: Data Integrity
         run: npx jest --testPathPattern='tests/data-integrity' --bail --ci
 
-      # HIGH gates — must pass 95%+
+      # HIGH gates — 95%+ required, custom threshold check
       - name: Clinical Workflows
-        run: npx jest --testPathPattern='tests/clinical' --ci
+        run: |
+          RESULT=$(npx jest --testPathPattern='tests/clinical' --ci --json 2>/dev/null)
+          PASSED=$(echo $RESULT | jq '.numPassedTests')
+          TOTAL=$(echo $RESULT | jq '.numTotalTests')
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}%"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Clinical workflow pass rate ${RATE}% below 95% threshold"
+          fi
 
       - name: Integration Compliance
-        run: npx jest --testPathPattern='tests/integration' --ci
+        run: |
+          RESULT=$(npx jest --testPathPattern='tests/integration' --ci --json 2>/dev/null)
+          PASSED=$(echo $RESULT | jq '.numPassedTests')
+          TOTAL=$(echo $RESULT | jq '.numTotalTests')
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}%"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Integration pass rate ${RATE}% below 95% threshold"
+          fi
 ```
 
-## Pass/Fail Matrix
+### Anti-Patterns
 
-| Category | Threshold | On Failure |
-|----------|-----------|------------|
-| CDSS Accuracy | 100% | **BLOCK deployment** |
-| PHI Exposure | 100% | **BLOCK deployment** |
-| Data Integrity | 100% | **BLOCK deployment** |
-| Clinical Workflow | 95%+ | WARN, allow with review |
-| Integration | 95%+ | WARN, allow with review |
+- Skipping CDSS tests "because they passed last time"
+- Setting CRITICAL thresholds below 100%
+- Using `--no-bail` on CRITICAL test suites
+- Mocking the CDSS engine in integration tests (must test real logic)
+- Allowing deployments when safety gate is red
+- Running tests without `--coverage` on CDSS suites
 
-## Eval Report Format
+## Examples
+
+### Example 1: Run All Critical Gates Locally
+
+```bash
+npx jest --testPathPattern='tests/cdss' --bail --ci --coverage && \
+npx jest --testPathPattern='tests/security/phi' --bail --ci && \
+npx jest --testPathPattern='tests/data-integrity' --bail --ci
+```
+
+### Example 2: Check HIGH Gate Pass Rate
+
+```bash
+npx jest --testPathPattern='tests/clinical' --ci --json | \
+  jq '{passed: .numPassedTests, total: .numTotalTests, rate: (.numPassedTests/.numTotalTests*100)}'
+# Expected: { "passed": 21, "total": 22, "rate": 95.45 }
+```
+
+### Example 3: Eval Report
 
 ```
-## Healthcare Eval: [date] [commit]
+## Healthcare Eval: 2026-03-27 [commit abc1234]
 
-### Patient Safety: PASS / FAIL
+### Patient Safety: PASS
 
 | Category | Tests | Pass | Fail | Status |
 |----------|-------|------|------|--------|
-| CDSS Accuracy | N | N | 0 | PASS |
-| PHI Exposure | N | N | 0 | PASS |
-| Data Integrity | N | N | 0 | PASS |
-| Clinical Workflow | N | N | N | 95%+ |
-| Integration | N | N | N | 95%+ |
+| CDSS Accuracy | 39 | 39 | 0 | PASS |
+| PHI Exposure | 8 | 8 | 0 | PASS |
+| Data Integrity | 12 | 12 | 0 | PASS |
+| Clinical Workflow | 22 | 21 | 1 | 95.5% PASS |
+| Integration | 6 | 6 | 0 | PASS |
 
-### Coverage: X% (target: 80%+)
-### Verdict: SAFE TO DEPLOY / BLOCKED
+### Coverage: 84% (target: 80%+)
+### Verdict: SAFE TO DEPLOY
 ```
-
-## Anti-Patterns
-
-- ❌ Skipping CDSS tests "because they passed last time"
-- ❌ Setting CRITICAL thresholds below 100%
-- ❌ Using `--no-bail` on CRITICAL test suites
-- ❌ Mocking the CDSS engine in integration tests (must test real logic)
-- ❌ Allowing deployments when safety gate is red
diff --git a/skills/healthcare-phi-compliance/SKILL.md b/skills/healthcare-phi-compliance/SKILL.md
index b84de1c6..ddd1eb2e 100644
--- a/skills/healthcare-phi-compliance/SKILL.md
+++ b/skills/healthcare-phi-compliance/SKILL.md
@@ -12,7 +12,7 @@ rollback: "git revert"
 
 Patterns for protecting patient data, clinician data, and financial data in healthcare applications. Applicable to HIPAA (US), DISHA (India), GDPR (EU), and general healthcare data protection.
 
-## When to Activate
+## When to Use
 
 - Building any feature that touches patient records
 - Implementing access control or authentication for clinical systems
@@ -22,124 +22,37 @@ Patterns for protecting patient data, clinician data, and financial data in heal
 - Reviewing code for data exposure vulnerabilities
 - Setting up Row-Level Security (RLS) for multi-tenant healthcare systems
 
-## Data Classification
+## How It Works
 
-### PHI (Protected Health Information)
+Healthcare data protection operates on three layers: **classification** (what is sensitive), **access control** (who can see it), and **audit** (who did see it).
 
-Any data that can identify a patient AND relates to their health:
+### Data Classification
 
-- Patient name, date of birth, address, phone, email
-- National ID numbers (SSN, Aadhaar, NHS number)
-- Medical record numbers
-- Diagnoses, medications, lab results, imaging
-- Insurance policy and claim details
-- Appointment and admission records
-- Any combination of the above
+**PHI (Protected Health Information)** — any data that can identify a patient AND relates to their health: patient name, date of birth, address, phone, email, national ID numbers (SSN, Aadhaar, NHS number), medical record numbers, diagnoses, medications, lab results, imaging, insurance policy and claim details, appointment and admission records, or any combination of the above.
 
-### PII (Personally Identifiable Information)
+**PII (Non-patient-sensitive data)** in healthcare systems: clinician/staff personal details, doctor fee structures and payout amounts, employee salary and bank details, vendor payment information.
 
-Non-patient sensitive data in healthcare systems:
-
-- Clinician/staff personal details
-- Doctor fee structures and payout amounts
-- Employee salary and bank details
-- Vendor payment information
-
-## Access Control Patterns
-
-### Row-Level Security (Supabase/PostgreSQL)
+### Access Control: Row-Level Security
 
 ```sql
--- Enable RLS on every PHI table
 ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
 
--- Scope access by facility/centre
+-- Scope access by facility
 CREATE POLICY "staff_read_own_facility"
-  ON patients FOR SELECT
-  TO authenticated
-  USING (
-    facility_id IN (
-      SELECT facility_id FROM staff_assignments
-      WHERE user_id = auth.uid()
-      AND role IN ('doctor', 'nurse', 'lab_tech', 'admin')
-    )
-  );
-
--- Audit log: insert-only (no updates, no deletes)
-CREATE POLICY "audit_insert_only"
-  ON audit_log FOR INSERT
-  TO authenticated
-  WITH CHECK (user_id = auth.uid());
+  ON patients FOR SELECT TO authenticated
+  USING (facility_id IN (
+    SELECT facility_id FROM staff_assignments
+    WHERE user_id = auth.uid() AND role IN ('doctor','nurse','lab_tech','admin')
+  ));
 
+-- Audit log: insert-only (tamper-proof)
+CREATE POLICY "audit_insert_only" ON audit_log FOR INSERT
+  TO authenticated WITH CHECK (user_id = auth.uid());
 CREATE POLICY "audit_no_modify" ON audit_log FOR UPDATE USING (false);
 CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false);
 ```
 
-### API Authentication
-
-- Every API route handling PHI MUST require authentication
-- Use short-lived tokens (JWT with 15-min expiry for clinical sessions)
-- Implement session timeout (auto-logout after inactivity)
-- Log every PHI access with user ID, timestamp, and resource accessed
-
-## Common Leak Vectors (Check Every Deployment)
-
-### 1. Error Messages
-
-```typescript
-// ❌ BAD — leaks PHI in error
-throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);
-
-// ✅ GOOD — generic error, log details server-side
-logger.error('Patient lookup failed', { patientId, facilityId });
-throw new Error('Record not found');
-```
-
-### 2. Console Output
-
-```typescript
-// ❌ BAD
-console.log('Processing patient:', patient);
-
-// ✅ GOOD
-console.log('Processing patient:', patient.id); // ID only
-```
-
-### 3. URL Parameters
-
-```
-❌ /patients?name=John+Doe&dob=1990-01-01
-✅ /patients/uuid-here  (lookup by opaque ID)
-```
-
-### 4. Browser Storage
-
-```typescript
-// ❌ NEVER store PHI in localStorage/sessionStorage
-localStorage.setItem('currentPatient', JSON.stringify(patient));
-
-// ✅ Keep PHI in memory only, fetch on demand
-const [patient, setPatient] = useState<Patient | null>(null);
-```
-
-### 5. Service Role Keys
-
-```typescript
-// ❌ NEVER use service_role key in client-side code
-const supabase = createClient(url, SUPABASE_SERVICE_ROLE_KEY);
-
-// ✅ ALWAYS use anon key — let RLS enforce access
-const supabase = createClient(url, SUPABASE_ANON_KEY);
-```
-
-### 6. Logs and Monitoring
-
-- Never log full patient records
-- Log patient IDs, not names
-- Sanitize stack traces before sending to error tracking services
-- Ensure log storage itself is access-controlled
-
-## Audit Trail Requirements
+### Audit Trail
 
 Every PHI access or modification must be logged:
 
@@ -151,35 +64,85 @@ interface AuditEntry {
   action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
   resource_type: string;
   resource_id: string;
-  changes?: { before: object; after: object }; // for updates
+  changes?: { before: object; after: object };
   ip_address: string;
   session_id: string;
 }
 ```
 
-## Database Schema Tagging
+### Common Leak Vectors
 
-Mark PHI/PII columns at the schema level so automated tools can identify them:
+**Error messages:** Never include patient-identifying data in error messages thrown to the client. Log details server-side only.
+
+**Console output:** Never log full patient objects. Use opaque internal record IDs (UUIDs) — not medical record numbers, national IDs, or names.
+
+**URL parameters:** Never put patient-identifying data in query strings or path segments that could appear in logs or browser history. Use opaque UUIDs only.
+
+**Browser storage:** Never store PHI in localStorage or sessionStorage. Keep PHI in memory only, fetch on demand.
+
+**Service role keys:** Never use the service_role key in client-side code. Always use the anon/publishable key and let RLS enforce access.
+
+**Logs and monitoring:** Never log full patient records. Use opaque record IDs only (not medical record numbers). Sanitize stack traces before sending to error tracking services.
+
+### Database Schema Tagging
+
+Mark PHI/PII columns at the schema level:
 
 ```sql
 COMMENT ON COLUMN patients.name IS 'PHI: patient_name';
 COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth';
 COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id';
 COMMENT ON COLUMN doctor_payouts.amount IS 'PII: financial';
-COMMENT ON COLUMN employees.salary IS 'PII: financial';
 ```
 
-## Deployment Checklist
+### Deployment Checklist
 
-Before every deployment of a healthcare application:
+Before every deployment:
+- No PHI in error messages or stack traces
+- No PHI in console.log/console.error
+- No PHI in URL parameters
+- No PHI in browser storage
+- No service_role key in client code
+- RLS enabled on all PHI/PII tables
+- Audit trail for all data modifications
+- Session timeout configured
+- API authentication on all PHI endpoints
+- Cross-facility data isolation verified
 
-- [ ] No PHI in error messages or stack traces
-- [ ] No PHI in console.log/console.error
-- [ ] No PHI in URL parameters
-- [ ] No PHI in browser storage
-- [ ] No service_role key in client code
-- [ ] RLS enabled on all PHI/PII tables
-- [ ] Audit trail for all data modifications
-- [ ] Session timeout configured
-- [ ] API authentication on all PHI endpoints
-- [ ] Cross-facility data isolation verified
+## Examples
+
+### Example 1: Safe vs Unsafe Error Handling
+
+```typescript
+// BAD — leaks PHI in error
+throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);
+
+// GOOD — generic error, details logged server-side with opaque IDs only
+logger.error('Patient lookup failed', { recordId: patient.id, facilityId });
+throw new Error('Record not found');
+```
+
+### Example 2: RLS Policy for Multi-Facility Isolation
+
+```sql
+-- Doctor at Facility A cannot see Facility B patients
+CREATE POLICY "facility_isolation"
+  ON patients FOR SELECT TO authenticated
+  USING (facility_id IN (
+    SELECT facility_id FROM staff_assignments WHERE user_id = auth.uid()
+  ));
+
+-- Test: login as doctor-facility-a, query facility-b patients
+-- Expected: 0 rows returned
+```
+
+### Example 3: Safe Logging
+
+```typescript
+// BAD — logs identifiable patient data
+console.log('Processing patient:', patient);
+
+// GOOD — logs only opaque internal record ID
+console.log('Processing record:', patient.id);
+// Note: even patient.id should be an opaque UUID, not a medical record number
+```