calendar

Original source / Raw SKILL.md

---
name: calendar
description: Manage Google Calendar with full event operations including viewing schedule, creating/editing/deleting events, finding free time, managing attendees via Google Contacts, adding Google Meet links, and timezone handling. This skill should be used for ALL calendar-related requests.
category: productivity
version: 1.0.0
---

# Google Calendar Management Skill

## Purpose

Manage Arlen Greer's Google Calendar with comprehensive event operations:
- View schedule (today, this week, date ranges)
- Create events with attendees and Google Meet links
- Update and delete events
- Find free time slots during business hours
- Automatic attendee resolution via Google Contacts
- Timezone-aware scheduling
- Block time for focused work

**Primary Calendar**: Uses primary personal calendar by default

## When to Use This Skill

Use this skill when:
- User requests calendar information: "What's on my calendar?", "Show my schedule"
- User wants to create events: "Schedule a meeting", "Create an appointment"
- User wants to modify events: "Move my meeting", "Update the appointment"
- User asks about availability: "When am I free?", "Find time next week"
- User mentions scheduling with others: "Set up a call with [Name]"
- User requests Google Meet: "Add a video call", "Create a Google Meet"

## Core Workflows

### 1. View Schedule

**List today's events**:
```bash
scripts/calendar_manager.rb --operation list
```

**List specific date range**:
```bash
scripts/calendar_manager.rb --operation list \
  --time-min "2024-10-31T00:00:00" \
  --time-max "2024-10-31T23:59:59"
```

**List this week**:
```bash
scripts/calendar_manager.rb --operation list \
  --time-min "2024-10-28T00:00:00" \
  --time-max "2024-11-04T23:59:59" \
  --max-results 50
```

**Natural language time parsing**:
- Accepts ISO8601 format or natural language
- Example: "tomorrow at 3pm", "next Tuesday at 9am"

### 2. Create Events

**Simple event creation**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Team Meeting" \
  --start-time "2024-10-31T15:00:00" \
  --end-time "2024-10-31T16:00:00"
```

**Event with attendees (by name)**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Upgrade Database Discussion" \
  --start-time "2024-10-31T15:00:00" \
  --end-time "2024-10-31T16:00:00" \
  --attendees "Ed Korkuch,Mark Whitney"
```

**Attendee Resolution**:
- Automatically looks up contacts by name via Google Contacts API
- Falls back to email address if name includes '@'
- Returns error if contact not found (prompts user for email)

**Event with Google Meet**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Team Standup" \
  --start-time "2024-11-01T09:00:00" \
  --google-meet
```

**Block time for work**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Focus Time - Database Upgrade" \
  --description "Blocked time to work on database migration" \
  --start-time "2024-11-05T09:00:00" \
  --end-time "2024-11-05T11:00:00"
```

**Event with all options**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Client Meeting" \
  --description "Discuss Q4 requirements" \
  --location "Conference Room A" \
  --start-time "2024-11-01T14:00:00" \
  --end-time "2024-11-01T15:00:00" \
  --attendees "[email protected]" \
  --google-meet
```

### 3. Update Events

**Update event time**:
```bash
scripts/calendar_manager.rb --operation update \
  --event-id "abc123xyz" \
  --start-time "2024-10-31T16:00:00" \
  --end-time "2024-10-31T17:00:00"
```

**Update event details**:
```bash
scripts/calendar_manager.rb --operation update \
  --event-id "abc123xyz" \
  --summary "Updated Meeting Title" \
  --description "New description"
```

**Getting Event ID**:
- List events first to get the event ID
- Event IDs are returned in all list operations

### 4. Delete Events

```bash
scripts/calendar_manager.rb --operation delete \
  --event-id "abc123xyz"
```

### 5. Find Free Time

**Find next available slot**:
```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-01T00:00:00" \
  --time-max "2024-11-08T23:59:59" \
  --duration 3600 \
  --max-results 5
```

**Find 2-hour blocks during business hours**:
```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-05T00:00:00" \
  --time-max "2024-11-05T23:59:59" \
  --duration 7200 \
  --business-start 9 \
  --business-end 17
