Soft Targets / Fairness Constraints — Future Design Notes

Parked during the hard constraints design session. Pick up after hard constraints are implemented and in use.

Constraint Types

Shift Count Targets

“PGY-X residents should complete N shifts of template type Y over the academic year.”

• program_id
• pgy_min / pgy_max — PGY range
• resident_tag_ids — optional additional filter (AND logic)
• template_id or call_type_id — what shifts count
• target_count — the goal
• min_count / max_count — optional hard floor/ceiling

Balance / Fairness Requirements

“Distribute shifts fairly across residents in a group.”

• program_id
• pgy_min / pgy_max — defines the resident group
• resident_tag_ids — optional additional group filter
• Scope: what shifts to balance (e.g., all weekend calls, all ICU nights)

Open Questions

Scoping across schedules

The core tension: soft targets need to balance across multiple schedules within an academic year, but: - You need to know which schedules to balance across - Those schedules might not all exist yet when you create the constraint - The “academic year” is implicit (no explicit entity), defined by date ranges of schedules

Possible approaches discussed

1. Program-level, always apply — targets are program-scoped and implicitly apply to all schedules. Simplest but least flexible.
2. Select associated schedules — when creating a schedule, you reference which other schedules share soft targets. The solver would look at assignments across all associated schedules. More explicit but raises UX questions about what happens when a new schedule is added mid-year.
3. Explicit academic year entity — create a program_year concept that groups schedules. Cleanest model but adds a new entity.

UX considerations

• When creating a new schedule, how does a user associate it with existing soft targets?
• Should soft targets auto-apply to new schedules created within the same date range?
• How do you show progress toward targets when assignments are spread across schedules?

Relationship to solver

Soft targets are optimization objectives, not hard constraints. The solver should: - Try to hit target counts (minimize deviation from target) - Minimize variance across the balance group (fairness) - These compete with “maximize filled shifts” — need to define priority/weighting