CRITICAL RULES - READ BEFORE PROCESSING ANY EMAIL

1. 1. NEVER CALL gog DIRECTLY - ALWAYS use wrapper scripts (create_event.sh, email_read.sh, etc.). Direct gog calls bypass tracking and cause duplicates. THIS IS NON-NEGOTIABLE.
2. IGNORE CALENDAR NOTIFICATIONS - DO NOT process emails from calendar-notification@google.com (Accepted:, Declined:, Tentative:, etc.). These are responses to existing invites, NOT new events. Run process_calendar_replies.sh to archive them.
3. ALWAYS ASK BEFORE CREATING - Never create calendar events without explicit user confirmation in the current conversation
4. CHECK IF ALREADY PROCESSED - Before processing any email, check processed_emails in index.json
5. READ CONFIG FIRST - Load and apply ignore_patterns and auto_create_patterns before presenting events
6. READ MEMORY.MD - Check for user preferences stored from previous sessions
7. INCLUDE ALL CONFIGURED ATTENDEES - When creating/updating/deleting events, always include attendees from config with --attendees flag (and --send-updates all if supported)
8. CHECK TRACKED EVENTS FIRST - Use lookup_event.sh --email-id to find existing events before calendar search (faster, more reliable)
9. TRACK ALL CREATED EVENTS - The create_event.sh script automatically tracks events; use tracked IDs for updates/deletions
10. SHOW DAY-OF-WEEK - Always include the day of week when presenting events for user verification

⛔ FORBIDDEN: DO NOT USE gog COMMANDS DIRECTLY ⛔
WRONG: gog calendar create ... or gog gmail ...
RIGHT: "$SCRIPTS_DIR/create_event.sh" ... or "$SCRIPTS_DIR/email_read.sh" ...
Direct CLI calls bypass event tracking, break duplicate detection, and cause duplicate events.
ALL operations MUST go through the wrapper scripts in scripts/.

Email to Calendar Skill

Extract calendar events and action items from emails, present them for review, and create/update calendar events with duplicate detection and undo support.

First-time setup: See SETUP.md for configuration options and smart onboarding.

Reading Email Content

IMPORTANT: Before you can extract events, you must read the email body. Use the wrapper scripts.

CODEBLOCK0

Note on stale forwards: Don't use newer_than:1d because it checks the email's original date header, not when it was received. Process all UNREAD emails and rely on the "already processed" check.

Workflow

0. Pre-Processing Checks (MANDATORY)

CODEBLOCK1

1. Find Emails to Process

DIRECT mode: Scan all unread emails for event indicators (dates, times, meeting keywords).

FORWARDED mode: Only process emails with forwarded indicators (Fwd:, forwarded message headers).

2. Extract Events (Agent does this directly)

Read the email and extract events as structured data. Include for each event:

• - title: Descriptive name (max 80 chars)
• date: Event date(s)
• dayofweek: For verification
• time: Start/end times (default: 9 AM - 5 PM)
• ismultiday: Whether it spans multiple days
• isrecurring: Whether it repeats (and pattern)
• confidence: high/medium/low
• urls: Any URLs found in the email (REQUIRED - always look for registration links, info pages, ticketing sites, etc.)
• deadlinedate: RSVP/registration/ticket deadline date (if found)
• deadlineaction: What user needs to do (e.g., "RSVP", "get tickets", "register")
• deadlineurl: Direct link for taking action (often same as event URL)

URL Extraction Rule: ALWAYS scan the email for URLs and include the most relevant one at the BEGINNING of the event description.

2.1 Deadline Detection

Scan the email for deadline patterns that indicate action is required before the event:

Common Deadline Patterns:

• - "RSVP by [date]", "Please RSVP by [date]"
• "Register by [date]", "Registration closes [date]"
• "Tickets available until [date]", "Get tickets by [date]"
• "Early bird ends [date]", "Early registration deadline [date]"
• "Must respond by [date]", "Respond by [date]"
• "Sign up by [date]", "Sign up deadline [date]"
• "Deadline: [date]", "Due by [date]"
• "Last day to [action]: [date]"

When a deadline is found:

1. 1. Extract the deadline date
2. Determine the required action (RSVP, register, buy tickets, etc.)
3. Find the URL for taking that action
4. Flag the event for special handling (see sections below)

3. Present Items to User and WAIT

Apply event rules, then present with numbered selection:

CODEBLOCK2

STOP AND WAIT for user response.

After presenting, record pending invites for follow-up reminders:
CODEBLOCK3

4. Check for Duplicates (MANDATORY)

ALWAYS check before creating any event:

CODEBLOCK4

Use LLM semantic matching for fuzzy duplicates (e.g., "Team Offsite" vs "Team Offsite 5-6pm").

5. Create or Update Calendar Events

Use create_event.sh (recommended) - handles date parsing, tracking, and changelog:

CODEBLOCK5

For direct gog commands and advanced options, see references/gog-commands.md.

6. Email Disposition (Automatic)

Email disposition (mark as read and/or archive) is handled automatically by create_event.sh based on config settings. No manual step needed - emails are dispositioned after event creation.

To manually disposition an email:
CODEBLOCK6

To process calendar reply emails (accepts, declines, tentatives):
CODEBLOCK7

CODEBLOCK8

Event Creation Rules

Date/Time Handling

• - Single-day events: Default 9:00 AM - 5:00 PM
• Multi-day events (e.g., Feb 2-6): Use INLINECODE21
• Events with specific times: Use exact time from email

Event Descriptions

Format event descriptions in this order:

1. 1. ACTION WARNING (if deadline exists):

1. 2. Event Link (if URL found):

1. 3. Event Details: Information extracted from the email

Example WITH deadline:
CODEBLOCK11

Example WITHOUT deadline:
CODEBLOCK12

Duplicate Detection

• - Same date AND similar title (semantic matching) AND overlapping time

Always update existing events rather than creating duplicates.

Creating Deadline Events

When an event has a deadline (RSVP, registration, ticket purchase, etc.), create TWO calendar events:

1. Main Event (as normal, but with warning in description):
CODEBLOCK13

2. Deadline Reminder Event (separate event on the deadline date):
CODEBLOCK14

Deadline Event Properties:

• - Title format: INLINECODE22
• Date: The deadline date
• Time: 9:00 AM (30 minute duration)
• Reminders: Email 1 day before + popup 1 hour before
• Description: Action required, URL, reference to main event

Email Notifications for Deadlines

When creating events with deadlines, send a notification email to alert the user:

CODEBLOCK15

When to send notifications:

• - Only when deadline_notifications.enabled is true in config
• Only for events that have action-required deadlines
• Include the deadline date, action, URL, and event details

Activity Log

CODEBLOCK16

Changelog and Undo

Changes can be undone within 24 hours:

CODEBLOCK17

Pending Invites

Events not immediately actioned are tracked for reminders:

CODEBLOCK18

Event Tracking

CODEBLOCK19

File Locations

References

• - Setup Guide: SETUP.md - Configuration and onboarding
• CLI Reference: references/gog-commands.md - Detailed gog CLI usage
• Extraction Patterns: references/extraction-patterns.md - Date/time parsing
• Workflow Example: references/workflow-example.md - Complete example

Notes

Date Parsing

• - January 15, 2026, Wednesday January 15
• 01/15/2026, 15/01/2026
• Date ranges like "Feb 2-6"

Time Zones