Shift swaps

A swap moves shifts between residents without anyone editing the schedule by hand. Clepsy validates the trade before it starts, tracks it through acceptance and approval, and rotates the assignments only when the request clears. This guide covers both residents requesting swaps and chiefs approving or executing them.

Two-way swaps

A two-way swap exchanges one of your shifts for one shift held by another resident. You must start from your own assignment; you cannot request a trade using someone else's shift as the source.

Request a two-way swap

1. Open the schedule and switch to Swap mode.
2. Click one of your own shifts. It becomes the source. Clepsy does not auto-select a source for residents, so the grid stays neutral until you click.
3. Read the colors. A green target is a valid two-way swap. Purple means a direct swap is blocked but a three-way bridge may work. Faded or red means the trade is blocked; hover the shift for the reason.
4. Click a green target. The confirmation modal shows both residents, both shifts, and your remaining swap requests for the academic year.
5. Click Request Swap. The request is created with status pending_target and the target resident is notified.
6. The target accepts from their swap view. If your residency requires chief approval, the request moves to pending_chief; if not, it executes as soon as the target accepts.
7. A chief approves or rejects a pending-chief request. Approval rotates the assignments immediately; rejection closes the request as rejected.

Every request expires 48 hours after it is created. The requester can cancel a request while it is pending_target or pending_chief, and the target can decline instead of accepting. Expiry is swept lazily when request lists are read, so an outdated row can remain visible until the next read.

Three-way bridge swaps

A three-way bridge solves a pair that cannot trade directly. The rotation is always: B takes A's source, C takes B's target, and A takes C's bridge. A is the requester, B is the target, and C is the bridge resident.

1. Select your own source shift, then click a target that shows purple.
2. The bridge panel lists candidate third shifts. Bridge discovery runs in the browser, not on the server, and every candidate is checked on all three legs before it appears.
3. Choose a bridge candidate and confirm. The modal labels the action Request 3-Way Swap.
4. Both the target and the bridge must accept. Either party can decline, which closes the request as rejected.
5. Once both accept, the request follows the same chief-approval path as a two-way swap: pending chief when the residency requires it, otherwise auto-executed.

Swap statuses

The same status can carry slightly different labels on different screens. The underlying value is what drives behavior.

The inline badge in the swap finder uses sentence case, the preview modal uses title case, and the home dashboard uses Waiting on. Approved, Rejected, Cancelled, and Expired are consistent.

Chief approval and direct execute

Each residency has a Need chief approval for swaps flag in Residency Settings.

• Checked: after the target accepts, and after the bridge accepts on a three-way, the request moves to pending_chief. A chief approves or rejects it in Swap Approvals.
• Unchecked: the swap auto-executes once the target accepts, or once both the target and bridge accept on a three-way. The request becomes approved without a chief step.

Turning the flag off does not remove the acceptance step. The target, and the bridge on a three-way, must still accept before anything rotates.

Callers at Chief Resident level or above, up to Admin, can also execute a swap directly. Select a source and target, add a bridge if needed, and choose Execute Swap. No request is created and no quota is consumed. Direct execute rotates immediately and pushes an undo entry.

Swap request quota

The default is 10 swap requests per academic year. The role supplies a default and an individual user can carry an override.

• Only the requester is counted. Accepting someone else's request does not consume your quota.
• Counted statuses are pending_target, pending_chief, and approved. Rejected, cancelled, and expired requests do not count.
• The academic year comes from the source shift's assignment date.
• Chiefs and every level above them are exempt: Chief Resident, Super User, Superduper User, and Admin.

In the swap finder the pill reads Swap requests this AY with a value such as 6 left · 4 used of 10. The confirmation modal shows Swap requests remaining this AY as 6 / 10 and disables the request button at zero.

What the swap engine checks

The browser engine runs these checks in order. Thresholds are the ones in the code, not a general ACGME summary.

Why is my swap blocked?

Hover or open the diagnostic on a blocked shift first; it names the failing rule. Then check the common causes:

• Same day: the resident already works another shift on the date they would receive.
• Rest: the gap to an adjacent shift is under 10 hours.
• Hours: the 28-day window would exceed 320 duty hours.
• Day off: there is no free calendar day in the plus or minus 3-day window.
• Streak: the trade would create a seventh consecutive night or seventh consecutive working day.
• Availability: the resident has no EM block that week or the week falls outside the academic year.
• Pending request: one of the shifts is already tied up in another request.
• Draft versus published: both shifts must be in the same publish state.
• Scope: a PGY pill or the Visitor option is excluding a participant.
• Timing: the request has already expired, or the shift is in the past.

What happens to the assignments?

In a two-way swap, the requester takes the target's shift and the target takes the requester's shift: A receives B's target and B receives A's source. In a three-way, B receives A's source, C receives B's target, and A receives C's bridge.

A chief's direct execute rotates the assignments immediately and is undoable; undo covers chief swap execution. A resident request rotates only when it is approved, either by a chief or automatically when chief approval is disabled. Clepsy refreshes the grid afterward, and pending requests are treated as possible future schedules when validating later swaps.

For chiefs

• Swap Approvals card: lists pending-chief requests in your residency. Use View to preview the trade on the calendar, then Approve or Reject. Approval executes the rotation.
• Direct execute: use Swap mode and the Execute action. You skip the request flow and the quota, and you get an undo entry.
• Quota: chiefs and above are exempt from the 10-per-year requester quota.
• Rest caution: manual fill in the schedule editor uses an 8-hour rest threshold, while the swap engine and solver use 10 hours. A manually accepted 8-to-10-hour turnaround can look fine in the editor but block a swap or make the next solve infeasible.
• Per-residency control: chief approval can be disabled entirely with Need chief approval for swaps. Target and bridge acceptance still apply.

See ACGME compliance for the enforcement gaps, Admin guide for Residency Settings, and FAQ for quick answers.