```

**Find time parameters**:
- `--duration`: Slot duration in seconds (default: 3600 = 1 hour)
- `--business-start`: Business day start hour (default: 9)
- `--business-end`: Business day end hour (default: 17)
- `--interval`: Check interval in seconds (default: 1800 = 30 min)

**IMPORTANT - Lunchtime Policy**:
- **AVOID scheduling meetings during lunch hours (12:00 PM - 1:00 PM) on weekdays**
- When finding free time, filter out any slots that overlap with noon-1pm
- Only suggest lunchtime slots if user explicitly requests them or no other times available
- This applies to all availability checks and meeting scheduling requests

## Natural Language Examples

### User Says: "What's on my calendar today?"
```bash
# Get today's date from <env> context
scripts/calendar_manager.rb --operation list \
  --time-min "[TODAY]T00:00:00" \
  --time-max "[TODAY]T23:59:59"
```

### User Says: "Schedule a meeting with Ed Korkuch for 3:00 p.m. on the 31st of October and name it 'Upgrade Database'"
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Upgrade Database" \
  --start-time "2024-10-31T15:00:00" \
  --end-time "2024-10-31T16:00:00" \
  --attendees "Ed Korkuch"
```

### User Says: "Find a time when I am free next week during business hours"
```bash
# Calculate next week dates
# NOTE: Filter out lunchtime slots (12:00 PM - 1:00 PM) from results unless user explicitly requests lunch hours
scripts/calendar_manager.rb --operation find_free \
  --time-min "[NEXT_WEEK_START]T00:00:00" \
  --time-max "[NEXT_WEEK_END]T23:59:59" \
  --duration 3600 \
  --business-start 9 \
  --business-end 17 \
  --max-results 10
```

### User Says: "Block off two hours during the normal business day next Tuesday for me to work on [issue]"
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Focus Time - [Issue]" \
  --description "Blocked time to work on [issue description]" \
  --start-time "[NEXT_TUESDAY]T09:00:00" \
  --end-time "[NEXT_TUESDAY]T11:00:00"
```

### User Says: "Move my 3pm meeting to 4pm"
```bash
# First list events to find the 3pm meeting
scripts/calendar_manager.rb --operation list --time-min "[TODAY]T15:00:00" --time-max "[TODAY]T15:01:00"

# Then update with new time
scripts/calendar_manager.rb --operation update \
  --event-id "[EVENT_ID_FROM_LIST]" \
  --start-time "[TODAY]T16:00:00" \
  --end-time "[TODAY]T17:00:00"
```

## Timezone Handling

**Default Timezone**: `America/Chicago`

**Specify different timezone**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Meeting" \
  --start-time "2024-10-31T15:00:00" \
  --timezone "America/New_York"
```

**Timezone considerations**:
- All times are stored in the calendar's timezone
- Use `--timezone` flag to specify event timezone
- List operations return times in original timezone
- See `references/timezone_guide.md` for timezone codes

## Authentication Setup

**Shared with Email Skill**:
- Uses same OAuth credentials and token
- Located at: `~/.claude/.google/client_secret.json` and `~/.claude/.google/token.json`
- Requires both Calendar and Contacts API scopes

**First Time Setup**:
1. Run any calendar operation
2. Script will prompt for authorization URL
3. Visit URL and authorize
4. Enter authorization code when prompted
5. Token stored for future use

**Re-authorization**:
- Token automatically refreshes when expired
- If refresh fails, re-run authorization flow

## Bundled Resources

### Scripts

**`scripts/calendar_manager.rb`**
- Comprehensive Google Calendar API wrapper
- All CRUD operations: list, create, update, delete
- Free time finding with business hours logic
- Automatic attendee resolution via Google Contacts
- Google Meet link generation
- Timezone support

**Operations**:
- `list`: View calendar events
- `create`: Create new events
- `update`: Modify existing events
- `delete`: Remove events
- `find_free`: Find available time slots

