rota-builder

---
name: rota-builder
description: Builds a staff rota that already obeys the Working Time Regulations 1998 before it is published, rather than a rota that looks fine on a spreadsheet and breaks the 48-hour average, the daily rest period or the weekly rest period once real shifts are placed on real days. It works out the reference period being used, lays daily and weekly rest in before shifts go on top, and checks every worker's written particulars still match what the rota actually asks of them. Use before you publish a new rota, before you add a busy-week run of extra shifts, and whenever two managers have built pieces of the same week separately.
---

# A rota that is legal before it is published, not checked after

You give this the shifts you want to place, the staff available for them, and each worker's written particulars. You get back a rota with the reference period stated, every worker's running average against the 48-hour limit, every daily and weekly rest gap checked shift by shift, and a flag on anyone the rota asks to work differently from what their written statement says.

## What it does

1. **Fix the reference period before counting a single hour.** Regulation 4(1) of the Working Time Regulations 1998 says a worker's working time "shall not exceed an average of 48 hours for each seven days", and regulation 4(3)(b) sets the default averaging window at "any period of 17 weeks in the course of his employment" unless a relevant agreement sets a different one. A rota built week by week with no stated reference period cannot show whether it breaches the limit, because one brutal week is allowed if earlier or later weeks pull the average down. State the 17 weeks, or the agreed alternative, before totting up a single shift.
2. **Lay in daily rest before shifts go on the grid.** Regulation 10(1) entitles a worker to "a rest period of not less than eleven consecutive hours in each 24-hour period during which he works for his employer." A closing shift followed by an early opening shift is the commonest way this gets missed, because each shift looks fine read on its own day. Calculate the gap between the end of one shift and the start of the next for every worker, every day, not just the ones that look tight.
3. **Lay in weekly rest next.** Regulation 11(1) entitles a worker to "an uninterrupted rest period of not less than 24 hours in each seven-day period", and regulation 11(2) lets an employer instead give "two uninterrupted rest periods each of not less than 24 hours in each 14-day period" or "one uninterrupted rest period of not less than 48 hours in each such 14-day period." Pick one pattern for the business and apply it to everyone on the rota, rather than letting rest periods emerge as whatever is left over once shifts are placed.
4. **Match the rota against each worker's written particulars.** Section 1 of the Employment Rights Act 1996 requires the written statement given to a worker to cover "the hours of work (including any terms and conditions relating to normal working hours)." A rota that regularly asks someone to work a pattern their written statement does not describe is not a scheduling problem, it is a document that has gone out of date. Flag the mismatch rather than quietly running the rota around it.
5. **Total the hours per worker against the 48-hour average, running.** Show the average so far across the stated reference period for every worker on the rota, not only the ones scheduled for a long week, because a quiet worker who is also covering at a second site can be the one actually over the limit.

## Then it checks

1. The reference period is stated and is 17 weeks or a named agreed alternative, not left blank.
2. Every worker's rolling average is shown against 48 hours, with the weeks it is calculated from.
3. Every shift-to-shift gap for every worker is at least 11 hours, with any gap below that named and dated.
4. Every worker has at least 24 uninterrupted hours in each 7-day period, or the agreed 14-day equivalent, with the actual rest periods shown.
5. Every worker whose rota pattern differs from their written statement is listed by name and by what differs.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.
- Never silently adjust a rest gap by rounding a shift time; a shift recorded as ending at 23:02 is 23:02, not 23:00.
- Never average a worker's hours across a reference period that includes time with a different employer unless agreed working time from that employer has actually been supplied.
- Young workers are not covered by this skill; use young-worker-rota, because their daily rest, weekly rest and hour limits are different figures under the same Regulations.
- This output is a working document prepared for the owner to check against their own written particulars, staff agreements and current rota, and for their adviser to check where a reference period agreement or an opt-out is unclear. It applies the Working Time Regulations 1998 to a draft rota; it is not legal advice and it is not confirmation that the published rota complies.

