gmail-inbox-architect/skills/survey/SKILL.md

name, description

name

description

survey

Guides a non-technical user through the opening session of building a Gmail classification pipeline. Use when the user says "set up my Gmail", "organize my inbox", "start the survey", "build a Gmail system", "classify my email", "create email rules", "set up email sorting", "build an inbox system", or begins a new Gmail Inbox Architect project. Runs an interview, catalogs labels, builds a taxonomy draft, and creates project artifacts (Bible.md, Tracker, _status.md) in Google Drive. First skill to run — precedes handoff, import, deploy, and rule-review. Part of the Gmail Inbox Architect plugin.

survey — Gmail Inbox Architect

What This Skill Does

Guides a user through the opening session of building a Gmail classification pipeline. Catalogs their existing label structure, runs a short interview, builds a first-pass taxonomy draft, and creates three project artifacts in Google Drive: Bible.md (the project constitution), Tracker.xlsx or a Google Sheet (the rule registry), and _status.md (the inter-agent checkpoint file).

If the user has fewer than 15 user-created labels, this skill forks into Bootstrap Mode rather than the main survey flow. Bootstrap Mode samples inbox and sent email to infer a draft taxonomy, creates the "! Rule Needed" label, and sets them up to return in 2–3 weeks via rule-review. See Bootstrap Mode section below.

This skill may invoke the handoff skill mid-run if inbox volume exceeds the sampling threshold. That is expected behavior — not an error.

This skill is entirely self-contained. All schemas, templates, and examples are embedded below. Do not reference any external URLs or repositories at runtime.

---

When This Skill Is Triggered

Fire this skill when the user says any of the following (or close variants):

• "set up my inbox", "help me organize my email", "start the Gmail project"
• "build me a filter system", "let's tackle my inbox", "Gmail inbox architect"
• "start fresh with email classification", "I want to tame my inbox"
• "let's do the survey", "run the survey", "start the survey"

---

⚠️ North Star Constraint — Read This First, Every Time

Never walk the full inbox. Never scan all messages. Never read every email.

The survey builds a draft-one blueprint. It does not need to touch every email to do that. If the user asks you to scan their entire inbox, read all their messages, or process thousands of emails as part of this survey, respond with this exact redirect:

"Right now my job is to build your draft-one blueprint — I just need to see the shape of your inbox, not read every message in it. The task orders I send to other tools will dig into the details; that's their job, not mine at this stage. Let's keep moving — I'll have something real for you to look at in just a few minutes."

Then continue with the current phase. Do not comply with the full-scan request.

---

Dependencies

• Google Workspace MCP — for Gmail label catalog, bounded inbox/sent sampling, and Drive file/folder creation
• xlsx skill — required if user chooses the XLSX Tracker path; invoke it for Tracker creation in Phase 5
• handoff skill — invoked automatically if sampling threshold is exceeded in Phase 4

This skill has NO other external dependencies. All schemas and templates are embedded below.

---

Execution Flow

Phase 1 → Q1 + Label Catalog (immediate — show results, then run bootstrap check)

  IF user-created labels < 15:
    → Bootstrap Mode (see below — replaces Phases 2–6)

  IF user-created labels ≥ 15:
    → Phase 2 → Four More Questions
    → Phase 3 → Taxonomy Draft (written live, section by section)
    → Phase 4 → Inbox Sample OR Handoff Decision
    → Phase 5 → Create Three Artifacts (Bible.md + Tracker + _status.md)
    → Phase 6 → Close Out

Do not skip any phase. Phase 1 and 2 interleave — ask Q1 first, run the label catalog while you have the account, then ask Q2–Q5 conversationally while processing finishes.

---

Phase 1 — Instant Win: What You Already Have

Goal: Show the user their existing label structure within the first few minutes. This is the hook. They see something real and realize this process is already further along than they thought.

Step 1.1 — Ask Q1 only

Before doing anything else, ask one question:

"What Gmail address are we setting this up for? Just confirm the account and we'll get started — I can usually pull up your existing label structure in about 30 seconds."

Wait for the answer.

Step 1.2 — Pull the label catalog

Call list_gmail_labels. For each label returned, capture:

• label_name — full path including parent (e.g., Finance/AMEX)
• parent — the part before the first /, or blank if top-level
• type — user (manually created) or system (Gmail built-in)
• messages_total — total message count (if available)
• messages_unread — unread count (if available)

Filter OUT all system labels (Inbox, Sent, Drafts, Spam, Trash, All Mail, Important, Starred, Scheduled, and any label with type: system).

Keep only type: user labels. These represent the user's real organizational decisions.

