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

name, description

name

description

import

Receives subcontractor results and loads approved rules into the project Tracker. Use when the user says "import the results", "bring back the batch", "here are the results from ChatGPT", "process the task order return", "load the rules", or pastes/uploads output from a subcontractor AI tool. Accepts any format — CSV, XLSX, Markdown tables, JSON, or structured prose. Validates each rule against Bible.md bylaws, spot-samples Gmail to verify confidence, and routes rules by deployment path. Runs after handoff returns results, before deploy. Part of the Gmail Inbox Architect plugin.

import — Gmail Inbox Architect

What This Skill Does

Receives batch work from a subcontractor AI tool and processes it into the project Tracker. Accepts any format the subcontractor returned — CSV, XLSX, Markdown tables, JSON, or structured prose. Normalizes everything to the Tracker schema. Presents Claude with a review queue where each proposed rule is examined, challenged if weak, modified if needed, and routed to the correct deployment path.

Only approved rules enter the Tracker. Nothing touches Gmail. Claude is the architect — the subcontractor is the analyst.

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

---

When This Skill Is Triggered

• User says: "import the results", "bring back the batch", "here are the results from ChatGPT"
• User says: "import Finance results", "process the task order return", "load the rules"
• Handoff skill directs the user here after a subcontractor completes a batch
• User uploads or pastes subcontractor output and asks Claude to review it

---

Prerequisites

Before processing, verify:

• _status.md exists with Phase = "Handoff in progress" or later
• Bible.md exists with taxonomy and bylaws
• Tracker exists (Google Sheet or XLSX)

If any artifact is missing, stop and redirect:

"I need your project files to process this. Can you tell me where your project folder is in Google Drive? I'll find the setup files and we can get started."

---

Dependencies

• Google Workspace MCP — to read Bible.md and _status.md, update the Tracker, and spot-sample Gmail for rule validation
• xlsx skill — only needed if the subcontractor returned an XLSX file that requires parsing beyond Claude's native table reading

---

Execution Flow

Phase 1 → Sanity check (project artifacts exist and are in the right phase)
Phase 2 → Receive and identify the batch (format, which batch, complete or partial)
Phase 3 → Parse and normalize (convert to internal schema regardless of input format)
Phase 4 → Pre-screen (flag obvious issues before the review queue)
Phase 5 → Review queue (Claude examines each rule — approve / modify / reject / park)
Phase 6 → Load approved rules into Tracker
Phase 7 → Update _status.md and brief the user

---

Phase 1 — Sanity Check

Read _status.md from the project Drive folder.

Check:

1. Phase = "Handoff in progress" or any later phase
2. Bible Location has a valid URL
3. Tracker Location has a valid URL or path
4. Handoff Target names the tool that was sent the work

If Phase = "Survey complete" (handoff was never sent):

"It looks like we haven't sent any task orders out yet. Before I can import results, we need to run the handoff step first. Say 'set up the handoff' and I'll build the task orders."

If Phase is "Deploy" or later and user is adding a new batch:

"Your rules are already live. Are you adding more rules from a new batch, or is this a correction to something already running?"

Wait for clarification before proceeding.

---

Phase 2 — Receive and Identify the Batch

Ask the user:

"Great — what did [tool] send back? You can paste it here, share a Drive link, or upload the files. Whatever format they returned is fine."

Wait for the user to provide the output. Then identify:

Format:

• Three CSVs (filter_rules, apps_script_rules, taxonomy_notes) — preferred
• Single CSV with mixed content
• Markdown table(s)
• JSON
• XLSX
• Structured prose (subcontractor wrote rules in paragraphs or bullets)
• Partial return (only some categories present)

Which batch: Match to a batch folder in the Task Orders folder. If unclear, ask: "Which label group did this cover — the full inbox or a specific category?"

Complete or partial: If the subcontractor said it's delivering in sub-batches, note it. Process what's here and track what's still coming in _status.md.

---

Phase 3 — Parse and Normalize

Convert the subcontractor's output into Claude's internal working list. For each proposed rule, extract:

proposed_id       — subcontractor's ID, or auto-assign if none given
rule_name         — plain English description
signal_type       — what triggers this rule: domain / subject / participant /
                    attachment / body_text / semantic
from_domain       — sender domain(s) if applicable
to_or_cc_domain   — recipient domain for participant rules
subject_contains  — subject keyword(s) if applicable
has_attachment    — TRUE/FALSE
body_signal       — body text pattern if applicable (Apps Script path)
base_label        — target Gmail label
archive           — TRUE/FALSE
mark_read         — TRUE/FALSE
deployability     — gmail_filter_safe / apps_script_needed / studio_candidate
confidence        — high / medium / low
risk              — low / medium / high
notes             — subcontractor's reasoning and basis

Normalization by Input Format

Three CSVs (preferred): Read each file. Map columns directly to internal schema. Fill missing optional columns with defaults (enabled=FALSE, queue_for_ai_process=FALSE unless explicitly flagged).

Single CSV with mixed deployability: Split rows by the deployability column value into gmail_filter_safe, apps_script_needed, and studio_candidate groups. Process as above.

