diff --git a/skills/import/SKILL.md b/skills/import/SKILL.md index 4e7819e..b582750 100644 --- a/skills/import/SKILL.md +++ b/skills/import/SKILL.md @@ -1,27 +1,413 @@ -# import +--- +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. +--- -## Trigger -Use this skill when the user brings back work from a subcontractor agent, says "the other -tool finished", "here's what ChatGPT found", "I have the CSV", or uploads/shares a file -containing proposed rules, label changes, or domain analyses. +# import — Gmail Inbox Architect -## Purpose -Parses incoming batch work in any format (MD, CSV, XLSX, Google Sheet, JSON, XML). -Normalizes the data against the Tracker schema. Sanity-checks the proposed rules. -Claude acts as the challenging architect — not a passive importer. +## What This Skill Does -## Sanity Check Logic -- **Simple domain-match rules** (from:/to:/cc: domain only): lightweight check — verify - label exists, no duplicate rule_id, pattern is valid Gmail query syntax -- **Multi-signal rules** (subject + body keyword + sender): deep check — spot-sample the - actual mailbox to verify the pattern fires as intended and doesn't over-match -- Claude should assess each rule's complexity and declare which check applies +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. -## Architect Behavior -- Question assumptions on any rule with medium/low confidence -- Flag contradictions (same domain assigned to two incompatible labels) -- Refuse to pass rules with missing required fields downstream -- Ask for justification on `do_not_automate_yet` overrides before accepting +Only approved rules enter the Tracker. Nothing touches Gmail. Claude is the architect — +the subcontractor is the analyst. -## Skill Stub — Implementation Pending -Full SKILL.md to be written in build session. Load CW-020_Concept.md for scope and design intent. +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.