Step 1.3 — Present the results

Show a clean summary grouped by top-level category. Use plain English — not raw data.

If they have 15 or more user labels:

"Great news — you've already done more work than you might realize. Here's what you already have:

Finance (3 labels) — AMEX, Invoices, Receipts Vendors (2 labels) — Shipping, Software ...and X more categories.

That's [total] labels total. Every one represents an organizational decision you've already made. We're going to build on this, not start over."

If they have fewer than 15 user labels:

"You've got [N] labels set up — that's a starting point, but not quite enough to build a full sorting system from yet. The good news: I can look at your actual email patterns right now and sketch out what your system should look like based on who you're actually talking to. Give me about a minute."

Then immediately proceed to Bootstrap Mode. Do NOT continue to Phase 2.

If they have zero user labels:

"You're starting from scratch — no custom labels yet. No problem. Let me take a quick look at who you've been emailing and I'll draft a system based on your real patterns."

Then immediately proceed to Bootstrap Mode.

Step 1.4 — Bootstrap Check

Count only type: user labels from the catalog.

• If count < 15 → proceed to Bootstrap Mode (below). Do not run Phases 2–6.
• If count ≥ 15 → proceed to Phase 2 (normal survey flow).

---

---

BOOTSTRAP MODE

For users with fewer than 15 user-created labels

Bootstrap Mode replaces Phases 2–6 for users who don't yet have an established label system. Instead of analyzing existing labels, we sample their actual email traffic to infer a draft taxonomy, set them up with the "! Rule Needed" label, and send them off for 2–3 weeks of tagging before returning via rule-review.

---

Bootstrap Phase B1 — Sample Inbox and Sent Email

Internal Domain Exclusion List (Hardcoded — MPM-Specific)

Always exclude these domains from ALL domain frequency analysis — inbox and sent. These are MPM internal domains. Email to/from these addresses tells us nothing about external relationships worth labeling.

mpmedia.tv
messagepoint.tv
messagepointmedia.com
messagepoint.media
mpm.to

Additionally, exclude any email address whose local part (before the @) matches any of these patterns — these are automated/system senders regardless of domain:

noreply
no-reply
donotreply
do-not-reply
mailer-daemon
postmaster
bounce
bounces
notifications
notification
automated

Apply these exclusions before counting. They should never appear in the domain frequency tables or the draft taxonomy.

Step B1.1 — Inbox Sample (100 emails)

Call search_gmail_messages with query in:inbox and max_results: 100.

For each result, capture:

• from — sender email address
• subject — subject line
• snippet — email preview/snippet (do NOT read full body)

Extract the sender domain from the from field (the part after @). Apply the exclusion list. Discard excluded domains before counting.

Build an inbox domain frequency table: domain → count of messages in sample.

Step B1.2 — Sent Sample (up to 250 emails)

Call search_gmail_messages with query in:sent and max_results: 250.

For each result, capture:

• to — recipient email address(es)
• date — send date (for recency weighting)

Extract the recipient domain(s) from the to field. Apply the exclusion list. Discard excluded domains before counting.

Recency weighting: Double-count any domain that appears in sends within the last 90 days. Recent sending patterns are stronger signal than historical ones.

Build a sent domain frequency table: domain → weighted count of sends.

Step B1.3 — Domain Analysis

Classify each domain that survived the exclusion filter:

Tier	Criteria	Signal	Rule Type Likely
Bidirectional	inbox_count ≥ 2 AND sent_count ≥ 2	Strongest — real two-way relationship	participant-pattern (from OR to OR cc)
Sent-heavy	sent_count ≥ 3, inbox_count < 2	Likely client/partner you email proactively	participant-pattern; confirm with user
Inbox-heavy	inbox_count ≥ 5, sent_count < 2	Likely vendor, service, or notification sender	from-only filter
Low signal	inbox_count < 5 AND sent_count < 3	Not enough data; skip	n/a

Drop all Low Signal domains. They don't have enough data to justify a rule.

Also scan the inbox snippets for these common patterns to surface additional early wins:

• Subject contains "invoice", "statement", "receipt", "payment" → Finance signal
• Subject contains "shipping", "tracking", "order" → Vendor/Notifications signal
• Subject contains "alert", "notification", "reminder" → Notifications signal

---

Bootstrap Phase B2 — Draft Taxonomy

Build a draft taxonomy from the domain analysis. Use the reference taxonomy from Phase 3 in the main flow (Finance, Vendors, Clients, Notifications, etc.) as a scaffold, and populate it with the actual domains you found.

Step B2.1 — Map domains to categories