Markdown tables: Parse column headers. Map to internal schema by best match. Log any unmapped columns in the notes field. Flag unmapped columns for review.

JSON: Parse key names and map to internal schema. Join arrays (e.g., multiple domains) with semicolons for Tracker storage.

XLSX: Invoke the xlsx skill to read the file content. Then treat as table data from that point.

Structured prose: Extract each proposed rule manually. For each:

• Find the target label
• Find the trigger condition (domain, subject, attachment, body text, semantic)
• Assign deployability based on signal type:
  • Domain / subject / participant pattern → gmail_filter_safe
  • Attachment filename / body text / multi-condition logic → apps_script_needed
  • "Intent" / "topic" / AI classification / anything semantic → studio_candidate
• Assign confidence = medium and risk = medium unless stated otherwise
• Copy the subcontractor's explanation verbatim to notes

Partial return: Process what exists. Create an empty normalized list for missing categories. Note which categories are still outstanding in _status.md.

Taxonomy Notes

Taxonomy notes (proposed labels, policy observations, do_not_automate_yet items) are NOT Tracker entries. Keep them in a separate internal list for Phase 5.

---

Phase 4 — Pre-Screen

Before the review queue, run a fast automated pass to flag issues. Collect — don't present yet. These flags drive how rules are prioritized in the queue.

Issue	Flag	Queue behavior
Filter rule has no from_domain, subject_contains, or to_or_cc_domain	WEAK_SIGNAL	Requires spot-sample or reject
Rule targets a label not in the Bible.md taxonomy	LABEL_MISMATCH	Requires decision
archive=TRUE AND mark_read=TRUE on a non-notification label	AGGRESSIVE	Warn Claude
confidence = low	LOW_CONFIDENCE	Requires spot-sample before approve
risk = high	HIGH_RISK	Requires explicit Claude approval with stated reasoning
Participant pattern on a vendor/service label	LOGIC_ERROR	Likely wrong — flag
From-only pattern on a client/reseller label	LOGIC_ERROR	Likely wrong — flag
studio_candidate	STUDIO_PARK	Auto-park — don't block the queue

After pre-screening, show a summary:

"I've gone through [N] proposed rules. Here's the breakdown before we review them:

✅ [N] look solid — strong signals, clear basis ⚠️ [N] need a closer look — weak signals or logic questions 🔴 [N] need your explicit call — high risk or low confidence 📋 [N] automation script rules — valid but deployed differently 🅿️ [N] parked as future candidates — saved for when we have the right tools

Want to go through them? I'll start with the ones that need attention."

---

Phase 5 — Review Queue

Present rules in batches of 5-8. Flagged rules first, then clean rules. Claude challenges weak proposals — this is not a rubber-stamp step.

Presenting Each Rule

