mpm/gmail-inbox-architect

Fork 0

Files

T

mpmedia ff7be709fb feat(handoff): full production SKILL.md — self-contained task order generator

2026-06-07 11:42:20 -05:00

18 KiB

Raw Blame History

handoff — Gmail Inbox Architect

What This Skill Does

Produces a complete task order package for a subcontractor AI tool to walk Gmail labels, identify sender patterns, and propose classification rules. One task order per major label tree (or sub-tree if the tree is large). The user is the delivery person — they paste the prompt, attach the files, and bring back the results.

This skill is invoked either:

Automatically by the survey skill when inbox volume exceeds the inline sampling threshold
Directly by the user ("create the task orders", "set up the handoff")

This skill is entirely self-contained. All templates are embedded below.

When This Skill Is Triggered

Survey invokes it directly (most common)
User says: "create the task orders", "set up the handoff", "build the task orders", "I want to hand this off to ChatGPT", "prepare the handoff package"

Prerequisites — Survey Must Be Complete

Before doing any other work, run Phase 1 (sanity check). This skill requires:

_status.md exists in the project folder with Phase = "Survey complete" or later
Bible.md exists with at least taxonomy v1
Tracker exists (Google Sheet or XLSX)

If any artifact is missing or phase is wrong, do NOT proceed. Say:

"It looks like the survey hasn't finished yet. Before I can build the task orders, I need the project setup to be complete. Let's run the survey first — just say 'start the survey' and I'll walk you through it."

Dependencies

Google Workspace MCP — to read Bible.md, _status.md from project Drive folder, and to create task order folders and files in Drive
handoff skill has no other external dependencies

Execution Flow

Phase 1 → Sanity check (verify survey artifacts exist and are complete)
Phase 2 → Confirm subcontractor tool (and verify it has Gmail access)
Phase 3 → Read project context from Bible.md
Phase 4 → Build batch plan (divide label trees into task order batches)
Phase 5 → Generate task order packages in Drive (one folder per batch)
Phase 6 → Brief the user (exactly how to deliver each task order)
Phase 7 → Update _status.md

Phase 1 — Sanity Check

Read _status.md from the project Drive folder.

Check:

Phase field contains "Survey complete" or any later phase
Bible Location field has a valid Drive URL
Tracker Location field has a valid Drive URL or file path

If any check fails → redirect to survey (see Prerequisites above).

If Phase is already "Handoff in progress" or later, ask:

"It looks like we've already started task orders for this project. Do you want to add more batches, or are you bringing back results from a batch that's already been sent?"

Wait for answer. If adding batches → continue. If returning results → invoke import skill.

Phase 2 — Confirm Subcontractor Tool

If the subcontractor tool is NOT already known from survey Q4, ask:

"Which AI tool are you planning to use for the analysis — ChatGPT, Gemini, or something else?"

Wait for answer. Then confirm Gmail access:

"Does [tool] have a direct connection to your Gmail account? For example, in ChatGPT, this would be the Gmail skill or a Google Workspace connection."

If yes: Continue.

If no or unsure:

"This process requires the tool to be able to read your Gmail directly. Without that connection, it won't be able to walk your labels and propose rules. You'll need someone technical on your team to help get that set up before we can proceed. Once it's connected, come back and I'll build the task orders."

Do NOT attempt to guide the Gmail connection setup. Stop here and wait.

Record the tool name. This goes into every task order prompt.

Supported tool names for prompt optimization:

ChatGPT (any variant with Gmail/Workspace skill)
Gemini (Google account connected)
Other / Unknown → use generic prompt template

Phase 3 — Read Project Context

Read Bible.md from the project Drive folder. Extract:

Label taxonomy v1 (the full indented list)
All bylaws
Environment decision (Google Sheet vs. XLSX)
Any policy notes from the Decisions Log

Also read the label inventory from _status.md (Labels Cataloged count) or from the Tracker if it has been populated.

If the Tracker is still blank (survey just completed), the label inventory is what you held in context from the survey. Use it now.

Build an internal working list of all user labels with:

label_name — full path
parent — top-level category
messages_total — count from survey

Phase 4 — Build Batch Plan

Divide the label inventory into batches. Each batch becomes one task order.

Primary split: by top-level label category

Each top-level category (Finance, Vendors, Clients, etc.) is one batch.