**Output Format**:
- JSON with `status: 'success'` or `status: 'error'`
- Event objects include: id, summary, start, end, attendees, links
- See script help: `scripts/calendar_manager.rb --help`

### References

**`references/timezone_guide.md`**
- Common timezone codes
- Timezone conversion examples
- Daylight saving time considerations
- International timezone handling

**`references/business_hours.md`**
- Business hours logic and customization
- Finding optimal meeting times
- Blocking focus time strategies
- Calendar best practices

## Error Handling

**Attendee Not Found**:
```json
{
  "status": "error",
  "code": "ATTENDEE_NOT_FOUND",
  "message": "Could not find email for attendee: John Smith"
}
```
**Action**: Prompt user for email address, then retry

**Authentication Error**:
```json
{
  "status": "error",
  "code": "AUTH_ERROR",
  "message": "Token refresh failed: ..."
}
```
**Action**: Guide user through re-authorization

**Invalid Time**:
```json
{
  "status": "error",
  "code": "INVALID_TIME",
  "message": "Failed to parse time: ..."
}
```
**Action**: Ask user to clarify date/time format

**API Error**:
```json
{
  "status": "error",
  "code": "API_ERROR",
  "message": "Failed to create event: ..."
}
```
**Action**: Display error to user, suggest troubleshooting steps

## Best Practices

### Date/Time Parsing
1. Always check current date from `<env>` context
2. Never assume dates from knowledge cutoff
3. Parse natural language: "tomorrow", "next Tuesday", "3pm today"
4. Default to 1-hour duration if end time not specified

### Attendee Management
1. Try contact lookup first for names
2. Fall back to email address if lookup fails
3. Always confirm attendees before sending invites
4. Use comma-separated list for multiple attendees

### Google Meet
1. Add `--google-meet` flag for video calls
2. Meet link auto-generated and included in event
3. All attendees receive calendar invite with link

### Free Time Finding
1. Default to business hours (9am-5pm)
2. **AVOID LUNCHTIME**: Do not suggest times between 12:00 PM - 1:00 PM on weekdays unless user explicitly requests it
3. Use 30-minute intervals for checking
4. Return top 5 slots by default
5. Consider timezone when suggesting times

### Event Updates
1. Always list events first to get event ID
2. Only update specified fields (others unchanged)
3. Send notifications to attendees automatically

## Quick Reference

**View today's schedule**:
```bash
scripts/calendar_manager.rb --operation list
```

**Create meeting with contact**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Meeting Title" \
  --start-time "2024-11-01T14:00:00" \
  --attendees "First Last"
```

**Add Google Meet**:
```bash
# Add --google-meet flag to any create operation
```

**Find free time next week**:
```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "[NEXT_WEEK]T00:00:00" \
  --time-max "[NEXT_WEEK_END]T23:59:59"
```

**Update event time**:
```bash
scripts/calendar_manager.rb --operation update \
  --event-id "[ID]" \
  --start-time "[NEW_TIME]"
```

## Example Workflow: Scheduling a Meeting

1. **Check availability**:
   ```bash
   scripts/calendar_manager.rb --operation find_free \
     --time-min "2024-11-01T00:00:00" \
     --time-max "2024-11-08T23:59:59" \
     --duration 3600
   ```

2. **Create event with attendees**:
   ```bash
   scripts/calendar_manager.rb --operation create \
     --summary "Project Review" \
     --start-time "2024-11-05T14:00:00" \
     --attendees "Ed Korkuch,Mark Whitney" \
     --google-meet
   ```

3. **Confirm creation**:
   - Script returns event ID, summary, links
   - Attendees receive calendar invites
   - Google Meet link automatically included

## Version History

- **1.0.0** (2024-10-28) - Initial calendar skill with full CRUD operations, Google Meet integration, contact lookup for attendees, free time finding, and timezone support

---

**Dependencies**: Ruby with `google-apis-calendar_v3`, `google-apis-people_v1`, `googleauth` gems (same as email skill)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/timezone_guide.md

```markdown
# Timezone Guide

## Common US Timezones