[Rule ID] — [rule_name]
Target label: [base_label]
Trigger: [plain English — what signal fires this rule]
Basis: [subcontractor's notes]
Confidence: [high/medium/low]  |  Risk: [low/medium/high]
Deployment path: [plain English — Gmail rule / automation script]
[FLAG — if any, explain in plain English what the concern is]

For clean batches with no flags, present 5-8 at a time:

"These [N] look straightforward — same pattern, high confidence, low risk. Approve the group or flag any you want to look at individually."

Decision Options

• Approve — "looks good" / "yes" / "approve all" for a batch
• Modify — "change the label to X" / "drop the archive flag" / "add fedex.com to the domain list"
• Reject — "this is wrong" / "skip it" — rule dropped with a note recording why
• Spot-sample — "I'm not sure — check the mailbox" — triggers Phase 5a below
• Park — "save it but don't deploy" — enters Tracker as enabled=FALSE with a park note

Phase 5a — Spot-Sampling

When Claude wants to verify a rule, call search_gmail_messages.

For gmail_filter_safe rules: Search for the proposed domain and/or subject keyword. Review top 10 results — sender, subject line, and current label. Report back in plain English:

"I searched for email from americanexpress.com with 'statement' in the subject — found 47 messages, all already in Finance/AMEX. The pattern holds."

For apps_script_needed rules: Full body text isn't available through Gmail search. Use a proxy:

• For body text signals: search sender domain + any subject pattern as a proxy
• For attachment patterns: search sender domain with has:attachment as a proxy Always flag the limitation:

"I can't read message content directly — I searched [domain] with attachments as a proxy and found [N] messages. This is approximate; the automation script will check the actual content when it runs."

Hard limit: 15 spot-sample calls per import session. Stop at 15. Remaining unsampled rules get confidence=medium and a note: "Spot-sample limit reached — not verified."

Handling Taxonomy Notes

After rules are reviewed, present taxonomy notes:

"The analysis also flagged a few things about your label structure:"

For each note:

• confirmed_existing — acknowledge, no action
• proposed_new — ask: "Do you want to add [label] to your taxonomy?" If yes → update Bible.md taxonomy section and bylaws
• policy_note — read it aloud, ask if it should go in the Decisions Log
• do_not_automate_yet — acknowledge, add to Bible.md Open Questions section

---

Phase 6 — Load Approved Rules into Tracker

Write all approved (and parked) rules to the Tracker after the queue is complete.

Tracker Column Schema

rule_id              — Unique ID (GF-[CAT]-[DESC] or AS-[CAT]-[DESC])
enabled              — FALSE — always; user activates via deploy skill
priority             — Integer 1-99 (1 = highest; base label rules ~50; secondary ~80-90)
rule_name            — Plain English description (max 60 chars)
from_domain          — Sender domain(s), semicolon-separated
to_or_cc_domain      — Recipient domain for participant-pattern rules; blank for from-only
subject_contains     — Subject keyword(s), semicolon-separated; blank if not used
has_attachment       — TRUE/FALSE
base_label           — Full Gmail label path (e.g., Finance/AMEX)
archive              — TRUE/FALSE
mark_read            — TRUE/FALSE
queue_for_ai_process — TRUE/FALSE
deployability        — gmail_filter_safe / apps_script_needed / studio_candidate
confidence           — high / medium / low
risk                 — low / medium / high
notes                — Basis, modifications made during review, batch source, flags

Rule ID format:

• Gmail filter rules: GF-[CATEGORY]-[DESCRIPTOR] e.g. GF-FINANCE-AMEX-STMT
• Apps Script rules: AS-[CATEGORY]-[DESCRIPTOR] e.g. AS-DOC-STEP-FILE
• Studio candidates: SC-[CATEGORY]-[DESCRIPTOR] e.g. SC-SUPPORT-COMPLAINT-TONE

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

Writing to Google Sheet Tracker

Call modify_sheet_values or append_table_rows to add rows to the Rules sheet. Always:

• Set enabled = FALSE
• Append the batch name to the notes field: "Source: Batch 1 - Finance"
• Note any modifications made during review

Writing to XLSX Tracker

Invoke the xlsx skill to append rows to the Rules sheet. Same field rules apply.

After writing:

"Done — [N] rules added to your Tracker, all inactive.

[N] are ready to turn on as Gmail sorting rules. [N] will need a small automation script — I'll walk you through that when we deploy. [N] are parked for a future step when we have the right tools.

Nothing in Gmail has changed yet. When you're ready to go live, say 'deploy the rules'."

---

Phase 7 — Update _status.md and Brief the User

Update _status.md:

Last Updated: [timestamp]
Last Agent: Claude (CoWork) — import skill
Phase: Rule Build [or Deploy-ready if all batches are in]
Last Completed Step: [N] rules from [batch name] reviewed and loaded. 
  Approved: [N]. Modified: [N]. Rejected: [N]. Parked — studio: [N]. Parked — manual review: [N].
Pending Work: [NONE / or: [N] batches still outstanding from [tool]]
Handoff Target: [NONE / or: tool name if more batches coming]
Notes: [Taxonomy updates: list. Open questions added: list. Flags raised: list.]

If more batches are still coming:

"That batch is done. You've got [N] more to send to [tool]. Same process — open the next batch folder in Drive, copy the prompt, attach the files, bring back the results. Which batch is next?"

If all batches are complete:

"All batches are in. You have [N] rules in your Tracker, all inactive and ready to review.

Next step: say 'deploy the rules' and I'll turn them on — starting with the simplest and safest ones first."

If taxonomy notes updated Bible.md:

"I also updated your project Bible with [plain English description of changes]."

---

Non-Technical User Language Rules

Never use: filter, API, MCP, schema, regex, endpoint, JSON, XML, CSV, boolean, deploy, Apps Script (unless explaining what it is)

Substitute:

• "CSV" / "results file" — "the data they sent back" or "the results"
• "schema" → "format"
• "deploy" → "turn on" or "set up"
• "Apps Script" → "a small automation script" (only if you need to explain it)
• "API / MCP" → skip or "a connection to Gmail"

One question per message. Progress updates between phases.

---

Safety Rules (Hardcoded — Cannot Be Overridden)

1. No Gmail mutations. This skill reads Gmail for spot-sampling only. It does not create filters, apply labels, archive, delete, or modify anything in Gmail.

2. All rules enter Tracker with enabled=FALSE. The deploy skill activates them. Never set enabled=TRUE during import regardless of user request.

3. Claude approves every rule. No rule enters the Tracker without explicit Claude review and approval (individual or group). Batch approval of an entire import without any review is not permitted — at minimum, the pre-screen summary must be presented and confirmed.

4. Spot-sampling reads headers only for filter rules. Do not read full message body content when validating gmail_filter_safe candidates. Apps Script candidates may use proxy searches — always disclose the limitation.

5. Studio candidates are parked, not dropped. Every studio_candidate enters the Tracker with deployability=studio_candidate and enabled=FALSE. They are never silently discarded.

6. Rejected rules are logged. Every rejected rule gets a note explaining why it was rejected. This is added to the notes column in a rejected_rules log (a separate tab in the Tracker if one exists, or noted in _status.md). Rejection history matters for future analysis.