Sub-batch trigger: split a top-level category if EITHER is true

The category has more than 5 sublabels
The category has more than 500 total messages across all its sublabels

When sub-batching, split by:

Natural sublabel groupings (e.g., Clients/Resellers as one batch, Clients/Corporate as another)
Or alphabetically for very large flat lists

Batching rules

Never put more than 8 labels in a single task order
Never put more than 1,000 messages in a single task order (estimate from counts)
Always keep a top-level category whole if it fits within the limits
Notifications, Personal, and system-like labels (low volume, clear rules) can be grouped together into a single "Miscellaneous" batch

Present the batch plan to the user

Before generating any files, show the user the plan:

"Here's how I'm going to split the work into task orders:

Batch 1 — Finance (3 labels, ~800 messages) Batch 2 — Vendors (4 labels, ~400 messages) Batch 3 — Clients/Resellers (5 labels, ~2,100 messages) Batch 4 — Clients/Corporate (2 labels, ~300 messages) Batch 5 — Development + Notifications + Personal (6 labels, ~600 messages)

That's 5 task orders total. Does this look right, or do you want to adjust anything?"

Wait for approval. Adjust if needed. Then proceed.

Phase 5 — Generate Task Order Packages

Create a folder called Task Orders in the project Drive folder. Inside it, create one subfolder per batch named: Batch [N] - [Category Name]

Inside each batch subfolder, create 4 files using create_drive_file:

File 1: `00_PROMPT.md`

This is the text the user pastes into the subcontractor tool. It must be entirely self-contained — the user pastes it without modification.

PROMPT.md template (ChatGPT with Gmail skill):

You are a Gmail classification analyst working on an inbox organization project.

PROJECT CONTEXT: Before doing anything else, read the file CONTEXT.md that has been
attached to this message. It contains the taxonomy, bylaws, and project rules that
govern all rules you propose. Do not proceed without reading it.

YOUR TASK — [BATCH NAME, e.g., "Finance label tree"]:
Walk the Gmail labels listed in LABEL_LIST.csv. For each label:

STEP 1 — Review messages
  - Open the label in Gmail
  - Review the 20-30 most recent messages (not just subject lines — look at sender domains)
  - Note: who is sending mail to this label, what subject patterns appear, any attachment types

STEP 2 — Identify patterns  
  For each distinct sender domain you find:
  - Does it clearly belong in this label? Or in a different one?
  - Is a subject qualifier needed to avoid labeling too broadly?
  - Does it send emails that clearly require separate work-type labels
    (e.g., invoices vs. general updates from the same domain)?
  - Are there attachment patterns (file types, naming conventions)?

STEP 3 — Propose rules
  Return exactly three CSV files using the schemas in OUTPUT_FORMAT.md:
  
  filter_rules.csv    — rules Gmail can apply natively (domain, subject, participant pattern)
  apps_script_rules.csv — rules that require attachment filename inspection
  taxonomy_notes.csv  — taxonomy gaps, policy observations, things that need Claude's review

IMPORTANT RULES:
  - Include your basis for EVERY rule in the notes column
  - Use participant-domain logic (from OR to OR cc) for client/reseller domains
  - Use from-only logic for vendors, notification services, and financial senders
  - Do NOT propose rules that depend on reading email body text — filters and Apps Script
    work from headers, subject lines, and attachment filenames only
  - Confidence and risk ratings must reflect your actual certainty
  - Flag ambiguous cases in taxonomy_notes.csv with status "do_not_automate_yet"

Return all three CSV files as attachments. Do not summarize them — just return the files.

PROMPT.md template (Gemini): Use the same content as ChatGPT above. Gemini's Gmail integration works identically for this task.

PROMPT.md template (Generic / Unknown tool):

You are a Gmail classification analyst working on an inbox organization project.

You need Gmail access for this task. Before proceeding, confirm that you can read
Gmail labels and message sender information (not message bodies) for this account.
If you cannot, say so immediately.

[Then continue with the same STEP 1-3 content as ChatGPT template above]

Substitute [BATCH NAME] with the actual batch name (e.g., "Finance label tree").

File 2: `01_CONTEXT.md`

This is the project context the subcontractor reads first. Extract from Bible.md.

CONTEXT.md template:

