Calendar Overload Detector

What this skill does

Reads an iCal (.ics) export and identifies weeks where meeting density exceeds a threshold, the longest unbroken focus block, and which recurring meetings contribute most. Outputs a list of meetings to decline or shorten.

Inputs

• ics_path: a .ics file (Google/Outlook/Apple all export this format).
• Optional working_hours: e.g., 09:00-18:00 (default).
• Optional overload_threshold_pct: percent of working hours in meetings that triggers overload (default 60).
• Optional min_focus_block_minutes: defaults to 90.

Steps

1. Parse the .ics with a small VEVENT reader. Skip cancelled events (STATUS:CANCELLED).
2. Expand recurring events using RRULE expansion (use a library like rrule.js or python-dateutil).
3. Filter events to those where the user is a required attendee (DECLINED responses skipped).
4. Bucket events into ISO weeks. For each week, compute total meeting minutes within working hours.
5. Compute the longest contiguous focus block per day (gap between meetings).
6. Mark weeks as overload if meeting_pct > threshold or if any day has zero focus blocks of length >= min_focus_block_minutes.
7. For each overloaded week, rank meetings by "decline-friendliness":
   • Recurring + low-attendance + you're not the organizer = high.
   • 1:1 with manager = low.
   • Status meeting with > 8 attendees = high.
8. Recommend a focus-time policy: e.g., block 9-11 every weekday on the calendar; don't accept meetings before 10 on Mondays.
9. Render a markdown report.

Output

calendar-overload.md with: per-week summary (meeting %, longest focus block), overload list with proposed declines, and a recommended focus-time policy. Stdout prints overload week count.

Verification

For each declined-meeting suggestion, verify: (a) you're not the organizer, (b) you've attended fewer than 50% of past instances, (c) declining doesn't break a chain (e.g., series-only-required attendee). Re-read your past 4 weeks: implementing the focus-time policy should reduce overload weeks visibly. If it wouldn't (mostly 1:1s), the bottleneck isn't recurring meetings; surface that explicitly.

Edge cases

• All-day events (off-sites, conferences): exclude from meeting % computation; they're not interruptions.
• Meetings outside working hours: report under a separate "after-hours" tally; do not double-count.
• Travel time / commute blocks: treat as focus blocks unless explicitly tagged.
• Time zone changes mid-export: use the event's TZ; users traveling may see synthetic overload otherwise.