For each domain that survived analysis:

• Bidirectional domains → place in Clients/ or Operations/ (prompt user to confirm)
• Sent-heavy domains → tentatively Clients/, flag for confirmation
• Inbox-heavy, subject=invoice/statement/receipt → Finance/
• Inbox-heavy, subject=shipping/tracking/order → Vendors/Shipping or Notifications/
• Inbox-heavy, subject=alert/notification → Notifications/
• Other inbox-heavy → Vendors/ (default for unknown services)

Step B2.2 — Present findings

Show a plain-English summary of what you found. Keep it conversational — this is not a technical report.

"Okay, I took a look at your recent email traffic. Here's what I found:

Looks like regular relationships (you email these people and they email back): [List bidirectional domains — 1-2 sentences each on what they seem to be]

Looks like services or vendors you use: [List inbox-heavy domains with pattern notes — e.g., 'americanexpress.com — 18 messages, mostly statements and alerts']

Possible clients or partners you reach out to: [List sent-heavy domains]

Based on this, here's the label structure I'd suggest starting with:

[Show draft taxonomy — indented list, clearly labeled as 'suggested']

Does this look roughly right? Any relationships I'm obviously missing or anything that's in the wrong category?"

Wait for feedback. Accept corrections. This is a conversation, not a presentation. Adjust the taxonomy based on what they say. Once they confirm it's roughly right, move to B3.

---

Bootstrap Phase B3 — Ask Drive Folder Location

"Where should I set up your project folder in Google Drive? I can put it anywhere — just name a folder and a parent location, or I can create it at the top level of your Drive."

Default if they say "wherever is fine": create Gmail Inbox Architect — [first name or account prefix] at Drive root.

---

Bootstrap Phase B4 — Create "! Rule Needed" Label

This label is how the user tags emails they want sorted automatically. It's the primary input to the rule-review skill.

Ask for explicit approval before creating anything:

"The most important thing I can set up for you right now is a label called '! Rule Needed'. Whenever you get an email and think 'I wish this went somewhere automatically' — just tag it with that label. After a few weeks of doing that, I can look at what you tagged and build the sorting rules for you.

Can I create that label in your Gmail now?"

Wait for an explicit "yes" before proceeding.

If approved: call manage_gmail_label with action: create and name: ! Rule Needed.

If declined: note it, tell them they can create it manually, and proceed.

---

Bootstrap Phase B5 — Offer Starter Labels

Based on the top 2–3 highest-confidence clusters from B2, offer to create matching labels now. Present as an offer — not automatic.

"Based on what I found, the most obvious labels to start with would be:

• [Category 1] — for email from [domain(s)] (these are [plain English description])
• [Category 2] — for email from [domain(s)]
• [Category 3] — for email about [pattern description]

Want me to create any of these? You don't have to — they can wait until we build the full system later. But having even 2–3 labels gives you a head start."

Create only the ones the user explicitly approves. One approval call per label. Use the same taxonomy path structure confirmed in B2 (e.g., Finance/Receipts, Vendors/Shipping).

Do not create more than 5 labels in bootstrap mode regardless of what the domain analysis found. The goal is a quick start, not a complete system.

---

Bootstrap Phase B6 — Create Lightweight Artifacts

Create two artifacts (not three — no Tracker yet, there are no rules to track).

Artifact B-1: Project Drive Folder

Call create_drive_folder using the location from Phase B3.

Artifact B-2: Bible.md (Bootstrap Version)

Create a lightweight Bible.md that reflects bootstrap status. Key differences from the full survey Bible.md: taxonomy is marked as preliminary, no bylaws required yet, Tracker section is omitted.

Bootstrap Bible.md template:

# Gmail Inbox Architect — Project Bible
**Created:** [YYYY-MM-DD]
**Account:** [email address]
**Project Folder:** [Drive folder URL]
**Phase:** Bootstrap — email patterns surveyed; taxonomy is preliminary
**Mode:** Bootstrap (< 15 labels at setup — return via rule-review after tagging)

---

## Setup Notes

This project was started in bootstrap mode — the user did not yet have an established
label system. The taxonomy below was inferred from inbox and sent email patterns rather
than from an existing label structure. It should be considered a working draft until
confirmed through actual use.

Return path: after 2–3 weeks of using "! Rule Needed", the user should say
"review my rule needed folder" to run the rule-review skill and start building rules.

---

## Environment Decision

**Tracker format:** To be determined — no Tracker created yet (not enough rules to track)
**Rule:** Confirm Tracker format (Google Sheet vs. XLSX) when the first rule-review session runs.

---

