holiday-fairness

---
name: holiday-fairness
description: Calculates each worker's actual holiday entitlement from their real contract type, full-time, part-time regular hours, or irregular hours and casual, using the method GOV.UK sets for that type rather than one formula applied to everyone on the rota, and then checks the figure against what they have actually been given or paid. Fairness here means the correct calculation for each person's own pattern, not an equal number of days handed out regardless of how differently people actually work. Use whenever you are setting up leave for a new starter, auditing a year's holiday records, or a worker on irregular shifts asks what they are owed.
---

# Holiday worked out from each person's actual pattern, not one number for everyone

You give this each worker's contract type and hours pattern, and the leave they have taken or been paid for so far. You get back their correct entitlement calculated the GOV.UK way for their specific pattern, and a flag on anyone whose record does not match it.

## What it does

1. **Start from the statutory minimum, not a round number someone remembers.** GOV.UK states: "Almost all people classed as workers are legally entitled to 5.6 weeks' paid holiday a year." For a worker on a standard five-day week that is 28 days, but the figure is defined in weeks, which is what makes every other calculation in this skill possible for patterns that are not five equal days.
2. **Pro-rate a part-time regular-hours worker by their own days, not by a fraction of 28.** GOV.UK's worked example: a part-time worker on regular hours who "works 3 days a week" "must get at least 16.8 days' leave a year (3 × 5.6)." The multiplication is always days worked per week times 5.6, applied to that worker's own pattern, never a fraction of a full-time figure borrowed from someone else's rota.
3. **Choose how a regular-hours worker's leave is tracked, and apply it consistently.** For regular-hours workers, GOV.UK allows either "a 'leave year' or an 'accrual' system", and under accrual "a worker gets one-twelfth of their leave in each month." Pick one system for each worker and use it for their whole leave year; do not mix a leave-year allowance with an accrual-style monthly top-up for the same person.
4. **Use the specific accrual formula for irregular-hours and part-year workers, because the normal methods do not fit them.** GOV.UK states that "for irregular-hours and part-year workers, employers must use a specific accrual system", under which "their entitlement will be 12.07% of the hours they worked in a pay period", and the result "must be rounded up to the nearest hour if the entitlement is 0.5 of an hour or more." This is the method that actually fits a casual bar or kitchen worker whose hours vary week to week, and applying a part-timer's day-based formula to them instead produces the wrong number every time.
5. **Decide bank holidays separately from the statutory minimum, and say which way the business has decided it.** GOV.UK is explicit that "an employer can choose to include bank holidays as part of a worker's statutory annual leave" and that "bank or public holidays do not have to be given as paid leave" at all. Fairness fails here when different workers are quietly treated differently, one rota's bank holiday counted as a day off within their allowance, another's given on top, with nobody having decided it on purpose.

## Then it checks

1. Every worker's contract type, full-time, part-time regular hours, or irregular/part-year, is recorded, and the matching GOV.UK method is the one actually used.
2. Every part-time regular-hours figure shows the days-per-week times 5.6 calculation, not a number copied from elsewhere.
3. Every irregular-hours or part-year figure shows the 12.07% calculation against actual hours worked in the pay period, with the rounding applied correctly.
4. The business's bank holiday decision, included in the statutory allowance or given separately, is stated once and applied the same way to every worker of the same contract type.
5. Any worker whose recorded leave taken or paid does not match their calculated entitlement is listed by name with both figures shown.

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 apply the part-time days-per-week formula to a worker whose hours genuinely vary week to week; use the 12.07% method for that person instead.
- Never round down an irregular-hours entitlement; GOV.UK's rule rounds up at 0.5 of an hour or more.
- Never treat a bank holiday decision as already made for a worker just because it was made for a different contract type on the same rota.
- This output is a working document prepared for the owner to check against their own payroll and leave records, and for their accountant or adviser to check any transitional leave-year question. It applies GOV.UK's published calculation methods to the figures supplied; it is not legal advice and it is not confirmation that every worker's leave record is correct.

