Gmail Labeler

A production-oriented Gmail labeling workflow built around:

• - gog for Gmail access
• a local overlay for private rules/accounts/routes
• a hybrid review flow: heuristics first, lightweight LLM review for ambiguity-band messages
• a 15-minute cron-friendly runner

What it does

• - Classifies inbox items into non-actionable vs actionable buckets
• Applies Gmail labels and archives non-actionable mail
• Keeps replies, opportunities, urgent billing items, and other actionable mail in Inbox
• Supports English, Portuguese, and Spanish keyword coverage out of the box
• Logs every decision to JSONL for auditability and tuning
• Purges logs older than 30 days
• Supports a daily self-improvement review loop based on prior decisions and user corrections

Default categories

Non-actionable

• - Newsletters
• Promotions
• Notifications
• Ordinary receipts

Actionable

• - Billing issues
• Replies
• Opportunities
• Action Required

What stays local/private

Keep user-specific editorial, business, or inbox-policy rules in the local overlay, not in the shared skill defaults. Examples of local-only rules:

• - PR / press release handling
• press trip or media invitation routing
• VIP sender policies
• business-specific labels
• custom notification routes

Operating model

1. Sender-type-first routing

Classify sender as:

• - INLINECODE1
• INLINECODE2
• INLINECODE3

This keeps bulk automated mail cheap to classify and reserves deeper review for ambiguous or human-origin messages.

2. Inbox-by-exception policy

Treat Inbox as an action queue, not a reading queue. Recommended default:

• - processed mail always gets INLINECODE4
• mail stays in Inbox only when it is clearly actionable / important
• everything else should leave Inbox, even when the category is still somewhat generic

Practical effect:

• - important/actionable mail → keep in Inbox and add category labels when possible
• non-important mail → remove INBOX, keep Auto/Triaged, then add a best-fit category label (Notification, Newsletter, Receipt, Press Releases, etc.)

3. Confidence-band review

Use heuristics first. Then send only ambiguity-band messages to a lightweight LLM review.

Recommended pattern:

• - high confidence → trust heuristics
• medium confidence → LLM review
• low confidence → conservative fallback

4. Conservative-but-useful fallback

If a message is clearly automated/company-origin but no specific filter matches, prefer a generic non-actionable classification (for example Notification) over leaving it untouched in Inbox.

5. Label normalization

Use a small canonical label set and avoid near-duplicates caused by translation, singular/plural, or typos. Example normalization targets:

• - Press Release → INLINECODE13
• finance label variants → one canonical finance label
• keep Auto/Triaged as the universal processed marker

Gmail-native labels to prefer

Use Gmail system labels when possible:

• - INLINECODE15
• INLINECODE16
• INLINECODE17
• INLINECODE18
• INLINECODE19

Create custom labels only when needed, for example:

• - INLINECODE20
• INLINECODE21
• INLINECODE22
• INLINECODE23
• INLINECODE24
• INLINECODE25

Local overlay design

Keep the skill publishable by storing private configuration outside the skill directory.

Recommended local overlay path:
CODEBLOCK0

Store private values only in the local overlay:

• - email accounts
• VIP senders/domains
• notification targets
• business-specific opportunity rules
• personal/custom labels

Logging and review

Decision logs should live outside the skill source tree, for example: CODEBLOCK1

Recommended format:

• - one JSONL file per day
• one row per decision
• separate error rows

Suggested daily review inputs:

• - yesterday's decision log
• false positives / false negatives
• over-aggressive archiving
• missed billing urgency
• missed opportunities
• user-requested corrections

Files to read

• - INLINECODE26
• INLINECODE27
• INLINECODE28
• INLINECODE29
• INLINECODE30
• INLINECODE31
• INLINECODE32
• INLINECODE33

Runners

• - Main runner: INLINECODE34
• Launcher example: INLINECODE35

Publishing guidance

Before publishing:

• - keep only generic defaults in the skill
• remove personal accounts, chat ids, private domains, and custom user rules
• keep examples generic
• document clearly that private configuration belongs in the local overlay
• keep PR / press-release handling user-specific when it reflects private editorial policy; do not publish those local heuristics by default
• validate cron/non-interactive execution via the launcher, not only via direct Python invocation