# How the optimizer scores trips — roamgap

> The efficiency formula and worked examples — how roamgap ranks calendar
> trips by total days off per PTO day spent. Source of truth:
> `specs/ALGORITHM.md` and `specs/PROJECT.md` §3 (served verbatim at
> https://roamgap.ike.work/llms-full.txt); this page paraphrases for public reading.

## The efficiency score

Every trip is scored on one number:

```
efficiency = total days ÷ max(PTO days, 1)
```

A 9-day break that costs 4 PTO days scores 2.25. A fully-free stretch
(weekends and holidays only, no PTO) divides by 1, so a 3-day holiday weekend
scores 3.00. Higher means more time off for each day you spend.

## How trips are found

The optimizer considers every start date and every reasonable length across
the year, then skips any candidate that:

- crosses the `Dec 31 → Jan 1` year boundary,
- intersects a blocked date range,
- spends more PTO than your budget, or
- violates a month / excluded-weekday filter.

It then **drops dominated trips** — if one trip beats another on *both* length
and efficiency, the weaker one is removed — and returns the survivors ranked by
your chosen sort (`efficiency` or `length`). Identical inputs always produce
identical output; ties break by start date, then end date.

## Worked example — Germany, Easter 2026

Good Friday (3 Apr) and Easter Monday (6 Apr) are public holidays, with the
weekend between them.

| Trip | Days | PTO | Efficiency |
| ---- | ---- | --- | ---------- |
| 3–6 Apr | 4 | 0 | 4.00 |
| 2–6 Apr (add Thursday) | 5 | 1 | 5.00 |
| 1–6 Apr (add Wednesday) | 6 | 2 | 3.00 |

`2–6 Apr` wins on efficiency *and* length over `3–6 Apr`, so the shorter one
is dropped. `1–6 Apr` is longer but lower — offered when you sort by length.

## Holidays on a weekend, and bridge days

A public holiday that falls on a weekend is effectively **lost** — it does not
reduce the PTO a trip needs — and we flag it. Some countries instead observe a
**substitute** holiday on the next working day; we use whichever your country
actually observes.

A **bridge day** is a single working day wedged between a holiday and a
weekend. Spending it as PTO turns a 3-day stretch into four or more — the
highest-leverage day you can spend — and we surface it as a suggestion rather
than forcing it into a trip.

## The annual planner

Given a whole-year PTO budget, the planner returns **five year plans** from the
same candidate pool, each applying a different selection rule:

| Strategy | Key | Optimises for |
| -------- | --- | ------------- |
| Packed · Best leverage | `packed-efficiency` | The most total days off per PTO day spent. |
| Packed · Longest breaks | `packed-length` | The longest continuous breaks. |
| Spread · Quarterly | `spread-quarterly` | Roughly one break per quarter. |
| Spread · Even | `spread-even` | Breaks spaced evenly through the year. |
| One big trip | `single-long` | The whole budget on a single long break. |

Budget mode is either `exhaust` (spend the whole budget) or `selective` (stop
once the next trip's efficiency drops below the worthwhile floor).

## Source

- This page: https://roamgap.ike.work/about/algorithm
- Plain-language concepts: https://roamgap.ike.work/about/how-it-works
- Full normative spec (verbatim): https://roamgap.ike.work/llms-full.txt
- Plan your year: https://roamgap.ike.work/year