inbox-cleanup

# Inbox Cleanup Skill

A playbook for large-scale email inbox cleanup. The core insight: sender-based scans are low-recall. Subject/body pattern queries catch 25x more archivable email. This skill is a multi-pass pipeline built around that insight.

Works with any connected email provider. Adapt query syntax to whatever the provider supports — the strategy (what to search for, how to decide what to archive) is universal.

> **Gmail is a required integration.** It's declared via `includes: ["gmail"]` in the frontmatter so it loads synchronously on activation, not lazily after the preferences form. Load/confirm the Gmail integration the moment this skill activates — before Phase 1 — so a missing or unauthorized connection surfaces up front rather than mid-cleanup.

---

## Phase 1: Preference Capture

Do this before touching anything. Ask the user:

**1. Aggressiveness level**

- _Conservative_ — newsletters with unsubscribe headers + obvious spam only
- _Standard_ — above + cold outreach heuristics (subject patterns, unknown senders)
- _Aggressive_ — above + anything from senders with no prior thread history

**2. Age threshold**
Archive everything older than X days? Common choices: 30 / 60 / 90 days. Or no age filter.

> **First-run scope:** On first invocation, scope to last 30 days or top 3 noise patterns, whichever surfaces faster. Show result, offer to expand. Prove the approach on a fast, visible slice before draining the whole backlog.

**3. VIP senders to protect**
Ask: "Are there any senders that might look like cold outreach but you actually care about? Think: specific individuals at investors, advisors, your lawyer, accountant, recruiters you're actively working with."

Build an explicit keep list. Do not archive anything matching it, ever, regardless of aggressiveness.

**4. Categories to confirm before archiving**
These need a sample + explicit approval before bulk action:

- Financial/billing alerts
- Legal/contracts
- Account suspension notices
- Government/regulatory

---

## Phase 2: Urgency Triage (do this before any archiving)

Scan the inbox first for high-stakes items that should be _surfaced_, not archived. Look for:

| Signal                                                            | Why it matters                                |
| ----------------------------------------------------------------- | --------------------------------------------- |
| "past due", "overdue", "final notice", "balance due"              | Outstanding invoice — financial consequence   |
| "will be suspended", "account suspension", "service interruption" | Service shutoff — operational consequence     |
| "collections", "case #", "recovery" in sender domain              | Collections agency — credit/legal consequence |
| "signature required", "agreement", "DocuSign pending"             | Legal action needed                           |
| Government TLDs (.gov), "IRS", "state of", "department of"        | Regulatory — can't be skipped                 |

Surface these to the user _before_ running the cleanup. They're easy to miss buried in a big inbox.

---

## Phase 3: The Query Pipeline

Run these passes in order. Each pass should paginate to exhaustion (keep fetching while more results exist). After each pass, **show the user a count + 5 sample subjects** before archiving anything.

### Pass 1: Age-based bulk (biggest catch)

Search for all inbox messages older than the user's age threshold (e.g. 30 days). Typically 50–80% of the archivable backlog. Always show a sample before bulk archiving.

> **Note on result caps:** Some providers cap query results (e.g. ~5,000). If a query returns exactly at the cap, archive that batch and re-run the same query — the next batch will surface. Repeat until it returns fewer than the cap.

### Pass 2: Personalized cold outreach (subject patterns)

Ask the user for their first name and company name, then search for subject lines containing patterns like:

- `[FirstName] -`, `[FirstName],`, `for [FirstName]`, `hi [FirstName]`, `hey [FirstName]`, `[FirstName] |`
- `[CompanyName] -`, `[CompanyName]?`, `for [CompanyName]`, `re: [CompanyName]`, `[CompanyName] AI`

These are the highest-recall patterns for cold outreach and partnership spam. A startup founder's inbox will see the biggest wins here.

### Pass 3: Generic cold outreach phrases

Search for subject lines containing:

- "quick question", "quick note", "checking in"
- "following up", "just following up", "circling back"
- "would love to connect", "15 minutes", "quick call"
- "intro call", "reaching out", "came across your"
- "are you the right person", "happy to hop on"

### Pass 4: No-reply & newsletters

Search for:

- Messages from noreply/no-reply/donotreply sender addresses
- Subject lines containing "unsubscribe", "newsletter", "weekly digest", "monthly digest"

### Pass 5: Calendar noise

Search for subject lines containing:

- "accepted:", "declined:", "tentative:"
- "has accepted", "has declined", "invitation:"

Calendar response confirmations are pure noise. Safe to bulk archive without review.

### Pass 6: Transactional/receipts

Search for subject lines containing:

- "your order", "order confirmation", "your receipt"
- "shipment", "has shipped", "delivered"

Cross-check against urgency triage first — filter out any "past due" or "final notice" items before archiving this batch.

### Pass 7: Sketchy TLDs

Search for messages from sender domains ending in `.shop`, `.biz`, `.xyz`, `.info`, `.club`, `.online`.

Disproportionately spam. Safe to bulk archive.

### Pass 8: High-volume repeat senders

After the above passes, run a sender frequency count on what remains. Any sender with 3+ emails not on the keep list is a candidate for bulk archive. Show grouped list to user for approval.

---

## Phase 4: Cold Outreach Classification

For emails not caught by pattern queries, use LLM-based classification in Standard/Aggressive mode. Flag as cold outreach if **3+ signals** are present:

- Sender d