zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: address all CodeRabbit + Cubic review comments on PR #955

Browse Source 
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)
This commit is contained in:
Dr. Keyur Patel
2026-03-27 03:54:20 +00:00
parent 63737544a1
commit e3f2bda9fc
4 changed files with 356 additions and 355 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
skills/healthcare-cdss-patterns/SKILL.md
View File

@@ -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. 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 - Implementing drug interaction checking
- Building dose validation engines - 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 - Building medication order entry with safety checks
- Integrating lab result interpretation with clinical context - 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 EMR UI
@@ -35,84 +43,52 @@ CDSS Engine (pure functions, no side effects)
EMR UI (displays alerts inline, blocks if critical) 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
## Drug Interaction Checking
### Data Model
```typescript ```typescript
interface DrugInteractionPair { interface DrugInteractionPair {
drugA: string; // generic name drugA: string; // generic name
drugB: string; // generic name drugB: string; // generic name
severity: 'critical' | 'major' | 'minor'; severity: 'critical' | 'major' | 'minor';
mechanism: string; // e.g., "CYP3A4 inhibition" mechanism: string;
clinicalEffect: string; // e.g., "Increased bleeding risk" clinicalEffect: string;
recommendation: string; // e.g., "Avoid combination" or "Monitor INR closely"
}
interface InteractionAlert {
severity: 'critical' | 'major' | 'minor';
pair: [string, string];
message: string;
recommendation: string; recommendation: string;
} }
```
### Implementation Pattern
```typescript
function checkInteractions( function checkInteractions(
newDrug: string, newDrug: string,
currentMedications: string[], currentMedications: string[],
allergyList: string[] allergyList: string[]
): InteractionAlert[] { ): InteractionAlert[] {
const alerts: InteractionAlert[] = []; const alerts: InteractionAlert[] = [];
// Check drug-drug interactions
for (const current of currentMedications) { for (const current of currentMedications) {
const interaction = findInteraction(newDrug, current); const interaction = findInteraction(newDrug, current);
if (interaction) { if (interaction) {
alerts.push({ alerts.push({ severity: interaction.severity, pair: [newDrug, current],
severity: interaction.severity, message: interaction.clinicalEffect, recommendation: interaction.recommendation });
pair: [newDrug, current],
message: interaction.clinicalEffect,
recommendation: interaction.recommendation
});
} }
} }
// Check drug-allergy interactions
for (const allergy of allergyList) { for (const allergy of allergyList) {
if (isCrossReactive(newDrug, allergy)) { if (isCrossReactive(newDrug, allergy)) {
alerts.push({ alerts.push({ severity: 'critical', pair: [newDrug, allergy],
severity: 'critical',
pair: [newDrug, allergy],
message: `Cross-reactivity with documented allergy: ${allergy}`, message: `Cross-reactivity with documented allergy: ${allergy}`,
recommendation: 'Do not prescribe without allergy consultation' recommendation: 'Do not prescribe without allergy consultation' });
});
} }
} }
return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
// Sort by severity (critical first)
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 ```typescript
interface DoseValidationResult { interface DoseValidationResult {
valid: boolean; valid: boolean;
message: string; message: string;
suggestedRange: { min: number; max: number; unit: string }; suggestedRange: { min: number; max: number; unit: string } | null;
factors: string[]; // what was considered (weight, age, renal function) factors: string[];
} }
function validateDose( function validateDose(
@@ -121,64 +97,76 @@ function validateDose(
route: 'oral' | 'iv' | 'im' | 'sc' | 'topical', route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',
patientWeight?: number, patientWeight?: number,
patientAge?: number, patientAge?: number,
renalFunction?: number // eGFR renalFunction?: number
): DoseValidationResult { ): DoseValidationResult {
const rules = getDoseRules(drug, route); const rules = getDoseRules(drug, route);
if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] }; if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };
const factors: string[] = [];
// Weight-based dosing // SAFETY: if rules require weight but weight missing, BLOCK (not pass)
if (rules.weightBased && patientWeight) { 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; const maxDose = rules.maxPerKg * patientWeight;
if (dose > maxDose) { if (dose > maxDose) {
return { return { valid: false, message: `Dose exceeds max for ${patientWeight}kg`,
valid: false, suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };
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 // Age-based adjustment (when rules define age brackets and age is provided)
if (dose > rules.absoluteMax) { if (rules.ageAdjusted && patientAge !== undefined) {
return { factors.push('age');
valid: false, const ageMax = rules.getAgeAdjustedMax(patientAge);
message: `Dose ${dose}${rules.unit} exceeds absolute max ${rules.absoluteMax}${rules.unit}`, if (dose > ageMax) {
suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit }, return { valid: false, message: `Exceeds age-adjusted max for ${patientAge}yr`,
factors: ['absolute_max'] 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 ### Clinical Scoring: NEWS2
National Early Warning Score 2 — standardized assessment of acute illness severity:
```typescript ```typescript
interface NEWS2Input { interface NEWS2Input {
respiratoryRate: number; respiratoryRate: number; oxygenSaturation: number; supplementalOxygen: boolean;
oxygenSaturation: number; temperature: number; systolicBP: number; heartRate: number;
supplementalOxygen: boolean;
temperature: number;
systolicBP: number;
heartRate: number;
consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive'; consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive';
} }
interface NEWS2Result { interface NEWS2Result {
total: number; // 0-20 total: number; // 0-20
risk: 'low' | 'low-medium' | 'medium' | 'high'; risk: 'low' | 'low-medium' | 'medium' | 'high';
components: Record<string, number>; 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 | | 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 | | Major | Warning banner inline. Orange. | Must acknowledge before proceeding |
| Minor | Info note inline. Yellow. | Awareness only, no action required | | Minor | Info note inline. Yellow. | Awareness only, no action required |
**Rules:** Critical alerts must NEVER be auto-dismissed or implemented as toast notifications. Override reasons must be stored in the audit trail.
- 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) ### Testing CDSS (Zero Tolerance for False Negatives)
```typescript ```typescript
describe('CDSS — Patient Safety', () => { describe('CDSS — Patient Safety', () => {
// Every known interaction pair MUST fire
INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => { INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => {
it(`detects ${drugA} + ${drugB} (${severity})`, () => { it(`detects ${drugA} + ${drugB} (${severity})`, () => {
const alerts = checkInteractions(drugA, [drugB], []); const alerts = checkInteractions(drugA, [drugB], []);
expect(alerts.length).toBeGreaterThan(0); expect(alerts.length).toBeGreaterThan(0);
expect(alerts[0].severity).toBe(severity); expect(alerts[0].severity).toBe(severity);
}); });
// Bidirectional check
it(`detects ${drugB} + ${drugA} (reverse)`, () => { it(`detects ${drugB} + ${drugA} (reverse)`, () => {
const alerts = checkInteractions(drugB, [drugA], []); const alerts = checkInteractions(drugB, [drugA], []);
expect(alerts.length).toBeGreaterThan(0); expect(alerts.length).toBeGreaterThan(0);
}); });
}); });
it('blocks mg/kg drug when weight is missing', () => {
// Dose validation const result = validateDose('gentamicin', 300, 'iv');
DOSE_RULES.forEach((rule) => { expect(result.valid).toBe(false);
it(`validates ${rule.drug}: ${rule.scenario}`, () => { expect(result.factors).toContain('weight_missing');
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', () => { it('handles malformed drug data gracefully', () => {
expect(() => checkInteractions('', [], [])).not.toThrow(); 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 - Making CDSS checks optional or skippable without documented reason
- ❌ Implementing interaction checks as toast notifications - Implementing interaction checks as toast notifications
- ❌ Using `any` types for drug or clinical data - Using `any` types for drug or clinical data
- ❌ Hardcoding interaction pairs instead of using a maintainable data structure - 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)
- ❌ 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.' }
```

127
skills/healthcare-emr-patterns/SKILL.md
View File

@@ -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. 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) - Implementing clinical note-taking (structured + free text + voice-to-text)
- Designing prescription/medication modules with drug interaction checking - Designing prescription/medication modules with drug interaction checking
- Integrating Clinical Decision Support Systems (CDSS) - 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 - Implementing audit trails for clinical data
- Designing healthcare-accessible UIs for clinical data entry - 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?" 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 - Critical vitals MUST trigger escalation workflows
- No clinical data modification without audit trail - 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) Patient Header (sticky — always visible)
@@ -53,9 +53,7 @@ Encounter Flow (vertical scroll)
└── 9. Sign / Lock / Print └── 9. Sign / Lock / Print
``` ```
### 3. Smart Template System ### Smart Template System
Build templates for common presentations:
```typescript ```typescript
interface ClinicalTemplate { 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 User selects drug
@@ -78,62 +76,87 @@ User selects drug
→ Check encounter medications for interactions → Check encounter medications for interactions
→ Check patient allergies → Check patient allergies
→ Validate dose against weight/age/renal function → Validate dose against weight/age/renal function
→ Display alerts (critical = block, major = require override reason) → If CRITICAL interaction: BLOCK prescribing entirely
→ Log override reason if clinician proceeds → 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: Once a clinical encounter is signed:
- No edits allowed — only addendum - No edits allowed — only an addendum (a separate linked record)
- Addendum is a new record linked to the original
- Both original and addendum appear in the patient timeline - 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) **Lab Results Display:** Normal range highlighting, previous value comparison, critical values with non-dismissable alert, collection/analysis timestamps, pending orders with expected turnaround.
- Trend arrows comparing to previous measurement
- Clinical scoring auto-calculated (NEWS2, qSOFA, MEWS)
- Scoring result displayed inline with escalation guidance
### 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 ### Accessibility for Healthcare
- Previous value comparison (trend)
- Critical values flagged with non-dismissable alert
- Timestamp of collection and analysis
- Pending orders shown with expected turnaround
### 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 ### Anti-Patterns
- 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 - 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 ### Example 1: Patient Encounter Flow
- **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 ```
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 ### Example 2: Medication Safety Workflow
- ❌ Silent failures in drug interaction checking
- ❌ Dismissable toasts for critical clinical alerts ```
- ❌ Tab-based encounter UIs that fragment the clinical workflow Doctor prescribes Warfarin for Patient #4521
- ❌ Allowing edits to signed/locked encounters → CDSS detects: Warfarin + Aspirin = CRITICAL interaction
- ❌ Displaying clinical data without audit trail → UI: red non-dismissable modal blocks prescribing
- ❌ Using `any` type for clinical data structures → 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
```

165
skills/healthcare-eval-harness/SKILL.md
View File

@@ -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. 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 - Before any deployment of EMR/EHR applications
- After modifying CDSS logic (drug interactions, dose validation, scoring) - 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 - During CI/CD pipeline configuration for healthcare apps
- After resolving merge conflicts in clinical modules - 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 ### Eval Categories
- Dose validation: out-of-range doses must be flagged
- Clinical scoring: results must match published specifications **1. CDSS Accuracy (CRITICAL — 100% required)**
- No false negatives: a missed alert is a patient safety event
- No silent failures: malformed input must error, not silently pass 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 ```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: Tests for protected health information leaks: API error responses, console output, URL parameters, browser storage, cross-facility isolation, unauthenticated access, service role key absence.
- 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 ```bash
npx jest --testPathPattern='tests/security/phi' --bail --ci 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: Tests clinical data safety: locked encounters, audit trail entries, cascade delete protection, concurrent edit handling, no orphaned records.
- 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 ```bash
npx jest --testPathPattern='tests/data-integrity' --bail --ci 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: Tests end-to-end flows: encounter lifecycle, template rendering, medication sets, drug/diagnosis search, prescription PDF, red flag alerts.
- 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 ```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: Tests external systems: HL7 message parsing (v2.x), FHIR validation, lab result mapping, malformed message handling.
- HL7 message parsing (v2.x)
- FHIR resource validation (if applicable)
- Lab result mapping to correct patients
- Malformed message handling (no crashes)
```bash ```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 ```yaml
name: Healthcare Safety Gate name: Healthcare Safety Gate
@@ -113,9 +95,9 @@ jobs:
node-version: '20' node-version: '20'
- run: npm ci - run: npm ci
# CRITICAL gates — must pass 100% # CRITICAL gates — 100% required, bail on first failure
- name: CDSS Accuracy - 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 - name: PHI Exposure Check
run: npx jest --testPathPattern='tests/security/phi' --bail --ci run: npx jest --testPathPattern='tests/security/phi' --bail --ci
@@ -123,47 +105,72 @@ jobs:
- name: Data Integrity - name: Data Integrity
run: npx jest --testPathPattern='tests/data-integrity' --bail --ci run: npx jest --testPathPattern='tests/data-integrity' --bail --ci
# HIGH gates — must pass 95%+ # HIGH gates — 95%+ required, custom threshold check
- name: Clinical Workflows - 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 - 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 | - Skipping CDSS tests "because they passed last time"
|----------|-----------|------------| - Setting CRITICAL thresholds below 100%
| CDSS Accuracy | 100% | **BLOCK deployment** | - Using `--no-bail` on CRITICAL test suites
| PHI Exposure | 100% | **BLOCK deployment** | - Mocking the CDSS engine in integration tests (must test real logic)
| Data Integrity | 100% | **BLOCK deployment** | - Allowing deployments when safety gate is red
| Clinical Workflow | 95%+ | WARN, allow with review | - Running tests without `--coverage` on CDSS suites
| Integration | 95%+ | WARN, allow with review |
## 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 | | Category | Tests | Pass | Fail | Status |
|----------|-------|------|------|--------| |----------|-------|------|------|--------|
| CDSS Accuracy | N | N | 0 | PASS | | CDSS Accuracy | 39 | 39 | 0 | PASS |
| PHI Exposure | N | N | 0 | PASS | | PHI Exposure | 8 | 8 | 0 | PASS |
| Data Integrity | N | N | 0 | PASS | | Data Integrity | 12 | 12 | 0 | PASS |
| Clinical Workflow | N | N | N | 95%+ | | Clinical Workflow | 22 | 21 | 1 | 95.5% PASS |
| Integration | N | N | N | 95%+ | | Integration | 6 | 6 | 0 | PASS |
### Coverage: X% (target: 80%+) ### Coverage: 84% (target: 80%+)
### Verdict: SAFE TO DEPLOY / BLOCKED ### 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

