414 lines
17 KiB
Markdown
414 lines
17 KiB
Markdown
---
|
|
name: import
|
|
description: >
|
|
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.
|