## Built from
- GOV.UK, "Holiday entitlement", https://www.gov.uk/holiday-entitlement-rights, published by the Department for Business and Trade, no revision date shown on the page, read 3 November 2026: the 5.6-week statutory minimum, the part-time pro-rata example, and the bank holiday rule, behind steps 1, 2 and 5.
- GOV.UK, "Calculate holiday entitlement", https://www.gov.uk/holiday-entitlement-rights/calculate-leave-entitlement, published by the Department for Business and Trade, no revision date shown on the page, read 3 November 2026: the leave-year versus accrual choice for regular-hours workers, the 12.07% method for irregular-hours and part-year workers, and the rounding rule, behind steps 3 and 4.

# holiday-fairness

## You are given
Each worker's name, contract type (`full-time`, `part-time regular hours`, or `irregular hours or part-year`), and their agreed pattern: days per week for a regular-hours worker, or hours worked per pay period for an irregular-hours worker. The leave tracking method in use for regular-hours workers: `leave year` or `accrual`. The business's bank holiday decision: `included in statutory allowance` or `given separately`. Leave already taken or paid for each worker this leave year, with dates and hours or days.

## Produce
Write into a `./holiday-fairness-output/` folder:

1. `worker-entitlement.csv` with columns: `worker_name`, `contract_type`, `pattern_input`, `method_used`, `calculation_shown`, `entitlement_calculated`, `unit`. `method_used` is exactly one of `5.6 x days per week`, `12.07% of hours worked, rounded`, or `5.6 weeks, full-time baseline`. `unit` is `days` or `hours`. `calculation_shown` states the actual arithmetic performed, not the result alone.
2. `irregular-hours-detail.csv` with columns: `worker_name`, `pay_period`, `hours_worked_this_period`, `raw_entitlement_hours`, `rounding_applied`, `rounded_entitlement_hours`. One row per pay period per irregular-hours worker. `rounding_applied` is `yes` if the raw figure's decimal part is 0.5 or more, otherwise `no`.
3. `bank-holiday-record.csv` with columns: `worker_name`, `contract_type`, `bank_holiday_treatment`, `consistent_with_contract_type_group`. `consistent_with_contract_type_group` is `yes` or `no`, comparing this worker's treatment against every other worker of the same contract type.
4. `leave-reconciliation.csv` with columns: `worker_name`, `entitlement_calculated`, `leave_taken_or_paid`, `unit`, `difference`, `verdict`. `verdict` is `matches`, `worker owed more`, or `worker has taken more than entitled`.
5. `gaps.md` - a numbered list of: every worker whose `method_used` does not match their stated `contract_type`; every `consistent_with_contract_type_group` row marked `no`; every `leave-reconciliation.csv` row that is not `matches`; and any worker with no pattern input or no leave-taken record supplied.

## Rules
- Codex counts and calculates. It never decides a worker's contract type, never invents hours worked or leave taken, and never decides the business's bank holiday policy; it only checks the policy is applied consistently to what was supplied.
- The 12.07% calculation and its rounding are applied exactly as GOV.UK states them: round up only where the decimal part of the raw figure is 0.5 of an hour or more.
- Every `calculation_shown` entry must show the actual numbers multiplied or percentaged, never the result alone.
- Never apply the days-per-week formula to a worker marked `irregular hours or part-year`, and never apply the 12.07% formula to a worker marked `part-time regular hours`.
- Use British English, GBP where pay 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 payroll and leave records, and for their accountant or adviser to check any transitional leave-year question. It applies GOV.UK's published calculation methods to the figures supplied and is not confirmation that every worker's leave record is correct.

## Return
The absolute path of each file written and the row count of each CSV. Every worker's entitlement calculation shown in full, with the method used. Every bank holiday inconsistency within a contract type group. Every reconciliation row that is not `matches`, stated with both figures. The `gaps.md` item count.