203
skills/healthcare-phi-compliance/SKILL.md
View File

@@ -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. 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 - Building any feature that touches patient records
- Implementing access control or authentication for clinical systems - 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 - Reviewing code for data exposure vulnerabilities
- Setting up Row-Level Security (RLS) for multi-tenant healthcare systems - 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 **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.
- 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) **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: ### Access Control: Row-Level Security
- 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 ```sql
-- Enable RLS on every PHI table
ALTER TABLE patients ENABLE ROW LEVEL SECURITY; ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
-- Scope access by facility/centre -- Scope access by facility
CREATE POLICY "staff_read_own_facility" CREATE POLICY "staff_read_own_facility"
ON patients FOR SELECT ON patients FOR SELECT TO authenticated
TO authenticated USING (facility_id IN (
USING ( SELECT facility_id FROM staff_assignments
facility_id IN ( WHERE user_id = auth.uid() AND role IN ('doctor','nurse','lab_tech','admin')
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());
-- 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_modify" ON audit_log FOR UPDATE USING (false);
CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false); CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false);
``` ```
### API Authentication ### Audit Trail
- 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
Every PHI access or modification must be logged: Every PHI access or modification must be logged:
@@ -151,35 +64,85 @@ interface AuditEntry {
action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export'; action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
resource_type: string; resource_type: string;
resource_id: string; resource_id: string;
changes?: { before: object; after: object }; // for updates changes?: { before: object; after: object };
ip_address: string; ip_address: string;
session_id: 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 ```sql
COMMENT ON COLUMN patients.name IS 'PHI: patient_name'; COMMENT ON COLUMN patients.name IS 'PHI: patient_name';
COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth'; COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth';
COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id'; COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id';
COMMENT ON COLUMN doctor_payouts.amount IS 'PII: financial'; 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 ## Examples
- [ ] No PHI in console.log/console.error
- [ ] No PHI in URL parameters ### Example 1: Safe vs Unsafe Error Handling
- [ ] No PHI in browser storage
- [ ] No service_role key in client code ```typescript
- [ ] RLS enabled on all PHI/PII tables // BAD — leaks PHI in error
- [ ] Audit trail for all data modifications throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);
- [ ] Session timeout configured
- [ ] API authentication on all PHI endpoints // GOOD — generic error, details logged server-side with opaque IDs only
- [ ] Cross-facility data isolation verified 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
```