479 lines
17 KiB
Markdown
479 lines
17 KiB
Markdown
# 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:
|
|
1. `Phase` field contains "Survey complete" or any later phase
|
|
2. `Bible Location` field has a valid Drive URL
|
|
3. `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 — Prepare the Task Order
|
|
|
|
Claude's job here is to prepare the context — not to plan the subcontractor's methodology.
|
|
A capable peer model will determine its own optimal approach once it has the project context
|
|
and the output requirements. Do not prescribe how many messages to review, how to split the
|
|
work, or in what order to process labels.
|
|
|
|
### Step 4.1 — Compile the full label inventory
|
|
|
|
From the label list built in Phase 3, prepare a complete LABEL_LIST.csv containing ALL user
|
|
labels with message counts, scan priority guidance, and bylaw references. This is the
|
|
subcontractor's working inventory — give it everything.
|
|
|
|
### Step 4.2 — Create the initial task order
|
|
|
|
Generate one task order covering the full label inventory. The subcontractor decides
|
|
whether to process everything in one pass or propose its own batching plan. Both are fine.
|
|
|
|
If the subcontractor returns a batching proposal rather than results:
|
|
- Review the proposal with the user in plain English
|
|
- Ask for approval
|
|
- Create additional task order folders for subsequent batches as requested
|
|
|
|
### Step 4.3 — Confirm with the user before creating Drive files
|
|
|
|
> "I'm going to prepare a task order with your full label inventory and let [tool] determine
|
|
> the most efficient way to work through it — it may do everything in one pass or propose
|
|
> splitting into batches. Either way works. Ready to go?"
|
|
|
|
Wait for confirmation, then proceed to Phase 5.
|
|
|
|
---
|
|
|
|
## 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 / Gemini):**
|
|
|
|
```
|
|
You are a Gmail classification analyst. You have been given a Gmail inbox organization project.
|
|
|
|
Read CONTEXT.md before doing anything else. It contains the taxonomy, bylaws, and project
|
|
decisions that govern all rules you propose.
|
|
|
|
Your goal: analyze the Gmail labels in LABEL_LIST.csv and propose classification rules that
|
|
will automatically sort incoming email according to the taxonomy in CONTEXT.md.
|
|
|
|
You have direct access to the Gmail account. Use that access as you see fit to identify
|
|
sender patterns, domain signals, subject patterns, and attachment types — whatever gives
|
|
you confident rule proposals.
|
|
|
|
Return your findings using the exact schemas in OUTPUT_FORMAT.md:
|
|
|
|
filter_rules.csv — rules Gmail can execute natively (domain, subject, participant)
|
|
apps_script_rules.csv — rules requiring attachment filename/extension inspection
|
|
taxonomy_notes.csv — taxonomy gaps, policy observations, and anything needing review
|
|
|
|
If the label inventory is large and you prefer to work in batches, propose a batching
|
|
plan and execute the first batch. Subsequent task orders will be prepared for remaining work.
|
|
|
|
Hard constraints that must be respected:
|
|
- Participant-domain logic (from OR to OR cc) for client and reseller labels
|
|
- From-only logic for vendors, services, and financial senders
|
|
- No rules dependent on message body text — filters and Apps Script work from headers,
|
|
subjects, and attachment filenames only
|
|
- Document your basis for every proposed rule in the notes column
|
|
- Use taxonomy_notes.csv status "do_not_automate_yet" for anything you are not confident about
|
|
|
|
Return all three CSV files. Do not summarize — just return the files.
|
|
```
|
|
|
|
**PROMPT.md template (Generic / Unknown tool):**
|
|
|
|
```
|
|
[Add this preamble before the main prompt above:]
|
|
You need direct Gmail access for this task. Before proceeding, confirm that you can
|
|
read Gmail labels and message sender information for this account. If you cannot, say
|
|
so immediately — do not attempt to work around it.
|
|
|
|
[Then continue with the ChatGPT template above]
|
|
```
|
|
|
|
---
|
|
|
|
### File 2: `01_CONTEXT.md`
|
|
|
|
This is the project context the subcontractor reads first. Extract from Bible.md.
|
|
|
|
**CONTEXT.md template:**
|
|
|
|
```markdown
|
|
# 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:**
|
|
|
|
```markdown
|
|
# 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):**
|
|
> 1. Open the batch folder in Drive
|
|
> 2. Open `00_PROMPT.md` — copy the entire text
|
|
> 3. Paste it into [tool name] and attach the other three files from the folder
|
|
> 4. Submit it and let the tool work
|
|
> 5. 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.
|
|
```
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
1. No Gmail mutations. This skill creates Drive files only. It does not touch Gmail.
|
|
|
|
2. 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.
|
|
|
|
3. Never skip the sanity check. If survey artifacts are missing, redirect to survey.
|
|
|
|
4. Task orders are reviewed by Claude before anything goes to Gmail. Import skill
|
|
brings results back to Claude. Deploy skill executes. Nothing is automatic.
|
|
|
|
5. The subcontractor proposes. Claude decides. Always.
|
|
|
|
|