Merge pull request #955 from drkeyurpatel-wq/feat/healthcare-patterns

feat: Healthcare domain — 4 skills + 1 agent for health-tech applications
2026-03-30 13:43:26 +08:00 · 2026-03-28 23:25:30 -04:00
parent eeeea506a6 9b24bedf85
commit c5e3658ba6
5 changed files with 814 additions and 0 deletions
--- a/skills/healthcare-cdss-patterns/SKILL.md
+++ b/skills/healthcare-cdss-patterns/SKILL.md
@@ -0,0 +1,245 @@
+---
+name: healthcare-cdss-patterns
+description: Clinical Decision Support System (CDSS) development patterns. Drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), alert severity classification, and integration into EMR workflows.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare CDSS Development Patterns
+
+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 Use
+
+- Implementing drug interaction checking
+- Building dose validation engines
+- Implementing clinical scoring systems (NEWS2, qSOFA, APACHE, GCS)
+- Designing alert systems for abnormal clinical values
+- Building medication order entry with safety checks
+- Integrating lab result interpretation with clinical context
+
+## 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
+  ↓ (user enters data)
+CDSS Engine (pure functions, no side effects)
+  ├── Drug Interaction Checker
+  ├── Dose Validator
+  ├── Clinical Scoring (NEWS2, qSOFA, etc.)
+  └── Alert Classifier
+  ↓ (returns alerts)
+EMR UI (displays alerts inline, blocks if critical)
+```
+
+### Drug Interaction Checking
+
+```typescript
+interface DrugInteractionPair {
+  drugA: string;           // generic name
+  drugB: string;           // generic name
+  severity: 'critical' | 'major' | 'minor';
+  mechanism: string;
+  clinicalEffect: string;
+  recommendation: string;
+}
+
+function checkInteractions(
+  newDrug: string,
+  currentMedications: string[],
+  allergyList: string[]
+): InteractionAlert[] {
+  if (!newDrug) return [];
+  const alerts: InteractionAlert[] = [];
+  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 });
+    }
+  }
+  for (const allergy of allergyList) {
+    if (isCrossReactive(newDrug, allergy)) {
+      alerts.push({ severity: 'critical', pair: [newDrug, allergy],
+        message: `Cross-reactivity with documented allergy: ${allergy}`,
+        recommendation: 'Do not prescribe without allergy consultation' });
+    }
+  }
+  return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
+}
+```
+
+Interaction pairs must be **bidirectional**: if Drug A interacts with Drug B, then Drug B interacts with Drug A.
+
+### Dose Validation
+
+```typescript
+interface DoseValidationResult {
+  valid: boolean;
+  message: string;
+  suggestedRange: { min: number; max: number; unit: string } | null;
+  factors: string[];
+}
+
+function validateDose(
+  drug: string,
+  dose: number,
+  route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',
+  patientWeight?: number,
+  patientAge?: number,
+  renalFunction?: number
+): DoseValidationResult {
+  const rules = getDoseRules(drug, route);
+  if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };
+  const factors: string[] = [];
+
+  // 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 exceeds max for ${patientWeight}kg`,
+        suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };
+    }
+  }
+
+  // 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 };
+    }
+  }
+
+  // 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
+
+```typescript
+interface NEWS2Input {
+  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;
+}
+```
+
+Scoring tables must match the Royal College of Physicians specification exactly.
+
+### Alert Severity and UI Behavior
+
+| Severity | UI Behavior | Clinician Action Required |
+|----------|-------------|--------------------------|
+| Critical | Block action. Non-dismissable modal. Red. | Must document override reason to proceed |
+| Major | Warning banner inline. Orange. | Must acknowledge before proceeding |
+| Minor | Info note inline. Yellow. | Awareness only, no action required |
+
+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)
+
+```typescript
+describe('CDSS — Patient Safety', () => {
+  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);
+    });
+    it(`detects ${drugB} + ${drugA} (reverse)`, () => {
+      const alerts = checkInteractions(drugB, [drugA], []);
+      expect(alerts.length).toBeGreaterThan(0);
+    });
+  });
+  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');
+  });
+  it('handles malformed drug data gracefully', () => {
+    expect(() => checkInteractions('', [], [])).not.toThrow();
+  });
+});
+```
+
+Pass criteria: 100%. A single missed interaction is a patient safety event.
+
+### 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
+- 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.' }
+```
--- a/skills/healthcare-emr-patterns/SKILL.md
+++ b/skills/healthcare-emr-patterns/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: healthcare-emr-patterns
+description: EMR/EHR development patterns for healthcare applications. Clinical safety, encounter workflows, prescription generation, clinical decision support integration, and accessibility-first UI for medical data entry.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare EMR Development Patterns
+
+Patterns for building Electronic Medical Record (EMR) and Electronic Health Record (EHR) systems. Prioritizes patient safety, clinical accuracy, and practitioner efficiency.
+
+## When to Use
+
+- 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)
+- Building lab result displays with reference range highlighting
+- Implementing audit trails for clinical data
+- Designing healthcare-accessible UIs for clinical data entry
+
+## How It Works
+
+### Patient Safety First
+
+Every design decision must be evaluated against: "Could this harm a patient?"
+
+- Drug interactions MUST alert, not silently pass
+- Abnormal lab values MUST be visually flagged
+- Critical vitals MUST trigger escalation workflows
+- No clinical data modification without audit trail
+
+### Single-Page Encounter Flow
+
+Clinical encounters should flow vertically on a single page — no tab switching:
+
+```
+Patient Header (sticky — always visible)
+├── Demographics, allergies, active medications
+│
+Encounter Flow (vertical scroll)
+├── 1. Chief Complaint (structured templates + free text)
+├── 2. History of Present Illness
+├── 3. Physical Examination (system-wise)
+├── 4. Vitals (auto-trigger clinical scoring)
+├── 5. Diagnosis (ICD-10/SNOMED search)
+├── 6. Medications (drug DB + interaction check)
+├── 7. Investigations (lab/radiology orders)
+├── 8. Plan & Follow-up
+└── 9. Sign / Lock / Print
+```
+
+### Smart Template System
+
+```typescript
+interface ClinicalTemplate {
+  id: string;
+  name: string;             // e.g., "Chest Pain"
+  chips: string[];          // clickable symptom chips
+  requiredFields: string[]; // mandatory data points
+  redFlags: string[];       // triggers non-dismissable alert
+  icdSuggestions: string[]; // pre-mapped diagnosis codes
+}
+```
+
+Red flags in any template must trigger a visible, non-dismissable alert — NOT a toast notification.
+
+### Medication Safety Pattern
+
+```
+User selects drug
+  → Check current medications for interactions
+  → Check encounter medications for interactions
+  → Check patient allergies
+  → Validate dose against weight/age/renal function
+  → 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 **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.
+
+### Locked Encounter Pattern
+
+Once a clinical encounter is signed:
+- 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 addendum records
+
+### UI Patterns for Clinical Data
+
+**Vitals Display:** Current values with normal range highlighting (green/yellow/red), trend arrows vs previous, clinical scoring auto-calculated (NEWS2, qSOFA), escalation guidance inline.
+
+**Lab Results Display:** Normal range highlighting, previous value comparison, critical values with non-dismissable alert, collection/analysis timestamps, pending orders with expected turnaround.
+
+**Prescription PDF:** One-click generation with patient demographics, allergies, diagnosis, drug details (generic + brand, dose, route, frequency, duration), clinician signature block.
+
+### Accessibility for Healthcare
+
+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
+
+### Anti-Patterns
+
+- 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
+
+## Examples
+
+### Example 1: Patient Encounter Flow
+
+```
+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
+```
+
+### 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
+```
--- a/skills/healthcare-eval-harness/SKILL.md
+++ b/skills/healthcare-eval-harness/SKILL.md
@@ -0,0 +1,182 @@
+---
+name: healthcare-eval-harness
+description: Patient safety evaluation harness for healthcare application deployments. Automated test suites for CDSS accuracy, PHI exposure, clinical workflow integrity, and integration compliance. Blocks deployments on safety failures.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare Eval Harness — Patient Safety Verification
+
+Automated verification system for healthcare application deployments. A single CRITICAL failure blocks deployment. Patient safety is non-negotiable.
+
+> **Note:** Examples use Jest as the reference test runner. Adapt commands for your framework (Vitest, pytest, PHPUnit, etc.) — the test categories and pass thresholds are framework-agnostic.
+
+## When to Use
+
+- Before any deployment of EMR/EHR applications
+- After modifying CDSS logic (drug interactions, dose validation, scoring)
+- After changing database schemas that touch patient data
+- After modifying authentication or access control
+- During CI/CD pipeline configuration for healthcare apps
+- After resolving merge conflicts in clinical modules
+
+## How It Works
+
+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.
+
+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`.
+
+### 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 --coverage
+```
+
+**2. PHI Exposure (CRITICAL — 100% required)**
+
+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)**
+
+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)**
+
+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 2>&1 | node scripts/check-pass-rate.js 95
+```
+
+**5. Integration Compliance (HIGH — 95%+ required)**
+
+Tests external systems: HL7 message parsing (v2.x), FHIR validation, lab result mapping, malformed message handling.
+
+```bash
+npx jest --testPathPattern='tests/integration' --ci 2>&1 | node scripts/check-pass-rate.js 95
+```
+
+### Pass/Fail Matrix
+
+| 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
+on: [push, pull_request]
+
+jobs:
+  safety-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+
+      # CRITICAL gates — 100% required, bail on first failure
+      - name: CDSS Accuracy
+        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
+
+      - name: Data Integrity
+        run: npx jest --testPathPattern='tests/data-integrity' --bail --ci
+
+      # HIGH gates — 95%+ required, custom threshold check
+      # HIGH gates — 95%+ required
+      - name: Clinical Workflows
+        run: |
+          RESULT=$(npx jest --testPathPattern='tests/clinical' --ci --json 2>&1) || true
+          TOTAL=$(echo "$RESULT" | jq '.numTotalTests // 0')
+          PASSED=$(echo "$RESULT" | jq '.numPassedTests // 0')
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "::error::No clinical tests found"; exit 1
+          fi
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Clinical pass rate ${RATE}% below 95%"
+          fi
+
+      - name: Integration Compliance
+        run: |
+          RESULT=$(npx jest --testPathPattern='tests/integration' --ci --json 2>&1) || true
+          TOTAL=$(echo "$RESULT" | jq '.numTotalTests // 0')
+          PASSED=$(echo "$RESULT" | jq '.numPassedTests // 0')
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "::error::No integration tests found"; exit 1
+          fi
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Integration pass rate ${RATE}% below 95%"
+          fi
+```
+
+### 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
+- Running tests without `--coverage` on CDSS suites
+
+## 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: 2026-03-27 [commit abc1234]
+
+### Patient Safety: PASS
+
+| Category | Tests | Pass | Fail | Status |
+|----------|-------|------|------|--------|
+| 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: 84% (target: 80%+)
+### Verdict: SAFE TO DEPLOY
+```
--- a/skills/healthcare-phi-compliance/SKILL.md
+++ b/skills/healthcare-phi-compliance/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: healthcare-phi-compliance
+description: Protected Health Information (PHI) and Personally Identifiable Information (PII) compliance patterns for healthcare applications. Covers data classification, access control, audit trails, encryption, and common leak vectors.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare PHI/PII Compliance Patterns
+
+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 Use
+
+- Building any feature that touches patient records
+- Implementing access control or authentication for clinical systems
+- Designing database schemas for healthcare data
+- Building APIs that return patient or clinician data
+- Implementing audit trails or logging
+- Reviewing code for data exposure vulnerabilities
+- Setting up Row-Level Security (RLS) for multi-tenant healthcare systems
+
+## How It Works
+
+Healthcare data protection operates on three layers: **classification** (what is sensitive), **access control** (who can see it), and **audit** (who did see it).
+
+### Data Classification
+
+**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 (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: Row-Level Security
+
+```sql
+ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
+
+-- 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 (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);
+```
+
+### Audit Trail
+
+Every PHI access or modification must be logged:
+
+```typescript
+interface AuditEntry {
+  timestamp: string;
+  user_id: string;
+  patient_id: string;
+  action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
+  resource_type: string;
+  resource_id: string;
+  changes?: { before: object; after: object };
+  ip_address: string;
+  session_id: string;
+}
+```
+
+### Common Leak Vectors
+
+**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';
+```
+
+### Deployment Checklist
+
+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
+
+## 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
+```