## Built from
- The Working Time Regulations 1998, regulation 4, https://www.legislation.gov.uk/uksi/1998/1833/regulation/4, SI 1998/1833, read 3 November 2026: the 48-hour average limit and the default 17-week reference period, behind step 1.
- The Working Time Regulations 1998, regulation 10, https://www.legislation.gov.uk/uksi/1998/1833/regulation/10, SI 1998/1833, read 3 November 2026: the 11-hour daily rest entitlement, behind step 2.
- The Working Time Regulations 1998, regulation 11, https://www.legislation.gov.uk/uksi/1998/1833/regulation/11, SI 1998/1833, read 3 November 2026: the weekly rest entitlement and the 14-day alternative, behind step 3.
- Employment Rights Act 1996, section 1, https://www.legislation.gov.uk/ukpga/1996/18/section/1, Act of Parliament, read 3 November 2026: the written particulars requirement to state hours of work, behind step 4.

# rota-builder

## You are given
A list of shifts to place: date, start time, end time, role, and site. A list of staff available for that period, each with name, contracted or usual weekly hours, any existing reference-period agreement, and any opt-out agreement reference. Each worker's written particulars extract covering normal hours and days of work, exactly as last issued. The reference period the owner has chosen: `17 weeks` or a named agreed alternative, with the agreement reference. The weekly rest pattern chosen: `24-hour weekly` or `48-hour fortnightly` or `two-24-hour-fortnightly`. Any previous rota period's hours per worker, for the running average.

## Produce
Write into a `./rota-builder-output/` folder:

1. `rota-grid.csv` with columns: `shift_ref`, `date`, `start_time`, `end_time`, `worker_name`, `role`, `site`, `shift_hours`. `shift_ref` is S0001 upward. `shift_hours` is calculated, never estimated.
2. `daily-rest-check.csv` with columns: `worker_name`, `date`, `previous_shift_end`, `next_shift_start`, `gap_hours`, `verdict`. One row per consecutive shift pair per worker. `verdict` is `pass` or `below 11 hours`.
3. `weekly-rest-check.csv` with columns: `worker_name`, `period_start`, `period_end`, `pattern_applied`, `rest_periods_found`, `longest_single_rest_hours`, `verdict`. `verdict` is `pass` or `rest period not met`.
4. `hours-average.csv` with columns: `worker_name`, `reference_period`, `period_start`, `period_end`, `total_hours_this_rota`, `total_hours_including_prior_periods`, `weeks_counted`, `average_hours_per_week`, `verdict`. `verdict` is `pass` or `average exceeds 48 hours`.
5. `particulars-mismatch.csv` with columns: `worker_name`, `written_hours_or_days`, `rota_hours_or_days`, `mismatch_description`, `flagged`. `flagged` is `yes` or `no`.
6. `gaps.md` - a numbered list of: every `below 11 hours` row; every `rest period not met` row; every `average exceeds 48 hours` row; every `flagged` mismatch row; any shift with no worker assigned; and any worker on the rota with no written particulars extract supplied.

## Rules
- Codex counts, matches and checks. It never invents a reference period, a rest pattern, or a worker's contracted hours, and it never decides who should work which shift.
- `shift_hours` and `gap_hours` are calculated from the supplied start and end times to the minute, never rounded in the worker's favour or the employer's.
- A reference period or rest pattern not supplied is not assumed; record it as missing in `gaps.md` and do not calculate the checks that depend on it.
- Every figure in `hours-average.csv` must show its arithmetic: weeks counted and the period dates, not the average alone.
- Never recommend who to schedule, never remove a worker from the rota to fix a breach, and never change a shift time to make a check pass. Report the breach; the owner decides the fix.
- Use British English, GBP where money appears, and DD Month YYYY dates. No em dashes in any file you write.
- Every file ends with this line: this is a working document prepared for the owner to check against their own written particulars, staff agreements and current rota, and for their adviser to check where a reference period agreement or an opt-out is unclear. It applies the Working Time Regulations 1998 to a draft rota and is not confirmation that the published rota complies.

## Return
The absolute path of each file written and the row count of each CSV. The reference period and rest pattern used. The number of shifts placed and the number left unassigned. Every `below 11 hours` and `rest period not met` row, stated in full with worker and date. Every worker's running average against 48 hours, stated with the weeks counted. The number of `flagged` particulars mismatches and what each one is. The `gaps.md` item count.