From 63737544a18ae01273b8dacd3d578757df8d05e8 Mon Sep 17 00:00:00 2001 From: "Dr. Keyur Patel" Date: Fri, 27 Mar 2026 03:17:49 +0000 Subject: [PATCH] feat: add healthcare domain skills and agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New skills: - healthcare-emr-patterns: EMR/EHR encounter workflows, smart templates, medication safety, clinical UI patterns - healthcare-phi-compliance: PHI/PII protection patterns, RLS templates, leak vector checklist, audit trail patterns - healthcare-cdss-patterns: Drug interaction checking, dose validation, clinical scoring (NEWS2/qSOFA), alert severity - healthcare-eval-harness: Patient safety CI/CD gate — CDSS accuracy, PHI exposure, data integrity, clinical workflows New agent: - healthcare-reviewer: Clinical safety reviewer for CDSS accuracy, PHI compliance, medical data integrity All patterns are generalized and framework-agnostic. Applicable to any health-tech stack. Origin: Health1 Super Speciality Hospitals, Ahmedabad, India. --- agents/healthcare-reviewer.md | 83 ++++++++ skills/healthcare-cdss-patterns/SKILL.md | 239 ++++++++++++++++++++++ skills/healthcare-emr-patterns/SKILL.md | 139 +++++++++++++ skills/healthcare-eval-harness/SKILL.md | 169 +++++++++++++++ skills/healthcare-phi-compliance/SKILL.md | 185 +++++++++++++++++ 5 files changed, 815 insertions(+) create mode 100644 agents/healthcare-reviewer.md create mode 100644 skills/healthcare-cdss-patterns/SKILL.md create mode 100644 skills/healthcare-emr-patterns/SKILL.md create mode 100644 skills/healthcare-eval-harness/SKILL.md create mode 100644 skills/healthcare-phi-compliance/SKILL.md diff --git a/agents/healthcare-reviewer.md b/agents/healthcare-reviewer.md new file mode 100644 index 00000000..94e84bcf --- /dev/null +++ b/agents/healthcare-reviewer.md @@ -0,0 +1,83 @@ +--- +name: healthcare-reviewer +description: Reviews healthcare application code for clinical safety, CDSS accuracy, PHI compliance, and medical data integrity. Specialized for EMR/EHR, clinical decision support, and health information systems. +tools: ["Read", "Grep", "Glob"] +model: opus +--- + +# Healthcare Reviewer — Clinical Safety & PHI Compliance + +You are a clinical informatics reviewer for healthcare software. Patient safety is your top priority. You review code for clinical accuracy, data protection, and regulatory compliance. + +## Your Responsibilities + +1. **CDSS accuracy** — Verify drug interaction logic, dose validation rules, and clinical scoring implementations match published medical standards +2. **PHI/PII protection** — Scan for patient data exposure in logs, errors, responses, URLs, and client storage +3. **Clinical data integrity** — Ensure audit trails, locked records, and cascade protection +4. **Medical data correctness** — Verify ICD-10/SNOMED mappings, lab reference ranges, and drug database entries +5. **Integration compliance** — Validate HL7/FHIR message handling and error recovery + +## Critical Checks + +### CDSS Engine + +- [ ] All drug interaction pairs produce correct alerts (both directions) +- [ ] Dose validation rules fire on out-of-range values +- [ ] Clinical scoring matches published specification (NEWS2 = Royal College of Physicians, qSOFA = Sepsis-3) +- [ ] No false negatives (missed interaction = patient safety event) +- [ ] Malformed inputs produce errors, NOT silent passes + +### PHI Protection + +- [ ] No patient data in `console.log`, `console.error`, or error messages +- [ ] No PHI in URL parameters or query strings +- [ ] No PHI in browser localStorage/sessionStorage +- [ ] No `service_role` key in client-side code +- [ ] RLS enabled on all tables with patient data +- [ ] Cross-facility data isolation verified + +### Clinical Workflow + +- [ ] Encounter lock prevents edits (addendum only) +- [ ] Audit trail entry on every create/read/update/delete of clinical data +- [ ] Critical alerts are non-dismissable (not toast notifications) +- [ ] Override reasons logged when clinician proceeds past critical alert +- [ ] Red flag symptoms trigger visible alerts + +### Data Integrity + +- [ ] No CASCADE DELETE on patient records +- [ ] Concurrent edit detection (optimistic locking or conflict resolution) +- [ ] No orphaned records across clinical tables +- [ ] Timestamps use consistent timezone + +## Output Format + +``` +## Healthcare Review: [module/feature] + +### Patient Safety Impact: [CRITICAL / HIGH / MEDIUM / LOW / NONE] + +### Clinical Accuracy +- CDSS: [checks passed/failed] +- Drug DB: [verified/issues] +- Scoring: [matches spec/deviates] + +### PHI Compliance +- Exposure vectors checked: [list] +- Issues found: [list or none] + +### Issues +1. [PATIENT SAFETY / CLINICAL / PHI / TECHNICAL] Description + - Impact: [potential harm or exposure] + - Fix: [required change] + +### Verdict: [SAFE TO DEPLOY / NEEDS FIXES / BLOCK — PATIENT SAFETY RISK] +``` + +## Rules + +- When in doubt about clinical accuracy, flag as NEEDS REVIEW — never approve uncertain clinical logic +- A single missed drug interaction is worse than a hundred false alarms +- PHI exposure is always CRITICAL severity, regardless of how small the leak +- Never approve code that silently catches CDSS errors diff --git a/skills/healthcare-cdss-patterns/SKILL.md b/skills/healthcare-cdss-patterns/SKILL.md new file mode 100644 index 00000000..00863466 --- /dev/null +++ b/skills/healthcare-cdss-patterns/SKILL.md @@ -0,0 +1,239 @@ +--- +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" +observe: "PostToolUse" +feedback: "manual" +rollback: "git revert" +--- + +# 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 Activate + +- 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 + +## Architecture + +``` +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) +``` + +**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 + +```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; + 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 + }); + } + } + + // Check drug-allergy interactions + 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' + }); + } + } + + // Sort by severity (critical first) + 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. Store once, check both directions. + +## 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) +} + +function validateDose( + drug: string, + dose: number, + route: 'oral' | 'iv' | 'im' | 'sc' | 'topical', + patientWeight?: number, + patientAge?: number, + renalFunction?: number // eGFR +): DoseValidationResult { + const rules = getDoseRules(drug, route); + if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] }; + + // Weight-based dosing + if (rules.weightBased && patientWeight) { + 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'] + }; + } + } + + // 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'] + }; + } + + 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: + +```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; + escalation: string; // recommended clinical action +} +``` + +Scoring tables must match the Royal College of Physicians NEWS2 specification exactly. Any deviation is a patient safety issue. + +## 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 | + +**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 + +## 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); + }); + }); + + // 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. + +## 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) diff --git a/skills/healthcare-emr-patterns/SKILL.md b/skills/healthcare-emr-patterns/SKILL.md new file mode 100644 index 00000000..a9cc79df --- /dev/null +++ b/skills/healthcare-emr-patterns/SKILL.md @@ -0,0 +1,139 @@ +--- +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" +observe: "PostToolUse" +feedback: "manual" +rollback: "git revert" +--- + +# 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 Activate + +- 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 + +## Core Principles + +### 1. 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 + +### 2. Single-Page Encounter Flow + +Clinical encounters should flow vertically on a single page — no tab switching during patient interaction: + +``` +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 +``` + +### 3. Smart Template System + +Build templates for common presentations: + +```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. + +### 4. 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 + → Display alerts (critical = block, major = require override reason) + → Log override reason if clinician proceeds +``` + +Critical interactions should **block prescribing by default**. The clinician must explicitly override with a documented reason. + +### 5. Locked Encounter Pattern + +Once a clinical encounter is signed: +- No edits allowed — only addendum +- Addendum is a new record linked to the original +- Both original and addendum appear in the patient timeline +- Audit trail captures who signed, when, and any addenda + +## UI Patterns for Clinical Data + +### Vitals Display + +- 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 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 + +### Prescription PDF + +- 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) + +## Accessibility for Healthcare + +Healthcare UIs have stricter accessibility 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 — for voice-assisted data entry +- **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 diff --git a/skills/healthcare-eval-harness/SKILL.md b/skills/healthcare-eval-harness/SKILL.md new file mode 100644 index 00000000..e65cd23d --- /dev/null +++ b/skills/healthcare-eval-harness/SKILL.md @@ -0,0 +1,169 @@ +--- +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" +observe: "PostToolUse" +feedback: "manual" +rollback: "git revert" +--- + +# Healthcare Eval Harness — Patient Safety Verification + +Automated verification system for healthcare application deployments. A single CRITICAL failure blocks deployment. Patient safety is non-negotiable. + +## When to Activate + +- 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 + +## Eval Categories + +### 1. CDSS Accuracy (CRITICAL — 100% required) + +Tests all clinical decision support logic: + +- 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 + +```bash +npx jest --testPathPattern='tests/cdss' --bail --ci +``` + +### 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 + +```bash +npx jest --testPathPattern='tests/security/phi' --bail --ci +``` + +### 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 + +```bash +npx jest --testPathPattern='tests/data-integrity' --bail --ci +``` + +### 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 + +```bash +npx jest --testPathPattern='tests/clinical' --ci +``` + +### 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) + +```bash +npx jest --testPathPattern='tests/integration' --ci +``` + +## CI/CD Integration + +### GitHub Actions Example + +```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 — must pass 100% + - name: CDSS Accuracy + run: npx jest --testPathPattern='tests/cdss' --bail --ci + + - 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 — must pass 95%+ + - name: Clinical Workflows + run: npx jest --testPathPattern='tests/clinical' --ci + + - name: Integration Compliance + run: npx jest --testPathPattern='tests/integration' --ci +``` + +## 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 | + +## Eval Report Format + +``` +## Healthcare Eval: [date] [commit] + +### Patient Safety: PASS / FAIL + +| 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%+ | + +### Coverage: X% (target: 80%+) +### Verdict: SAFE TO DEPLOY / BLOCKED +``` + +## 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 new file mode 100644 index 00000000..b84de1c6 --- /dev/null +++ b/skills/healthcare-phi-compliance/SKILL.md @@ -0,0 +1,185 @@ +--- +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" +observe: "PostToolUse" +feedback: "manual" +rollback: "git revert" +--- + +# 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 Activate + +- 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 + +## 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 +- Any combination of the above + +### PII (Personally Identifiable 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) + +```sql +-- Enable RLS on every PHI table +ALTER TABLE patients ENABLE ROW LEVEL SECURITY; + +-- Scope access by facility/centre +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()); + +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(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 + +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 }; // for updates + ip_address: string; + session_id: string; +} +``` + +## Database Schema Tagging + +Mark PHI/PII columns at the schema level so automated tools can identify them: + +```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 + +Before every deployment of a healthcare application: + +- [ ] 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