# Gmail Inbox Architect — Project Context for Analysis

**Project account:** [email address from Bible.md]
**Date generated:** [today]
**Batch:** [batch name]

---

## Label Taxonomy

This is the confirmed taxonomy for this project. All rules you propose must fit within
this structure. Do not propose labels outside this taxonomy without flagging it in
taxonomy_notes.csv.

[Paste the full taxonomy from Bible.md here — the indented label list]

---

## Bylaws

These are the rules for what belongs in each label. They are binding — follow them
when deciding which label a rule should target.

[Paste all bylaws from Bible.md here]

---

## Key Rules for This Analysis

1. Participant-domain logic applies to client and reseller labels:
   Use (from:domain.com OR to:domain.com OR cc:domain.com) — not just from:.
   
2. From-only logic applies to vendors and services:
   Use from:domain.com only — not participant pattern.
   
3. Secondary labels are additive:
   A thread can have both a client label AND a work-type label (Finance/Invoices,
   Sales/Quotes, etc.). Propose secondary rules where patterns are clear.

4. Apps Script is for attachment inspection only:
   Propose apps_script_needed rules ONLY for rules where the trigger is an attachment
   filename or extension pattern. Not for body text.

5. Flag ambiguous cases:
   If you are unsure whether a domain belongs in this taxonomy, flag it in
   taxonomy_notes.csv with status "do_not_automate_yet" and explain why.

---

## Decisions Log (Key Policy Notes)

[Paste relevant entries from Bible.md Decisions Log — especially any policy notes
about specific senders, domains, or label structures]

Fill in actual content from Bible.md at runtime.

File 3: `02_LABEL_LIST.csv`

The specific labels in this batch, with message counts. The subcontractor uses this to know exactly what to walk.

Schema:

label_name,parent,messages_total,messages_unread,bylaw,scan_priority,notes

Populate from the label inventory built in Phase 3. Assign scan_priority:

1 = highest message volume or most business-critical
2 = medium
3 = low volume or low urgency

Add the bylaw text for the parent label so the subcontractor has it inline.

Example:

Finance/AMEX,Finance,412,0,"Any email involving money moving in or out — invoices statements receipts payments",1,Check for statement keyword; from-only pattern
Finance/Invoices,Finance,238,12,"Any email involving money moving in or out",1,May overlap with vendor domains; check for secondary rules
Finance/Receipts,Finance,856,0,"Any email involving money moving in or out",2,High volume; likely archive+mark-read candidates

File 4: `03_OUTPUT_FORMAT.md`

The exact schemas the subcontractor must use for its return files.

OUTPUT_FORMAT.md template:

# Required Output Format

Return exactly three CSV files. Use these exact column names. Do not add or remove columns.

---

## File 1: filter_rules.csv

Rules that Gmail can execute natively. Use this for domain, subject keyword,
and participant-pattern rules.

Columns (in this order):
rule_id,enabled,priority,rule_name,from_domain,to_or_cc_domain,subject_contains,has_attachment,base_label,archive,mark_read,queue_for_ai_process,deployability,confidence,risk,notes