| Timezone | Code | UTC Offset (Standard) | UTC Offset (DST) |
|----------|------|----------------------|------------------|
| Eastern | America/New_York | UTC-5 | UTC-4 |
| Central | America/Chicago | UTC-6 | UTC-5 |
| Mountain | America/Denver | UTC-7 | UTC-6 |
| Pacific | America/Los_Angeles | UTC-8 | UTC-7 |
| Alaska | America/Anchorage | UTC-9 | UTC-8 |
| Hawaii | Pacific/Honolulu | UTC-10 | No DST |

## International Timezones (Common)

| Region | Timezone | Code | UTC Offset |
|--------|----------|------|------------|
| UK | GMT/BST | Europe/London | UTC+0 / UTC+1 |
| Central Europe | CET/CEST | Europe/Paris | UTC+1 / UTC+2 |
| India | IST | Asia/Kolkata | UTC+5:30 |
| China | CST | Asia/Shanghai | UTC+8 |
| Japan | JST | Asia/Tokyo | UTC+9 |
| Australia (Sydney) | AEST/AEDT | Australia/Sydney | UTC+10 / UTC+11 |

## Daylight Saving Time (DST)

### US DST Rules
- **Starts**: Second Sunday in March at 2:00 AM local time
- **Ends**: First Sunday in November at 2:00 AM local time
- **Not Observed**: Hawaii, most of Arizona

### Impact on Scheduling
- Spring forward: Meetings scheduled during "lost hour" (2:00-3:00 AM) may be adjusted
- Fall back: Meetings during duplicated hour need clarification
- Always specify timezone when scheduling across DST transitions

## Timezone Conversion Examples

### Example 1: Chicago to New York
```
Chicago (Central): 2:00 PM CST
New York (Eastern): 3:00 PM EST
Difference: +1 hour
```

### Example 2: Chicago to London
```
Chicago (Central): 9:00 AM CST (Winter)
London (GMT): 3:00 PM GMT
Difference: +6 hours
```

### Example 3: Chicago to Tokyo
```
Chicago (Central): 5:00 PM CST
Tokyo (JST): 10:00 AM JST (next day)
Difference: +15 hours
```

## Best Practices for Timezone Handling

### 1. Always Specify Timezone
```bash
# Good: Explicit timezone
--start-time "2024-10-31T15:00:00" --timezone "America/Chicago"

# Risky: Assumes default timezone
--start-time "2024-10-31T15:00:00"
```

### 2. Use IANA Timezone Database Codes
- ✅ Good: `America/Chicago`, `Europe/London`, `Asia/Tokyo`
- ❌ Bad: `CST`, `GMT`, `JST` (ambiguous, no DST info)

### 3. Consider Attendee Timezones
When scheduling with international attendees:
1. Note each attendee's timezone
2. Find overlap in working hours
3. Specify event in primary user's timezone
4. Calendar automatically converts for attendees

### 4. DST Transition Periods
During first week of March and November:
- Double-check meeting times
- Verify calendar auto-adjusts correctly
- Send confirmation to attendees

## Working Hours by Timezone

### Typical Business Hours (9 AM - 5 PM)

| Location | Timezone | Local Time | Chicago Equivalent |
|----------|----------|------------|-------------------|
| New York | America/New_York | 9 AM - 5 PM EST | 8 AM - 4 PM CST |
| Chicago | America/Chicago | 9 AM - 5 PM CST | 9 AM - 5 PM CST |
| Los Angeles | America/Los_Angeles | 9 AM - 5 PM PST | 11 AM - 7 PM CST |
| London | Europe/London | 9 AM - 5 PM GMT | 3 AM - 11 AM CST |
| Tokyo | Asia/Tokyo | 9 AM - 5 PM JST | 7 PM - 3 AM CST |

### Finding Overlap

**US East Coast + Chicago + West Coast**:
- Overlap: 11 AM - 4 PM CST (10 AM - 3 PM PST, 12 PM - 5 PM EST)
- Best meeting time: 1 PM CST / 12 PM PST / 2 PM EST