## Label Taxonomy v1 (Preliminary)

> Bootstrap draft. Inferred from inbox/sent domain patterns — not from an existing
> label system. Expect significant revision after first rule-review session.

[Paste the taxonomy confirmed in B2 — indented list]

---

## Domain Analysis Summary

### Bidirectional Domains (highest confidence — real two-way relationships)
[List domains with counts: "acme.com — 8 inbox, 12 sent"]

### Sent-Heavy Domains (outbound relationships — likely clients/partners)
[List domains with counts]

### Inbox-Heavy Domains (services/vendors/notifications)
[List domains with counts + subject pattern notes]

### Exclusions Applied
Internal MPM domains excluded from all analysis:
mpmedia.tv, messagepoint.tv, messagepointmedia.com, messagepoint.media, mpm.to

---

## Labels Created at Bootstrap

[List any labels created in B4 and B5, with dates]

---

## Key Decisions Log

| Date | Decision | Reason |
|---|---|---|
| [today] | Bootstrap mode used | < 15 user labels at setup |
| [today] | "! Rule Needed" label [created / not created] | [user's decision] |

---

## Open Questions

- Confirm bidirectional domains: are these clients, partners, or internal contacts?
- Bylaw definitions needed for all taxonomy categories
- Tracker format (Google Sheet vs. XLSX) to be confirmed at first rule-review session

---

## Tools & Agents Involved

- **Claude (CoWork)** — Architect. All Gmail mutations go through Claude.

---

## Change Log

| Date | Agent | Change |
|---|---|---|
| [today] | Claude (survey — bootstrap) | Bootstrap Bible created. Taxonomy v1 preliminary draft from domain analysis. |

Artifact B-3: _status.md

# Gmail Inbox Architect — Project Status

**Last Updated:** [YYYY-MM-DD HH:MM UTC]
**Last Agent:** Claude (CoWork) — survey skill (bootstrap mode)
**Phase:** Bootstrap
**Last Completed Step:** Bootstrap survey complete. Domain analysis run. Taxonomy v1 preliminary.
  "! Rule Needed" label [created / pending]. [N] starter labels created.
**Pending Work:** User tagging emails with "! Rule Needed" for 2–3 weeks. Return via rule-review.
**Handoff Target:** NONE
**Tracker Format:** TBD — to be confirmed at first rule-review session
**Tracker Location:** NONE — no Tracker created yet
**Bible Location:** [Drive URL]
**Labels Cataloged:** [N] user labels at setup (bootstrap threshold: < 15)
**Taxonomy Status:** Preliminary v1 — inferred from domain analysis, not from label history
**Bootstrap Mode:** TRUE
**Notes:** Domain analysis: [N] bidirectional, [N] sent-heavy, [N] inbox-heavy domains identified.
  Return trigger: user says "review my rule needed folder" after 2–3 weeks of tagging.
  Do NOT re-run survey — go straight to rule-review.

---

## How To Use This File

This file is the handoff checkpoint for the Gmail Inbox Architect project.
Any agent starting a new session should:
1. Read this file first to understand current state
2. Read Bible.md for full project context
3. Continue from "Pending Work" above
4. NOTE: This project is in bootstrap mode. When the user returns, invoke rule-review,
   not survey.

---

Bootstrap Phase B7 — Bootstrap Close Out

Be specific and brief. The user needs to know exactly what to do next.

"Here's where we are:

✅ Draft label structure — based on your actual email patterns, here's what I recommend: [brief 3–4 line recap of top taxonomy categories]

✅ '! Rule Needed' label — [created in your Gmail / ready to create when you want] Whenever you get an email and think 'this should be sorted automatically' — tag it with this label. That's all you have to do.

✅ Project Bible — [link] I've saved your draft label structure and everything I found about your email patterns. It's ready to pick up where we left off.

What to do next: Use '! Rule Needed' for the next 2–3 weeks. Tag anything that feels like it should be automatic. Don't overthink it — if it bugs you that it's in your inbox, tag it.

When you're ready to actually build the sorting rules, come back and say: 'review my rule needed folder'

I'll look at what you tagged, group it by pattern, and we'll build rules together based on your real email — not guesses.

You do not need to re-run this survey. Start with 'review my rule needed folder' when you return."

---

---

MAIN SURVEY FLOW

For users with 15 or more user-created labels

---

Phase 2 — Four More Questions

Ask these conversationally after showing the label inventory. Never number them out loud. Never ask two questions in the same message. Adapt the order naturally to the conversation.

Q2 — Drive folder location

"Where should I set up your project folder in Google Drive? I can put it anywhere — just name a folder and a parent location, or I can create it at the top level of your Drive if you're not sure."

Default if they say "wherever is fine": create Gmail Inbox Architect — [first name or account prefix] at Drive root.

Q3 — Google environment question (the key decision)

This determines XLSX vs. Google Sheet. Ask naturally:

"Quick technical question — do all the tools you're planning to use with this project have a direct connection to Google Docs and Sheets? If you're not sure, just say so — it's easy to pick a safe default."

Interpret answers:

• "Yes" / "They all do" / "I'm only using Claude" → Google Sheet
• "No" / "Not sure" / "I use ChatGPT too" / "I have a local AI" → XLSX + Markdown
• "What does that mean?" → Explain, then ask again:

  "Some AI tools can read Google Sheets directly — others need a file like Excel. If you're only using tools connected to your Google account, we can use Google Sheets. If you're using anything else — ChatGPT, a local tool — use Excel instead so everything can read it. Which sounds like your situation?"

Record this decision. It gets written to Bible.md in Phase 5 and must not be changed without re-asking the user explicitly.

Q4 — Other agents they plan to use

"Besides me, are you planning to use any other AI tools with this project — like ChatGPT, Gemini, or something you run on your own computer?"

Accept any answer. This informs the handoff skill later. Record what they say. If "just you" — note it; handoff is still possible later if volume demands it.

Q5 — Goals or problem areas

"Last one — is there anything specific driving this? A type of email that's always a mess, or something you wish happened automatically?"

Accept any answer including "not really — just more organized." Record it for Bible.md.

---

Phase 3 — Taxonomy Draft

Goal: Build a first-pass taxonomy from the label inventory and show it to the user section by section. They should feel the system being built in front of them.

Step 3.1 — Analyze existing labels

From Phase 1, identify:

1. Existing top-level categories — what the user already organized
2. Gaps — common business email types they're probably missing
3. Consolidation candidates — labels too granular or redundant
4. Draft bylaws — one-line rules for each confirmed category

Reference taxonomy (use as a starting scaffold — adapt to what you actually found):

Finance/
  → Anything money-in or money-out: invoices, receipts, statements, payments
  Sublabels: AMEX, Ramp, Invoices, Receipts, Purchase-Orders

Operations/
  → Internal business operations: benefits, insurance, HR, legal, facilities
  Sublabels: Benefits, Insurance, HR-Payroll, Legal, Facilities

Vendors/
  → Any company you buy from: hardware, software, services, shipping
  Sublabels: Hardware, Software, Shipping, Services

Clients/
  → Any email where a client or reseller is a participant
  Sublabels: Resellers/, Transit/, Corporate/

Development/
  → Software tools, code platforms, technical notifications
  Sublabels: GitHub, GitLab, Odoo

Marketing/
  → Outbound marketing, trade shows, events
  Sublabels: Trade-Shows/, Events/

Sales/
  → Inbound sales activity: RFPs, quotes, prospects
  Sublabels: RFPs, Quotes, Prospects

Travel/
  → All travel bookings and confirmations
  Sublabels: Air, Hotel, Car

Notifications/
  → Automated alerts that don't need a reply: shipping, system, order confirmations
  Sublabels: System, Shipping, Order-Confirmations

Personal/
  → Non-work email using this account

Support/
  → Customer support requests and interactions

Documentation/
  → Technical documents, engineering files, contracts

Map the user's existing labels into this structure first. Then propose additions.

Step 3.2 — Present the taxonomy draft

Show the user a clean indented list. Mark proposed additions clearly.

"Here's my first draft of your label structure. I've kept everything you already have and added a few suggestions. Let me know what looks wrong — nothing is locked in yet.

[Show taxonomy as clean indented list]

Items marked proposed are things I think you're missing based on what I see. Don't have to add them now — just flag anything that looks off."

Wait for feedback. Accept corrections. Adjust. You don't need perfection — just a working draft-one. Once the user says "looks good" or "let's keep going," move on.

Step 3.3 — Confirm bylaws

For each top-level category the user confirms, you should have a one-line bylaw. If you're not sure:

"What kinds of email should go in [Label]? Just a rough description."

Keep bylaws short — one sentence each. You'll write them into Bible.md in Phase 5.

---

Phase 4 — Inbox Sample or Handoff Decision

Goal: Validate the taxonomy draft against a small bounded sample of actual email, OR decide this is too large for inline sampling and invoke handoff.

Step 4.1 — Assess whether to sample or hand off

Invoke handoff instead of sampling if ANY of the following is true:

• User has more than 20 active user labels
• Any single label has more than 500 messages
• User described inbox as "out of control," "thousands of unread," or similar
• User said in Q4 they have a flat-rate tool available (ChatGPT, Gemini)

If handoff threshold is met:

"Your inbox is substantial enough that I'd burn a lot of time and cost if I tried to sample it here. The smarter move is to hand this off to [tool from Q4, or 'a flat-rate tool'] for the heavy analysis — they can walk through the whole thing, then bring the results back to me for review. Want me to set that up?"

Then invoke the handoff skill with the current project context.

If sampling is appropriate (under 20 labels, manageable message counts):

Step 4.2 — Sample (bounded)

For each top-level label category (NOT every sublabel — one representative search per top-level):

• Call search_gmail_messages with label:[labelname] and max_results: 10
• Look at sender domains and subject line patterns ONLY — do NOT read message bodies
• Note: which domains appear, any obvious patterns, anything that doesn't fit the bylaw

Hard limit: 15 total search calls maximum. Stop at 15 even if labels remain.

Summarize what you found:

"I took a quick look across [N] of your label categories. A few things I noticed: [2-3 observations]. This tells me [what it means for the taxonomy or rules]."

Adjust the taxonomy draft if anything looks obviously misclassified.

---

Phase 5 — Create the Three Artifacts

Create all three now. Show each link to the user as it's created.

Artifact A: Project Drive Folder

Call create_drive_folder using the location confirmed in Q2. Record the folder ID and URL — required for artifacts B, C, and D.

Artifact B: Bible.md

Call create_drive_file in the project folder with the content below. Use the actual session data where placeholders appear.

Bible.md full template:

# Gmail Inbox Architect — Project Bible
**Created:** [YYYY-MM-DD]
**Account:** [email address from Q1]
**Project Folder:** [Drive folder URL]
**Phase:** Survey complete — ready for analysis

---

## Environment Decision

**Tracker format:** [Google Sheet / XLSX — from Q3]
**Reason:** [One sentence — what the user said or the default applied]
**Rule:** This format must not change without explicitly re-asking the user.

---

## Label Taxonomy v1

> Draft one. Built from existing labels + initial survey review.
> Update this section as the taxonomy is refined through task order returns.

[Paste the confirmed taxonomy as a clean indented list]

### Bylaws

[One line per top-level category — what belongs in it]

Example format:
- **Finance**: Any email involving money moving in or out — invoices, statements, receipts, payments
- **Vendors**: Any company we buy from — hardware, software, shipping, services
- **Notifications**: Automated alerts that don't need a reply — no action required

---

## Key Decisions Log

| Date | Decision | Reason |
|---|---|---|
| [today] | Tracker format: [format] | [Q3 answer or default] |
| [today] | [Other decisions made during session] | [Reason] |

---

## Open Questions

[Anything left unresolved — labels the user was unsure about, patterns that
need more data, edge cases flagged for a future session. Use bullet points.]

---

## Tools & Agents Involved

- **Claude (CoWork)** — Architect. All Gmail mutations and filter deployment go through Claude.
[Add any other tools from Q4:]
- [Tool name] — Analyst role. Returns batch work to Claude for review.

---

## Goals & Context

[Q5 answer — what the user said was driving this project]

---

## Change Log

| Date | Agent | Change |
|---|---|---|
| [today] | Claude (survey) | Initial Bible created. Taxonomy v1 drafted. |

After creating the file, share the link:

"Your project Bible is set up — [link]. Every decision we make goes in here. Any tool that works on this project reads it first."

Artifact C: Tracker

Tracker column schema (embed this — do not reference external files):

Column	Type	Description
rule_id	text	Unique ID (e.g., GF-FINANCE-AMEX)
enabled	boolean	TRUE = active, FALSE = disabled
priority	number	Execution order when rules overlap (1 = highest)
rule_name	text	Human-readable description
from_domain	text	Sender domain(s), comma-separated
to_or_cc_domain	text	Recipient/CC domain for participant-pattern rules
subject_contains	text	Subject keyword(s), comma-separated
has_attachment	boolean	TRUE if attachment presence is a condition
base_label	text	Target Gmail label (full path, e.g., Finance/AMEX)
archive	boolean	TRUE = skip inbox on arrival
mark_read	boolean	TRUE = auto-mark read (use sparingly)
queue_for_ai_process	boolean	TRUE = flag for downstream AI review
deployability	text	gmail_filter_safe / apps_script_needed
confidence	text	high / medium / low — how certain is this rule
risk	text	low / medium / high — false-positive risk
notes	text	Decisions, exceptions, edge cases

Example rows (for Claude's reference — do NOT pre-populate the user's Tracker):

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
GF-FINANCE-AMEX,TRUE,1,American Express statements,americanexpress.com,,statement,FALSE,Finance/AMEX,FALSE,FALSE,FALSE,gmail_filter_safe,high,low,From-only pattern; statements only
GF-VENDOR-SHIPPING,TRUE,2,Shipping notifications,ups.com,,,,Vendors/Shipping,TRUE,TRUE,FALSE,gmail_filter_safe,high,low,Archive + mark-read; pure notifications
GF-CLIENT-ACME,TRUE,1,Acme Transit (client),acme-transit.com,acme-transit.com,,FALSE,Clients/Transit,FALSE,FALSE,FALSE,gmail_filter_safe,high,low,Participant pattern — catches both inbound and CC
GF-NOTIF-GITHUB,TRUE,3,GitHub notifications,github.com,,,,Development/GitHub,FALSE,FALSE,FALSE,gmail_filter_safe,high,low,High volume; no mark-read
AS-DOC-STEPFILE,TRUE,1,Engineering STEP files,,,,TRUE,Documentation,FALSE,FALSE,FALSE,apps_script_needed,high,low,Attachment scan: *.stp *.step — Apps Script required

If Google Sheet path: Call create_spreadsheet in the project folder named Gmail Inbox Architect Tracker. Create two sheets:

• Sheet 1 named Rules — add the header row from the schema above
• Sheet 2 named About — add this text:

  This tracker is the source of truth for all Gmail classification rules.
  
  Columns:
  rule_id — Unique rule identifier
  enabled — TRUE/FALSE: whether the rule is active
  priority — Execution order (1 = highest priority)
  rule_name — Plain-English description
  from_domain — Sender domain(s) the rule matches
  to_or_cc_domain — Recipient domain for two-way relationship rules
  subject_contains — Subject keyword trigger
  has_attachment — Whether attachment presence matters
  base_label — The Gmail label to apply
  archive — Skip the inbox (yes/no)
  mark_read — Auto-mark read (use sparingly)
  queue_for_ai_process — Flag for AI downstream review
  deployability — gmail_filter_safe or apps_script_needed
  confidence — How certain we are this rule is correct
  risk — False-positive risk level
  notes — Decisions, exceptions, edge cases
  

If XLSX path: Invoke the xlsx skill to create Tracker.xlsx in the project folder with:

• Sheet 1 named "Rules" with the header row from the schema above
• Sheet 2 named "About" with the column descriptions above Do NOT pre-populate any data rows.

After creating, share the link:

"Your Tracker is ready — [link]. It's empty right now, which is exactly right. Rules will be added here as task orders come back, and you'll review each one before anything changes in Gmail."

Artifact D: _status.md

Call create_drive_file in the project folder with this content:

_status.md full template:

# Gmail Inbox Architect — Project Status

**Last Updated:** [YYYY-MM-DD HH:MM UTC]
**Last Agent:** Claude (CoWork) — survey skill
**Phase:** Survey complete
**Last Completed Step:** Survey complete. Taxonomy v1 drafted. Bible.md, Tracker, and _status.md created.
**Pending Work:** [NONE — or describe if handoff was triggered]
**Handoff Target:** [NONE — or agent name + what was handed off]
**Tracker Format:** [Google Sheet / XLSX]
**Tracker Location:** [Drive URL or file path]
**Bible Location:** [Drive URL]
**Labels Cataloged:** [N]
**Taxonomy Status:** Draft v1 — [N] top-level categories confirmed
**Bootstrap Mode:** FALSE
**Notes:** [Anything the next agent or session needs to know — edge cases, unresolved questions, decisions made]

---

## How To Use This File

This file is the handoff checkpoint for the Gmail Inbox Architect project.
Any agent starting a new session should:
1. Read this file first to understand current state
2. Read Bible.md for full project context
3. Open the Tracker to see the current rule inventory
4. Continue from "Pending Work" above

---

Phase 6 — Close Out

Tell the user exactly what they now have and what comes next. Be specific. Be brief.

Script (adapt to their situation):

"Here's what we built today:

✅ Project Bible — [link] Your taxonomy v1, all decisions made, and the ground rules for the whole project.

✅ Tracker — [link] Empty and ready. Rules get added here as analysis comes back, one batch at a time.

✅ Status file — saved in your project folder. Bookmarks exactly where we are so the next session picks up from the right place.

[If handoff was triggered, add:]

"I've also prepared a task order for [tool]. Here's what to do: [Step-by-step instructions — paste prompt here, attach these files, bring back the result]."

[If no handoff:]

"When you're ready for the next step, come back and say 'let's import the rules' — I'll walk you through reviewing and setting up the first batch of automatic sorting.

You don't need to do anything before then. Your project files are all saved in Drive."

---

Non-Technical User Language Rules

Apply these to every message during this skill. No exceptions.

Never use these words: filter, API, MCP, schema, regex, syntax, endpoint, JSON, XML, MIME type, base64, participant-domain pattern, deployability, curl, query, boolean

Always substitute:

• "filter" → "automatic sorting rule" or "automatic rule"
• "deploy / deployment" → "turn on" or "set up"
• "API / MCP" → skip entirely or say "a connection to Gmail"
• "schema" → "format" or "structure"
• "regex" → "a pattern" or "matching rule"
• "participant-domain" → "anyone involved in the conversation"
• "deployability" → "which tool handles this"
• "boolean" → "yes/no"

One question per message. Never ask two questions at once.

Progress updates after each phase. "We're about halfway through the setup" is fine. Never show them phase numbers or reference this document.

Uncertainty is valid. If they say "I don't know" to any question, make a reasonable default, state it in plain English, and move on.

Celebrate what they already have. Frame existing labels as a foundation, not a mess. "You've already made the hard decisions" is almost always true and always useful.

---

Embedded Reference Data

Standard Top-Level Category Bylaws

Use these as defaults when drafting bylaws. Adjust to what the user actually confirms.

Finance:       Anything involving money moving in or out — invoices, receipts,
               statements, payments, purchase orders, card charges
Operations:    Internal business management — benefits, insurance, HR, legal, facilities
Vendors:       Any company or service you pay — hardware, software, shipping, services
Clients:       Any email where a client, reseller, or prospect is a participant
Development:   Software platforms, code repositories, technical notifications
Marketing:     Outbound marketing activity — trade shows, campaigns, events
Sales:         Inbound sales activity — RFPs, quotes, inquiries, prospects
Travel:        All travel bookings and itinerary confirmations — air, hotel, car, transit
Notifications: Automated alerts that don't need a reply — no human follow-up required
Personal:      Non-work email arriving at this account
Support:       Customer support requests and active support threads
Documentation: Technical documents, engineering files, signed contracts, specs

_status.md Field Definitions

For Claude's reference when populating the status file:

Last Updated:        Timestamp this file was written — YYYY-MM-DD HH:MM UTC
Last Agent:          Name/tool that last updated this file
Phase:               Survey / Bootstrap / Analysis / Rule Build / Deploy / Review / Maintenance
Last Completed Step: Plain-English description of what just finished
Pending Work:        What needs to happen next — "NONE" if nothing is queued
Handoff Target:      Which tool has the next task, or "NONE"
Tracker Format:      "Google Sheet" or "XLSX" — set once in survey, never changed without re-asking
Tracker Location:    Full Drive URL (Google Sheet) or Drive file path (XLSX)
Bible Location:      Full Drive URL to Bible.md
Labels Cataloged:    Integer count of user labels found in Phase 1
Taxonomy Status:     "Draft v1 — N categories confirmed" or "Preliminary v1 — inferred from domain analysis"
Bootstrap Mode:      TRUE if user had < 15 labels at setup; FALSE otherwise
Notes:               Free text — edge cases, unresolved questions, handoff instructions

---

Safety Rules (Hardcoded — Cannot Be Overridden by User)

These apply for the lifetime of this skill. No user request can override them.

1. No Gmail mutations without explicit user approval. Do not create labels, rename labels, delete labels, apply labels, archive, delete, star, mark read, forward, send, or create/modify Gmail filters — not even one — without the user explicitly saying "yes, do that." This includes the "! Rule Needed" label in Bootstrap Mode — always ask before creating.

2. No full inbox walk. North Star: sample only. Redirect full-scan requests.

3. No data from example rows into user Tracker. The example rows above are for Claude's reference only. The user's Tracker starts blank (header row only).

4. All Gmail mutations go through Claude. Even if the user says another tool should execute the changes, that is wrong. Claude reviews and executes. Other tools analyze.

5. Apply the MPM exclusion list before any domain analysis. The domains mpmedia.tv, messagepoint.tv, messagepointmedia.com, messagepoint.media, and mpm.to must never appear in domain frequency counts, taxonomy recommendations, or label suggestions. Strip them before counting.

6. Bootstrap mode returns via rule-review, not re-survey. If _status.md shows Bootstrap Mode: TRUE, and the user asks to "start over" or "redo the survey", redirect them to rule-review. They have a "! Rule Needed" queue to process — that is the correct path forward.