--- name: COMPLIANCE_VALIDATION description: ACGME & institutional rule checking with systematic audit workflows, historical analysis, and violation remediation. Use for compliance audits, violation investigation, and regulatory reporting. --- # COMPLIANCE_VALIDATION Skill Comprehensive ACGME compliance validation, historical analysis, and violation remediation for medical residency scheduling. This skill provides systematic audit workflows, trend analysis, and actionable remediation strategies. ## When This Skill Activates - **Pre-deployment validation** - Before publishing any schedule - **Regulatory audits** - Monthly/quarterly ACGME reporting - **Violation investigation** - When compliance issues are detected - **Historical analysis** - Trend analysis over multiple blocks - **Remediation planning** - Fixing identified violations - **Program review preparation** - Annual ACGME site visits - **Post-swap validation** - After schedule swap execution ## Overview This skill implements a three-phase compliance approach: 1. **AUDIT** - Systematic checking of current or historical schedules 2. **ANALYZE** - Pattern identification and trend analysis 3. **REMEDIATE** - Violation fixing with minimal disruption Unlike the general `acgme-compliance` skill (which provides reference knowledge), this skill focuses on **systematic execution** of compliance workflows. ## Key Phases ### Phase 1: Audit - Load schedule data from database - Run all Tier 1/2 constraint validators - Generate comprehensive violation report - Classify violations by severity (CRITICAL, HIGH, MEDIUM, LOW) - Identify affected personnel ### Phase 2: Analyze - Aggregate violations across time periods - Identify recurring patterns (same rule violated repeatedly) - Calculate compliance metrics (% compliant blocks, violation rate) - Generate trend charts (violations over time) - Root cause analysis (why violations happen) ### Phase 3: Remediate - Prioritize violations (Tier 1 ACGME first, then institutional) - Generate remediation strategies for each violation - Impact assessment (how fix affects other constraints) - Execute fixes with transaction rollback support - Verification (re-run validation after fix) ## Constraint Tiers All constraints are classified into tiers for prioritization: ### Tier 1: ACGME Regulatory (CRITICAL) **Must fix immediately - regulatory violations** - 80-Hour Rule: Maximum 80 hours/week averaged over 4 weeks - 1-in-7 Rule: One 24-hour period off every 7 days - Supervision Ratios: PGY-specific faculty supervision - Duty Period Limits: Maximum continuous duty hours - Availability: No assignments during absences ### Tier 2: Institutional Hard Constraints (HIGH) **Must fix before deployment - operational requirements** - FMIT Coverage: Weekly faculty rotation - Night Float Headcount: Exactly 1 resident - NICU Friday Clinic: Required clinic day - Post-Call Blocking: Required recovery time - Credential Requirements: Slot-type invariants ### Tier 3: Soft Constraints (MEDIUM) **Should fix if possible - preferences** - Call spacing: Avoid back-to-back call weeks - Weekend distribution: Fair distribution - Clinic day preferences: PGY-specific clinic days ### Tier 4: Optimization Goals (LOW) **Nice to have - quality improvements** - Workload balance - Continuity of care - Learning opportunities ## Workflows This skill provides specialized workflows in the `Workflows/` directory: | Workflow | Purpose | When to Use | |----------|---------|-------------| | **audit-current-schedule.md** | Validate active schedule | Pre-deployment, monthly checks | | **historical-compliance.md** | Analyze past schedules | Quarterly reporting, trend analysis | | **violation-remediation.md** | Fix identified violations | After audit failures, post-swap | ## Key Files ### Core Validation Code ``` backend/app/services/constraints/acgme.py - ACGME constraint validators backend/app/validators/advanced_acgme.py - Enhanced validators (24+4, NF limits) backend/app/scheduling/constraints/acgme.py - Constraint service integration ``` ### Database Schema ``` backend/alembic/versions/003_add_acgme_audit_fields.py - Audit trail schema backend/app/models/assignment.py - Schedule assignments backend/app/models/person.py - Faculty/resident data backend/app/models/block.py - Time blocks ``` ### Tests ``` backend/tests/validators/test_advanced_acgme.py - Unit tests backend/tests/integration/test_acgme_edge_cases.py - Integration tests backend/tests/performance/test_acgme_load.py - Load testing ``` ## Output Format All compliance reports must follow this structure: ``` ╔══════════════════════════════════════════════════════════════════╗ ║ ACGME COMPLIANCE AUDIT REPORT ║ ║ Schedule: Block 10 (2026-03-12 to 2026-04-08) ║ ║ Generated: 2025-12-26 15:30:00 ║ ║ Validator: COMPLIANCE_VALIDATION Skill ║ ╠══════════════════════════════════════════════════════════════════╣ ║ OVERALL STATUS: [COMPLIANT / WARNING / VIOLATION] ║ ╠══════════════════════════════════════════════════════════════════╣ ║ ║ ║ TIER 1: ACGME VIOLATIONS (Critical) ║ ║ ──────────────────────────────────────────────────────────── ║ ║ [List violations with person, date, specifics] ║ ║ ║ ║ TIER 2: INSTITUTIONAL VIOLATIONS (High) ║ ║ ──────────────────────────────────────────────────────────── ║ ║ [List violations] ║ ║ ║ ║ TIER 3: SOFT CONSTRAINT WARNINGS (Medium) ║ ║ ──────────────────────────────────────────────────────────── ║ ║ [List warnings] ║ ║ ║ ║ SUMMARY METRICS ║ ║ ──────────────────────────────────────────────────────────── ║ ║ Total Violations: 3 (Tier 1: 2, Tier 2: 1) ║ ║ Affected Personnel: 5 (3 residents, 2 faculty) ║ ║ Compliance Rate: 94.2% (33/35 constraints passed) ║ ║ ║ ║ RECOMMENDED ACTIONS ║ ║ ──────────────────────────────────────────────────────────── ║ ║ 1. [Specific remediation step] ║ ║ 2. [Specific remediation step] ║ ║ 3. [Specific remediation step] ║ ║ ║ ╚══════════════════════════════════════════════════════════════════╝ ``` ## Error Handling ### Database Connection Issues ```python # Always use try-catch with rollback try: db = SessionLocal() result = validate_schedule(db, schedule_id) db.commit() except Exception as e: db.rollback() logger.error(f"Validation failed: {e}") raise finally: db.close() ``` ### Missing Data If data is missing (no assignments, no residents), report clearly: ``` ⚠️ VALIDATION INCOMPLETE: No assignments found for Block 10 Possible causes: - Schedule not yet generated - Wrong date range - Database migration incomplete ``` ### Constraint Failures If a constraint validator fails (not just violations, but crashes): ``` ❌ VALIDATOR ERROR: 80HourRule constraint failed to execute Error: Division by zero in _calculate_rolling_average() Action: Check that blocks exist in date range ``` ## MCP Tool Integration ### Primary Tools ``` validate_acgme_compliance - Run full ACGME validation get_schedule - Retrieve schedule data check_utilization_threshold_tool - Verify 80% utilization run_contingency_analysis - N-1 coverage check ``` ### Remediation Tools ``` execute_swap - Fix violations via swaps get_swap_candidates - Find compatible swap partners validate_swap_compliance - Ensure swap maintains compliance ``` ## Escalation Matrix | Violation Count | Severity | Action Required | |----------------|----------|-----------------| | 0 | GREEN | Deploy schedule | | 1-2 Tier 3 | YELLOW | Fix within 7 days | | 1-2 Tier 2 | ORANGE | Fix within 48 hours | | Any Tier 1 | RED | Do not deploy, fix immediately | | 3+ Tier 1 | BLACK | Escalate to Program Director | ## References - See `Reference/acgme-rules-detailed.md` for complete ACGME citations - See `Reference/compliance-glossary.md` for terminology definitions - See `Workflows/` for step-by-step audit procedures ## Development Notes **When adding new constraints:** 1. Add validator to `backend/app/services/constraints/acgme.py` 2. Register in `ACGMEConstraintValidator.constraints` list 3. Add unit test in `backend/tests/validators/` 4. Update this skill's reference documentation 5. Classify as Tier 1/2/3/4 for prioritization **When fixing violations:** 1. Always create database backup first 2. Use transaction rollback if fix fails 3. Re-run validation after fix 4. Document fix in audit trail 5. Update historical compliance metrics