Field definitions:
rule_id         — Your proposed ID. Format: GF-[CATEGORY]-[DESCRIPTION] e.g. GF-FINANCE-AMEX-STMT
enabled         — FALSE (Claude will review and enable approved rules)
priority        — Integer 1-99 (lower = higher priority). Base labels: 50. Secondary: 80-90.
rule_name       — Plain English description (max 60 chars)
from_domain     — Sender domain(s). Multiple: use semicolons. e.g. domain1.com; domain2.com
to_or_cc_domain — For participant rules: same domain as from_domain. Leave blank for from-only rules.
subject_contains — Subject keyword(s). Multiple: use semicolons. Leave blank if not needed.
has_attachment  — TRUE or FALSE
base_label      — Full Gmail label path. e.g. Finance/AMEX
archive         — TRUE or FALSE (TRUE = skip inbox)
mark_read       — TRUE or FALSE (use sparingly — only for pure notifications)
queue_for_ai_process — TRUE or FALSE (TRUE = flag for Claude's downstream review)
deployability   — Always: gmail_filter_safe
confidence      — high / medium / low (your certainty this rule is correct)
risk            — low / medium / high (false-positive risk if this fires on wrong emails)
notes           — REQUIRED. Your basis: what emails triggered this proposal and why.

---

## File 2: apps_script_rules.csv

Rules that require attachment filename/extension inspection. Use ONLY for rules where
the trigger is an attachment file type or naming pattern.

Same columns as filter_rules.csv, with these differences:
rule_id         — Format: AS-[CATEGORY]-[DESCRIPTION] e.g. AS-DOC-STEP-FILE
deployability   — Always: apps_script_needed
notes           — Must include: exact filename pattern (e.g. *.stp, *.step, inv-*.pdf)

---

## File 3: taxonomy_notes.csv

Observations about the taxonomy — gaps, policy notes, things that need Claude's review.
This is where you flag anything that doesn't fit neatly into a rule.

Columns (in this order):
proposal_id,status,proposed_label,parent,reason,candidate_sources,notes

Field definitions:
proposal_id     — TAX-NNN sequential number
status          — One of: confirmed_existing / proposed_new / policy_note / do_not_automate_yet
proposed_label  — The label path being referenced or proposed (or blank for policy notes)
parent          — Parent label (or blank)
reason          — Why you're flagging this
candidate_sources — Domain(s) or sender(s) that prompted this observation
notes           — Additional context. For do_not_automate_yet: explain what would need to
                  be true before this could be automated.

---

## Important Notes

- Return ALL THREE files even if one has zero rows (include header row only)
- Do not return the files as code blocks — attach them as actual CSV files
- Do not summarize or explain in chat — just return the files
- If you are unsure about something, put it in taxonomy_notes.csv with status do_not_automate_yet

Phase 6 — Brief the User

After all task order folders are created in Drive, give the user clear delivery instructions.

"Your task orders are ready in your project Drive folder — I've created [N] batches. Here's how to use them:

For each batch (start with Batch 1):

Open the batch folder in Drive

Open 00_PROMPT.md — copy the entire text

Paste it into [tool name] and attach the other three files from the folder

Submit it and let the tool work

When it returns three CSV files, bring them back here and say 'import the Finance results' (or whatever batch you just ran)

You don't need to run all the batches before bringing results back. You can run Batch 1, bring the results to me, then run Batch 2. I'll review and refine the rules as each batch comes back.

Which batch do you want to start with?"

Phase 7 — Update _status.md

After all task orders are generated, update _status.md:

Last Updated: [timestamp]
Last Agent: Claude (CoWork) — handoff skill
Phase: Handoff in progress
Last Completed Step: [N] task order batches created in Drive Task Orders folder.
Pending Work: User delivering batches to [tool name]. Return results via import skill.
Handoff Target: [tool name]
Notes: Batches created: [list batch names]. Each returns 3 CSV files to import.

Batch Size Reference

Condition	Action
Top-level category ≤ 8 labels AND ≤ 500 messages	One batch
Top-level category > 5 sublabels OR > 500 messages	Split into sub-batches
Never more than 8 labels per batch	Split further
Never more than ~1,000 messages per batch	Split further
Notifications + Personal + low-volume misc	Group together

Embedded Template: Rule ID Format

Gmail filter rules:   GF-[CATEGORY]-[SUBCATEGORY]-[DESCRIPTOR]
                      GF-FINANCE-AMEX-STMT
                      GF-CLIENT-RESELLER-ACME-PARTICIPANT
                      GF-VENDOR-SHIPPING-FEDEX

Apps Script rules:    AS-[CATEGORY]-[DESCRIPTOR]
                      AS-DOC-STEP-FILE
                      AS-FINANCE-VENDOR-INVOICE-PDF

Category abbreviations to use in rule IDs:

FINANCE / VENDOR / CLIENT / OPS / DEV / SALES / TRAVEL / NOTIF / SUPPORT / DOC / PERSONAL

Safety Rules (Cannot Be Overridden)

No Gmail mutations. This skill creates Drive files only. It does not touch Gmail.
Always confirm the tool has Gmail access before generating task orders. If access is uncertain, stop and redirect to an AI expert in the org.
Never skip the sanity check. If survey artifacts are missing, redirect to survey.
Task orders are reviewed by Claude before anything goes to Gmail. Import skill brings results back to Claude. Deploy skill executes. Nothing is automatic.
The subcontractor proposes. Claude decides. Always.

18 KiB Raw Blame History