Safe Schedule Generation

Safe Schedule Generation Skill

HARD GATE: No schedule generation, bulk assignment, or destructive operation without verified backup.

Two Truths: Generation Writes Descriptive Truth

CRITICAL CONTEXT:

Generation transforms prescriptive truth INTO descriptive truth:

rotation_templates + block_assignments → expansion_service → half_day_assignments
     (prescriptive)                                            (descriptive)

Why backup is critical: Generation WRITES to half_day_assignments. This is the canonical record of what got scheduled. If generation produces bad results:

• Manual overrides (source='manual') could be lost
• Preloads (source='preload') could be corrupted
• Historical audit trail could be damaged

The source column tracks how each slot was determined:

• preload = locked (absences, FMIT, call) - NEVER overwritten by generation
• solver = computed by optimizer during generation
• manual = human override (should survive regeneration)
• template = default from weekly pattern

When This Skill Activates

• Generating new schedules via API or MCP
• Bulk assigning residents/faculty to rotations
• Executing swap requests
• Clearing or regenerating schedule blocks
• Any operation that modifies assignments table

MANDATORY Pre-Flight Checklist

ALL checks MUST pass before any database-modifying operation:

1. Backup Verification

# Check most recent backup
ls -la backups/postgres/*.sql.gz | tail -1

# Verify backup is recent (created within last 2 hours)
find backups/postgres -name "*.sql.gz" -mmin -120 | head -1

If no recent backup exists:

./scripts/backup-db.sh --docker

2. Backend Health Check

curl -s http://localhost:8000/health | jq .
# Expected: {"status":"healthy","database":"connected"}

3. Data Verification

# Get auth token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login/json \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}' | jq -r .access_token)

# Verify people exist
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/people?limit=5" | jq .total

# Verify rotation templates exist
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/rotation-templates" | jq 'length'

4. User Confirmation

Before proceeding, confirm with user:

"Backup verified at [timestamp]. Proceed with schedule generation?"

Backup Safety Rules

Minimum Backup Policy

Backup File Naming

residency_scheduler_YYYYMMDD_HHMMSS.sql.gz     # Regular backup
residency_scheduler_SACRED_20251223.sql.gz     # Protected baseline
residency_scheduler_pre-block-10_20260312.sql.gz  # Pre-operation marker

Creating a Backup

# Standard backup (creates timestamped file, never overwrites)
./scripts/backup-db.sh --docker

# Verify
ls -la backups/postgres/ | tail -3

Rollback Procedure

Emergency Restore

If schedule generation fails or produces bad results:

# 1. Find the backup to restore
ls -la backups/postgres/*.sql.gz

# 2. Decompress (keeps original .gz)
gunzip -k backups/postgres/residency_scheduler_YYYYMMDD_HHMMSS.sql.gz

# 3. Restore to database
docker compose exec -T db psql -U scheduler -d residency_scheduler \
  < backups/postgres/residency_scheduler_YYYYMMDD_HHMMSS.sql

# 4. Verify restoration
docker compose exec db psql -U scheduler -d residency_scheduler \
  -c "SELECT COUNT(*) FROM assignments;"

Partial Rollback (Specific Tables)

# Restore only assignments table
docker compose exec db psql -U scheduler -d residency_scheduler \
  -c "DELETE FROM assignments WHERE date BETWEEN '2026-03-12' AND '2026-04-08';"
# Then reimport from backup or regenerate

Local Data Sources (PII - Never in Git)

If database needs complete reimport, source files are at:

CRITICAL: These files contain real names. Never commit to repository.

Examples

Example 1: Generating Block 10 Schedule

User Request: "Generate the schedule for Block 10 (March 12 - April 8, 2026)"

Claude Response:

Step 1: Pre-flight checks

Running pre-flight checklist...
✅ Most recent backup: backups/postgres/residency_scheduler_20260312_083000.sql.gz (created 45 minutes ago)
✅ Backend health: {"status":"healthy","database":"connected"}
✅ Data verification: 25 people found, 8 rotation templates available

Step 2: User confirmation

"Backup verified at 2026-03-12 08:30:00. Proceed with schedule generation for Block 10 (2026-03-12 to 2026-04-08)?"

User: "Yes, proceed"

Step 3: Execute generation

Calling generate_schedule API...
{
  "start_date": "2026-03-12",
  "end_date": "2026-04-08",
  "algorithm": "cp_sat",
  "timeout_seconds": 120
}

Step 4: Report results

✅ Schedule generated successfully
- Total blocks assigned: 1425 / 1456 (97.9% coverage)
- ACGME violations: 2 (minor)
- N-1 compliant: True
- Generation time: 47 seconds

Example 2: Failed Generation Requiring Rollback

User Request: "Try generating the schedule again with stricter constraints"

Claude Response:

Step 1: Create new backup before retry

Creating pre-operation backup...
✅ Backup created: residency_scheduler_pre-retry_20260312_094500.sql.gz

Step 2: Attempt generation

Generating schedule with updated constraints...
❌ Generation failed: Solver timeout after 120s with no feasible solution

Step 3: Check for partial data

SELECT COUNT(*) FROM assignments WHERE date >= '2026-03-12';
-- Result: 234 assignments (partial data written)

Step 4: Automatic rollback

⚠️  Partial data detected. Rolling back to last backup...

Restoring from: residency_scheduler_pre-retry_20260312_094500.sql.gz
✅ Database restored successfully
✅ Verification: 0 assignments for target date range (clean state)

Step 5: Recommendation

"Generation failed due to infeasible constraints. Recommend reviewing constraint weights before retry. Database rolled back to clean state."

Example 3: Read-Only Validation (No Backup Required)

User Request: "Check if the current schedule has any ACGME violations"

Claude Response:

This is a read-only operation, no backup required.

Calling validate_schedule API...

Results:

{
  "acgme_compliant": false,
  "violations": [
    {
      "type": "80_hour_rule",
      "resident_id": "RES-PGY1-03",
      "week": "2026-03-17",
      "hours": 82.5
    },
    {
      "type": "supervision_ratio",
      "date": "2026-03-22",
      "pgy1_residents": 3,
      "faculty": 1
    }
  ]
}

"Found 2 ACGME violations. Recommend addressing these before deployment."

Schedule Generation Workflow

Via Direct API

# 1. Create backup (MANDATORY)
./scripts/backup-db.sh --docker

# 2. Get auth token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login/json \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}' | jq -r .access_token)

# 3. Generate schedule
curl -X POST http://localhost:8000/api/v1/schedule/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-03-12",
    "end_date": "2026-04-08",
    "algorithm": "cp_sat",
    "timeout_seconds": 120
  }'

Via MCP Tool

Tool: generate_schedule
Input: {
  start_date: "2026-03-12",
  end_date: "2026-04-08",
  algorithm: "cp_sat",
  timeout_seconds: 120
}

MCP tools MUST verify backup before execution.

Protected vs Safe Operations

Database-Modifying (Require Backup)

Read-Only (Always Safe)

Success Metrics

After schedule generation, verify:

Failure Recovery

If Generation Fails Mid-Process

1. Note the error message
2. Do NOT retry immediately
3. Check backend health
4. Restore from backup if partial data written
5. Investigate root cause

If Generation Produces Bad Schedule

1. Review violations in response
2. If > 10 violations: restore and adjust constraints
3. If < 10 violations: manual adjustment may be faster

If Backend Crashes

# Restart backend
docker compose restart backend

# Verify health
curl http://localhost:8000/health

# Check if data corrupted
docker compose exec db psql -U scheduler -d residency_scheduler \
  -c "SELECT COUNT(*) FROM people;"

Workflow Diagram

┌──────────────────────────────────────────────────────────────────┐
│           SAFE SCHEDULE GENERATION WORKFLOW                      │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  STEP 1: Pre-Flight Safety Checks                                │
│  ┌────────────────────────────────────────────────┐             │
│  │ Check backend health (/health endpoint)        │             │
│  │ Verify data exists (people, rotation templates)│             │
│  │ Confirm auth working                           │             │
│  └────────────────────────────────────────────────┘             │
│                         ↓                                       │
│  STEP 2: Backup Verification (MANDATORY)                        │
│  ┌────────────────────────────────────────────────┐             │
│  │ Check for backup < 2 hours old                 │             │
│  │ If none exists: ./scripts/backup-db.sh --docker│             │
│  │ Verify backup file created successfully        │             │
│  │ ⚠️ NEVER proceed without verified backup       │             │
│  └────────────────────────────────────────────────┘             │
│                         ↓                                       │
│  STEP 3: User Confirmation                                      │
│  ┌────────────────────────────────────────────────┐             │
│  │ Show backup timestamp and database contents    │             │
│  │ Ask: "Proceed with schedule generation?"       │             │
│  │ Wait for explicit YES                          │             │
│  └────────────────────────────────────────────────┘             │
│                         ↓                                       │
│  STEP 4: Schedule Generation                                    │
│  ┌────────────────────────────────────────────────┐             │
│  │ Call API or MCP tool with parameters           │             │
│  │ Monitor progress (log streaming if available)  │             │
│  │ Capture result (success/failure)               │             │
│  └────────────────────────────────────────────────┘             │
│                         ↓                                       │
│  STEP 5: Result Validation                                      │
│  ┌────────────────────────────────────────────────┐             │
│  │ Check: ACGME violations < 5                    │             │
│  │ Check: Coverage rate > 80%                     │             │
│  │ Check: N-1 compliant (if resilience enabled)   │             │
│  │ If ANY fail → Offer rollback                   │             │
│  └────────────────────────────────────────────────┘             │
│                         ↓                                       │
│  STEP 6: Success or Rollback                                    │
│  ┌────────────────────────────────────────────────┐             │
│  │ Success: Report metrics, keep backup           │             │
│  │ Failure: Restore from backup, report error     │             │
│  └────────────────────────────────────────────────┘             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Concrete Usage Example: Generating Block 10 Schedule

See detailed walkthrough in skill documentation above showing complete safety check workflow.

Failure Mode Handling

Failure Mode 1: No Recent Backup

Symptom: No backup exists or last backup > 2 hours old

Recovery: Create new backup with ./scripts/backup-db.sh --docker before proceeding

Failure Mode 2: Generation Fails with Partial Data

Symptom: Error response with partial_assignments count > 0

Recovery: Offer rollback to user, restore from backup if confirmed

Failure Mode 3: Excessive ACGME Violations

Symptom: validation.acgme_violations >= 5

Recovery: Automatic rollback offer, do not accept schedule

Failure Mode 4: Backend Crash During Generation

Symptom: Connection refused or 500 errors

Recovery: Restart backend, check database integrity, rollback if needed

Failure Mode 5: Backup Restoration Fails

Symptom: Duplicate key or constraint violations during restore

Recovery: Try clean restore (drop/recreate database), escalate if fails

Integration with Other Skills

With schedule-validator

Post-generation ACGME compliance check and coverage gap detection

With resilience-dashboard

Burnout risk assessment and N-1/N-2 compliance verification

With database-migration

Pre-migration backup creation and rollback capability

With systematic-debugger

Investigation of repeated generation failures

Validation Checklists

Pre-Generation

• Backend health verified
• Data loaded (people, templates, absences)
• Backup exists and recent
• User confirmation obtained

Success Validation

• HTTP 200 response
• ACGME violations < 5
• Coverage > 80%
• N-1 compliant (if enabled)

Escalation

• Backup fails repeatedly
• ACGME violations > 10
• Database corruption
• Infeasible constraints

Quick Reference Card

┌─────────────────────────────────────────────────────┐
│         SCHEDULE MODIFICATION DECISION TREE         │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Does this modify the database?                     │
│     NO  → Safe to proceed                           │
│     YES → Continue checks                           │
│                                                     │
│  Is there a recent backup (< 2 hours)?              │
│     NO  → CREATE BACKUP FIRST                       │
│     YES → Continue                                  │
│                                                     │
│  Is backend healthy?                                │
│     NO  → FIX BACKEND FIRST                         │
│     YES → Continue                                  │
│                                                     │
│  Has user confirmed?                                │
│     NO  → ASK USER                                  │
│     YES → Proceed with operation                    │
│                                                     │
│  After operation:                                   │
│     Check violations < 5                            │
│     Verify coverage > 80%                           │
│     If failed → RESTORE FROM BACKUP                 │
│                                                     │
└─────────────────────────────────────────────────────┘