Inbox Management

Inbox Management Skill

Companion to inbox-cleanup. Cleanup drains the backlog once. Management keeps the inbox clean on a schedule: archiving noise, flagging urgents, drafting replies, and catching stale follow-ups.

Runs as a script-mode schedule. Each fire polls Gmail deterministically. An empty poll (no new inbox mail and no due follow-up) exits without waking the assistant, so leftover Stage 0 mail is not re-judged every few hours. The assistant runs only when the poll attaches a digest.

Default posture: high recall on noise archiving, high precision on user interruption. Archive aggressively on known-safe patterns. Ping sparingly. Never auto-send a reply. When unsure, flag instead of archiving.

Trust Ladder

A single wrong archive of an important email kills trust. Earn autonomy in stages:

Graduation requires the user to explicitly say "graduate me" or equivalent. Do not infer from silence.

Never auto-send a draft. No toggle for this rule.

Setup (one-time, before enabling schedule)

0. Informed consent

Before anything else, explain what the user is opting into. Be direct:

"Here's what inbox management does: on a schedule you choose (e.g. every few hours on weekdays), I'll scan new mail and take action based on a trust level you control. Quiet polls (no new mail) do not use the model.

Stage 0 (the default starting point): I watch but don't touch. I'll tell you what I would archive among new mail, show you draft replies I wrote, and flag urgent items, but I won't move or delete anything. This lasts until you explicitly tell me to graduate.

Stage 1 (you opt in): I silently archive obvious noise (calendar responses, no-reply senders, newsletters). Everything else is still flagged for your review.

Stage 2 (you opt in): I also archive cold outreach using my judgment. Higher autonomy, slightly higher risk of a wrong call.

At every stage: I will never send an email on your behalf. I create drafts for you to review. You can pause or stop this at any time."

Wait for explicit confirmation before proceeding. If the user hesitates or asks clarifying questions, answer them. Don't rush past this step.

1. Stage

Default to Stage 0 (flag-only). When the user (directly or via a caller like admin-copilot setup) has made an explicit, informed choice to start higher, honor it: Stage 1 (silent archive of known-safe categories only) or Stage 2 (also cold outreach by judgment). Do not infer a higher stage from enthusiasm; require an explicit choice made after the §0 consent framing for that stage. Store the chosen stage via gmail-prefs.ts --action set-management-config --stage <0|1|2>.

2. Safe-list

Ask for senders/domains that may look like outreach but matter. Seed categories:

• Financial advisors, lawyers, accountants
• Active investors and VCs
• Customer domains
• Family/personal contacts
• Paid subscriptions (billing addresses)

Store via gmail-prefs.ts --action add-safelist --emails "...". The safe-list is shared with inbox-cleanup.

3. Interrupt threshold

Default urgency bar for alerts:

• Customer at risk (churn, renewal, escalation)
• Investor/board with time-sensitive ask
• Legal/compliance deadline
• Team member flagging urgency
• Explicit markers ("EOD today", "ASAP", "urgent") from real humans

Store threshold level via gmail-prefs.ts --action set-management-config --interrupt-threshold "default".

4. Schedule

Do not create an execute-mode job. Empty inbox fires must not start an agent turn. This skill only sets up new script-mode schedules. Do not convert or rewrite leftover execute-mode jobs.

1. Create a recurring script-mode schedule:

