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:
- AUDIT - Systematic checking of current or historical schedules
- ANALYZE - Pattern identification and trend analysis
- 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
# 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.mdfor complete ACGME citations - See
Reference/compliance-glossary.mdfor terminology definitions - See
Workflows/for step-by-step audit procedures
Development Notes
When adding new constraints:
- Add validator to
backend/app/services/constraints/acgme.py - Register in
ACGMEConstraintValidator.constraintslist - Add unit test in
backend/tests/validators/ - Update this skill's reference documentation
- Classify as Tier 1/2/3/4 for prioritization
When fixing violations:
- Always create database backup first
- Use transaction rollback if fix fails
- Re-run validation after fix
- Document fix in audit trail
- Update historical compliance metrics