**Chicago + London**:
- Overlap: 9 AM - 11 AM CST (3 PM - 5 PM GMT)
- Best meeting time: 10 AM CST / 4 PM GMT

**Chicago + Tokyo**:
- No normal business hours overlap
- Options:
  - Early morning Chicago (7 AM CST = 10 PM JST previous day)
  - Late evening Chicago (9 PM CST = 12 PM JST next day)

## Timezone Detection

### Automatic Detection
The calendar script uses `America/Chicago` as default but allows override:

```bash
# Explicitly set timezone for event
scripts/calendar_manager.rb --operation create \
  --summary "Meeting" \
  --start-time "2024-10-31T15:00:00" \
  --timezone "America/Los_Angeles"
```

### User Travel Considerations
When user is traveling:
1. Check current timezone from system
2. Ask user if they want events in local or home timezone
3. Calendar can show events in any timezone

## Common Timezone Pitfalls

### 1. Ambiguous Abbreviations
```
CST could mean:
- Central Standard Time (UTC-6)
- China Standard Time (UTC+8)
- Cuba Standard Time (UTC-5)

Always use IANA codes: America/Chicago, Asia/Shanghai, America/Havana
```

### 2. All-Day Events
- All-day events don't have timezone
- Display differently based on viewer's timezone
- Be clear when creating: "all-day in what timezone?"

### 3. Recurring Events Across DST
- Meetings may shift by 1 hour relative to other timezones
- Example: Weekly 2 PM CST meeting becomes 3 PM CET after DST change
- Best to review recurring events during DST transitions

## Quick Reference Commands

**Create event with specific timezone**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Meeting" \
  --start-time "2024-10-31T15:00:00" \
  --timezone "America/New_York"
```

**List events (returns times in original timezone)**:
```bash
scripts/calendar_manager.rb --operation list
```

**Find free time in specific timezone**:
```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-01T00:00:00" \
  --time-max "2024-11-08T23:59:59" \
  --timezone "America/Los_Angeles"
```

## Resources

- [IANA Timezone Database](https://www.iana.org/time-zones)
- [Time Zone Converter](https://www.timeanddate.com/worldclock/converter.html)
- [DST Information](https://www.timeanddate.com/time/dst/)

```

### references/business_hours.md

```markdown
# Business Hours Guide

## Default Business Hours

**Standard Configuration**:
- Start: 9:00 AM
- End: 5:00 PM
- Days: Monday - Friday
- Timezone: America/Chicago (default)

## Customizing Business Hours

### Via Command Line Flags

```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-01T00:00:00" \
  --time-max "2024-11-08T23:59:59" \
  --business-start 8 \
  --business-end 18
```

**Parameters**:
- `--business-start`: Hour (0-23) when business day starts
- `--business-end`: Hour (0-23) when business day ends
- Both use 24-hour format

### Common Business Hour Configurations

| Type | Start | End | Use Case |
|------|-------|-----|----------|
| Standard | 9 AM | 5 PM | Traditional office hours |
| Early Bird | 7 AM | 3 PM | Early start preference |
| Standard Extended | 8 AM | 6 PM | Longer workday |
| Tech Industry | 10 AM | 6 PM | Later start, common in tech |
| International | 6 AM | 8 PM | Covering multiple timezones |
| Flexible | 8 AM | 8 PM | Find any reasonable time |

## Finding Optimal Meeting Times

### 1. Single Timezone Scheduling

**Within Same Timezone**:
```bash
# Find 1-hour slots during standard business hours
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-04T00:00:00" \
  --time-max "2024-11-08T23:59:59" \
  --duration 3600 \
  --business-start 9 \
  --business-end 17
```

**Best Practices**:
- Avoid scheduling before 9 AM or after 5 PM
- Consider lunch hour (12 PM - 1 PM) preferences
- Check for existing meeting density

### 2. Multi-Timezone Scheduling

**US Coast-to-Coast** (Eastern + Pacific):
```bash
# Find overlap: 12 PM - 4 PM EST / 9 AM - 1 PM PST
# In Central time: 11 AM - 3 PM CST
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-04T11:00:00" \
  --time-max "2024-11-04T15:00:00" \
  --duration 3600