• Name: Inbox Management
• Default cadence: 0 */3 * * 1-5 (every 3 hours on weekdays)
• Mode: script
• Script: bun "$VELLUM_WORKSPACE_DIR/schedules/$__SCHEDULE_ID/poll.ts"
• timeout_ms: 900000 (the poll's runtime includes the woken assistant turn)
• inference_profile: "cost-optimized" (applies to wake handoff turns)
• quiet: true
• reuse_conversation: false (each wake is a fresh conversation)

If assistant oauth status google shows more than one active connection, ask which inbox to watch and append one --account user@example.com flag per chosen mailbox.

By default the first poll baselines at now and does not escalate pre-existing mail (that is what stops the leftover Stage 0 pile from being re-billed). If the user wants the first sync to include recent mail, append --lookback <duration> (90m/4h/2d/1w).

2. Copy the shipped poll script into the schedule's directory. Read the id from the create result:

mkdir -p "$VELLUM_WORKSPACE_DIR/schedules/<id>"
cp "$VELLUM_WORKSPACE_DIR/skills/inbox-management/scripts/poll.ts" \
   "$VELLUM_WORKSPACE_DIR/skills/inbox-management/scripts/poll-lib.ts" \
   "$VELLUM_WORKSPACE_DIR/schedules/<id>/"

The schedule owns this copy. poll.ts self-provisions JSON state on first run (schedules/<id>/state/state.json).

3. Verify with assistant schedules execute <id>. The first run records {"ok":true,"new":0,...,"baselined":true}. Later empty polls record "new":0 without waking the assistant.

Confirm cadence with the user. Overnight wakes (when the digest is non-empty): urgent-scan only.

5. Voice profile

Run messaging_analyze_style on the user's recent sent mail. Store the style profile in the Personal Knowledge Base for draft generation.

6. Draft preference

Confirm the user wants drafts generated. Some prefer flag-only forever.

Pipeline (only when the poll wakes you)

The poll attached a digest as untrusted external content. Run these steps only against message ids in that digest. Do not search in:inbox or in:sent for the whole mailbox. Do not re-judge mail that is not in the digest.

Each step is silent unless something qualifies for interrupt.

Step 0: Missed-run check & resume

Resume interrupted runs first. Before starting a new pipeline pass, check bun run scripts/gmail-runs.ts list. If the most recent run has status: "interrupted", resume it via bun run scripts/gmail-archive.ts archive --resume "<run-id>" before proceeding. Also run bun run scripts/gmail-runs.ts prune to clean up logs older than 30 days.

Read the last-run timestamp via gmail-prefs.ts --action get-management-config. If last-run is more than 2x the scheduled interval ago (e.g. >6 hours for a 3-hour schedule), notify the user:

• Slack: "📬 Inbox management hasn't run since [time]. I'm catching up now."
• No Slack: In-app notification.

Then update last-run to now via gmail-prefs.ts --action set-management-config --last-run "..." before continuing.

Step 1: Archive known noise (Stage 1+ only)

Restrict the usual archive queries to digest inbox ids (or --dry-run the matching ids). Queries for context:

subject:(Accepted: OR Declined: OR Tentative: OR "has accepted" OR "has declined") in:inbox
from:(noreply OR no-reply OR donotreply) in:inbox
subject:("newsletter" OR "weekly digest" OR "monthly digest") in:inbox

Cross-check the safe-list before each batch. Use gmail-prefs.ts --action list to load the safe-list. Remove any safe-listed sender from the batch before archiving.

Stage 0: Collect digest matches but do not archive. Include in summary with "would archive" label.

Step 2: Cold outreach judgment (Stage 2: archive / Stage 0-1: flag)

Scope the scan to the poll window, then intersect it with the digest:

bun run scripts/gmail-scan.ts outreach-scan --time-range 1d

--time-range feeds Gmail's newer_than:, whose granularity is days, so 1d is the smallest window that covers the default 0 */3 * * 1-5 cadence. On a first sync, use the schedule's --lookback value rounded up to whole days. Append one --account user@example.com flag per mailbox when the schedule watches specific inboxes.

Then drop every result that is not in the digest: keep only senders that appear among the digest's inbox messages, and ignore the rest. The scan has no digest filter and its cache spans the whole window, so its results reach back past the mail this run is allowed to judge.

For each surviving sender, judge: is this person/offer potentially relevant to the user?

• Relevant → leave in inbox, include in summary
• Not relevant → archive (Stage 2) / flag as "would archive" (Stage 0-1)

Archive only the digest ids for that sender, as one comma-separated list:

bun run scripts/gmail-archive.ts --message-ids <id1>,<id2>,<id3>

Never archive through the --cache-key + --sender-emails path here. That path replays the scan's cache and pulls the sender's older messages, which are outside the digest.

Step 3: Urgent scan (all stages)

Scan digest inbox messages (unread or not) for urgency signals:

If any qualify, send one alert:

• Slack connected: Slack DM with 🚨 urgent email: count + per-item bullets (sender · subject · why)
• Slack not connected: In-app notification via notification pipeline
• If nothing qualifies: skip silently. Never ping just to ping.

Overnight wakes: stop after this step.