Timezone Meeting Window Finder

What this skill does

Given participants' timezones (and optional working-hours ranges), finds three candidate meeting windows in the next two weeks, computes each participant's local time, and reports a fairness score that penalizes after-hours impositions on minority TZs.

Inputs

• participants: array of {name, tz, working_hours?}. tz is an IANA name like America/New_York. working_hours default 09:00-18:00.
• Optional duration_minutes: defaults 30.
• Optional lookahead_days: defaults 14.
• Optional weights: per-participant importance weights for fairness (default 1).

Steps

1. Validate every tz against the IANA tz database (the OS tzdata or Intl.supportedValuesOf('timeZone')).
2. For each 30-minute slot in lookahead_days * 24 * 2 slots over UTC, compute each participant's local time.
3. Mark a slot as "in-hours" for a participant if local time falls within their working_hours.
4. Skip weekends per each participant's local week (Sat/Sun by default; configurable per participant for Mon-first vs Sun-first regions).
5. Compute slot fairness score: sum of weights for in-hours participants minus 0.5 * sum of weights for out-of-hours.
6. Apply secondary penalty: heavily penalize slots where a participant is awake before 07:00 or after 21:00 local.
7. Sort slots by fairness desc; collapse consecutive slots into windows of duration_minutes.
8. Pick top 3 windows that don't overlap each other.
9. Render each candidate with: UTC time, each participant's local time, fairness score, any "stretching" notes.
10. Save to meeting-windows.md.

Output

meeting-windows.md listing the three candidate windows with: UTC start, per-participant local times in a small table, fairness score, and a note for any participant whose local time falls outside working_hours. Plus an .ics file with each candidate as a tentative event.

Verification

Pick one candidate and verify each participant's local time using TZ=<tz> date -d "<UTC time>"; results must match. For the chosen window, confirm working_hours are honored where possible. If no slot satisfies all participants, the report must explicitly say so and propose the least-bad windows with stretching notes.

Edge cases

• DST transitions during the lookahead: tzdata handles this; spot-check across a transition date.
• Participants with shifted working hours (e.g., night shift): respect their declared range; do not assume 9-6.
• Holiday calendars: not modeled; surface a note recommending an external check.
• Three-continent splits where no overlap exists: surface "no fair window; consider rotating the burden weekly" and propose alternates that rotate hardship.