```

**Chicago + London**:
```bash
# Morning Chicago = Afternoon London
# 9 AM - 11 AM CST = 3 PM - 5 PM GMT
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-04T09:00:00" \
  --time-max "2024-11-04T11:00:00" \
  --duration 3600
```

### 3. Preferred Meeting Times

**Early Morning** (8 AM - 10 AM):
- ✅ Pros: Fresh minds, fewer distractions
- ❌ Cons: May conflict with commutes, not everyone is a morning person

**Mid-Morning** (10 AM - 12 PM):
- ✅ Pros: Everyone settled in, productive time
- ❌ Cons: Often heavily booked

**Early Afternoon** (1 PM - 3 PM):
- ✅ Pros: Post-lunch, good for collaboration
- ❌ Cons: Post-lunch energy dip for some

**Late Afternoon** (3 PM - 5 PM):
- ✅ Pros: Can serve as end-of-day checkpoint
- ❌ Cons: Energy waning, may run over into personal time

**Avoid**:
- 12 PM - 1 PM (lunch hour)
- First 30 min of business day (people settling in)
- Last 30 min of business day (people wrapping up)

## Blocking Focus Time

### Strategy 1: Morning Focus Blocks

**Philosophy**: Protect creative/deep work time in the morning

```bash
# Block 9 AM - 11 AM for focus work
scripts/calendar_manager.rb --operation create \
  --summary "Focus Time - Deep Work" \
  --description "Protected time for concentrated work" \
  --start-time "2024-11-04T09:00:00" \
  --end-time "2024-11-04T11:00:00"
```

**Benefits**:
- Peak cognitive performance
- Fewer interruptions
- Sets productive tone for day

### Strategy 2: Afternoon Focus Blocks

**Philosophy**: After meetings, dedicate time to execution

```bash
# Block 2 PM - 4 PM for focused implementation
scripts/calendar_manager.rb --operation create \
  --summary "Focus Time - Implementation" \
  --description "Blocked time for project work" \
  --start-time "2024-11-04T14:00:00" \
  --end-time "2024-11-04T16:00:00"
```

**Benefits**:
- Action on morning decisions
- Less email/Slack activity
- Buffer before end of day

### Strategy 3: Full-Day Deep Work

**Philosophy**: Entire day dedicated to major project

```bash
# Block full business day (with breaks)
scripts/calendar_manager.rb --operation create \
  --summary "Deep Work Day - Database Migration" \
  --description "Full day blocked for concentrated project work" \
  --start-time "2024-11-05T09:00:00" \
  --end-time "2024-11-05T17:00:00"
```

**When to Use**:
- Major project milestones
- Complex problem-solving needed
- Deadline-driven work
- Recovery after heavily meeting-packed week

### Focus Time Best Practices

1. **Mark as Busy**: Set calendar status to "Busy" not "Free"
2. **Descriptive Titles**: "Focus Time - [Specific Project]"
3. **Recurring Blocks**: Set up weekly recurring focus time
4. **Respect Your Own Blocks**: Treat them as seriously as external meetings
5. **Communicate**: Let team know about regular focus blocks

## Time Slot Duration Guidelines

| Meeting Type | Recommended Duration | Use Case |
|--------------|---------------------|----------|
| Quick Sync | 15 minutes | Status updates, quick questions |
| Standard Meeting | 30 minutes | Most 1:1s, small team discussions |
| Deep Discussion | 1 hour | Project planning, problem solving |
| Workshop/Brainstorm | 2 hours | Collaborative design, team building |
| Training/Presentation | 2-3 hours | Learning sessions, comprehensive reviews |
| Focus Work | 2-4 hours | Deep work on complex problems |

## Calendar Health Best Practices

### 1. Meeting-Free Time Ratios

**Healthy Calendar Balance**:
- 40-50% meetings
- 40-50% focus time
- 10-20% buffer/break time

**Warning Signs**:
- ❌ >70% meetings = Not enough execution time
- ❌ Back-to-back meetings all day = Burnout risk
- ❌ No focus blocks = Reactive mode only

### 2. Buffer Time

**Between Meetings**:
```bash
# Leave 5-10 minute buffers between meetings
# If meeting ends at 11:00, next starts at 11:10
scripts/calendar_manager.rb --operation create \
  --summary "Next Meeting" \
  --start-time "2024-11-04T11:10:00" \
  --end-time "2024-11-04T12:00:00"
```

**Benefits**:
- Bathroom breaks
- Mental transition
- Action items capture
- Travel time between rooms

### 3. No-Meeting Days

**Strategy**: Designate one day per week with minimal/no meetings

```bash
# Block entire Wednesday for focus
scripts/calendar_manager.rb --operation create \
  --summary "No-Meeting Day - Focus Work" \
  --description "Protected day for deep work and project progress" \
  --start-time "2024-11-06T09:00:00" \
  --end-time "2024-11-06T17:00:00"
```

**Common Choices**:
- Wednesday (mid-week balance)
- Friday (wrap up week's work)
- Monday (set intentions for week)

## Finding Free Time: Advanced Techniques

### 1. Next Available Slot

```bash
# Find soonest 1-hour slot this week
scripts/calendar_manager.rb --operation find_free \
  --time-min "$(date -u +%Y-%m-%dT%H:%M:%S)" \
  --time-max "$(date -u -v+7d +%Y-%m-%dT%H:%M:%S)" \
  --duration 3600 \
  --max-results 1
```

### 2. Specific Day Pattern

```bash
# Find Tuesday/Thursday slots only
# (Requires filtering results by day of week)
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-05T00:00:00" \
  --time-max "2024-11-30T23:59:59" \
  --duration 3600
# Then filter for Tuesday/Thursday in results
```

### 3. Long Duration Blocks

```bash
# Find 3-hour blocks for deep work
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-04T00:00:00" \
  --time-max "2024-11-15T23:59:59" \
  --duration 10800 \
  --business-start 9 \
  --business-end 17
```

### 4. Multiple Short Slots

```bash
# Find several 30-minute slots
scripts/calendar_manager.rb --operation find_free \
  --time-min "2024-11-04T00:00:00" \
  --time-max "2024-11-08T23:59:59" \
  --duration 1800 \
  --max-results 10
```

## Time Management Strategies

### 1. Themed Days

Designate days for specific types of work:
- **Monday**: Planning, team meetings
- **Tuesday/Thursday**: External meetings, client calls
- **Wednesday**: Focus day, deep work
- **Friday**: Wrap-up, 1:1s, retrospectives

### 2. Time Blocking

Proactively block time for different activities:
```bash
# Morning: Deep work
# Afternoon: Meetings
# End of day: Email/admin

# Example blocks
scripts/calendar_manager.rb --operation create \
  --summary "Deep Work Block" \
  --start-time "2024-11-04T09:00:00" \
  --end-time "2024-11-04T12:00:00"
```

### 3. Meeting Stacking

Group meetings together to preserve focus blocks:
- ✅ 10-11 AM, 11-12 PM, 1-2 PM (stacked)
- ❌ 10-11 AM, 2-3 PM, 4-5 PM (fragmented)

## Quick Reference

**Find next free slot**:
```bash
scripts/calendar_manager.rb --operation find_free \
  --time-min "[TODAY]" --time-max "[WEEK_END]"
```

**Block focus time**:
```bash
scripts/calendar_manager.rb --operation create \
  --summary "Focus Time" \
  --start-time "[DATE]T09:00:00" \
  --end-time "[DATE]T11:00:00"
```

**Custom business hours**:
```bash
# Add --business-start 8 --business-end 18 to any find_free command
```

## Resources

- [Cal Newport's "Deep Work"](https://www.calnewport.com/books/deep-work/)
- [Maker's Schedule, Manager's Schedule](http://www.paulgraham.com/makersschedule.html)
- [Time Blocking Method](https://todoist.com/productivity-methods/time-blocking)

```