mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

SKILL.md

Markdown16.0 KB180 lines

skills/client-enrich/SKILL.md

  1. ---
  2. name: client-enrich
  3. description: >-
  4. Enrich Meridian Display Co. quarterly-outreach client stubs with Apollo + web data, per-pipeline,
  5. and write it back per the vault's scraping-dump contract. Use when Matt says "enrich this client",
  6. "enrich the winback cohort", "enrich the check-in list", "enrich the cat 24 batch", or "run
  7. enrichment". Resolves cohorts from `outreach_pipelines` in stub frontmatter across the four
  8. in-scope funnels (24 Partner Tier Upgrade, 26 Winback, 36 Quarterly Check-In, 16 Abandoned Carts),
  9. checks suppression before spending Apollo credits, and tailors the research angle to the play.
  10. Writes only under `## Research`, never `## Human Notes`, sources every claim, and appends one
  11. LEDGER entry. Not for drafting emails (that's matt-guerra-email) or pricing lookups.
  12. ---
  14. # client-enrich
  16. Enrich client stubs in the `quarterly-outreach` vault and write them back without breaking the vault's contract. This skill is a procedure Claude runs: the data comes from MCP tools (Apollo, Apify, WebSearch) that only Claude can call, and the helper scripts just do the deterministic write-back.
  18. This is the **single** enrichment skill for this vault, shared to both operators rather than forked per person (Matt, 2026-08-11; see the vault's `DECISIONS.md`). If it needs to behave differently for someone, change the skill; don't copy it.
  20. Enrichment is **pipeline-aware**. The recipe is the same everywhere; what changes is which cohort you pull, what counts as a reason to reach out, and how much you're allowed to spend.
  22. ## Before you start
  23. 1. Read `03-Clients/CLAUDE-clients.md` (the scraping-dump contract), root `MEMORY.md`, and `07-Automation/pipeline-routing-rules.md` (which funnels are in scope and who is suppressed). The rules there win if anything here conflicts.
  24. 2. Confirm the active session email for LEDGER attribution: `hello@meridiandisplay.example` → **Matt**, `accounts@meridiandisplay.example` → **Hazel**, anything else → `Unknown (<email>)` and flag it.
  25. 3. Know the cost rules: Apollo charges **1 credit per matched person** (0 if not found) and **1 credit per found company**. You MUST confirm credit cost with the user before any Apollo call, stating the total upfront for a batch (e.g. "Enriching 20 contacts will cost up to 20 credits. Proceed?"). Apify is paid per result (~$0.004/profile), so confirm before using. WebSearch is free.
  27. ## The four pipelines
  29. | Frontmatter / XML key | Bitrix funnel | cat | Scope | The angle enrichment must serve |
  30. |---|---|---|---|---|
  31. | `partner_outreach` | Partner Tier Upgrade | 24 | routing + audit | Why a partner relationship makes sense **now** |
  32. | `winback` | Winback | 26 | routing + audit | Is this account still alive, and is this still the right person |
  33. | `quarterly_checkin` | Quarterly Check-In | 36 | routing + audit | One specific, recent, dateable thing to open with |
  34. | *(no stub key)* | Abandoned Carts | 16 | audit only | Provenance only (see the cat-16 rule below) |
  36. Nothing outside this table is in scope. If someone says "all the pipelines", it means these four.
  38. ## Step 0: resolve the cohort
  40. Stubs are flat in `03-Clients/client-stubs/` (there are no per-play folders any more; older notes referencing `03-Clients/Check-In/` are stale). Pipeline membership lives in each stub's `outreach_pipelines` block. Pull a cohort from frontmatter, not from a folder:
  42. ```python
  43. import glob, yaml
  44. KEY, STATUS = "winback", "active" # partner_outreach | quarterly_checkin | winback
  45. hits = []
  46. for p in sorted(glob.glob("03-Clients/client-stubs/*.md")):
  47. t = open(p, encoding="utf-8").read()
  48. fm = yaml.safe_load(t.split("---", 2)[1]) if t.startswith("---") else {}
  49. b = ((fm or {}).get("outreach_pipelines") or {}).get(KEY)
  50. if b and (STATUS is None or b.get("status") == STATUS):
  51. hits.append((p, b.get("stage"), fm.get("email"), fm.get("user_group_correct")))
  52. ```
  54. Other valid cohort sources, in order of preference when they exist:
  55. - **A routing run:** `05-Outputs/partner-runs/routing-candidates_<date>.json`, the approved candidate list. Enriching an approved cohort before it's sent is the intended use.
  56. - **The weekly audit workbook:** `05-Outputs/Bitrix_Pipeline_Outreach_Audit_<date>.xlsx`, one sheet per funnel. Use it when Matt points at a funnel tab.
  57. - **A hand-supplied list** of names/emails/stub paths.
  59. Rules when resolving:
  60. - A client can hold blocks for several funnels (e.g. an active `winback` plus a lost `partner_outreach`). **The open block drives the angle**; closed blocks are history, useful context, not the play.
  61. - **Check suppression before spending a credit.** Skip anyone in `07-Automation/data/suppression_list.json` (names + emails) and anyone whose stub shows a Not-Interested closure (cat 24 `LOSE`, cat 36 "Not Interested"). A sizeable share of clients (roughly 150) are suppressed; they're never getting an email, so research on them is wasted money.
  62. - Report the resolved count and the skips back to the user before running.
  64. ## The enrichment recipe (per client)
  65. Run in order and **stop early when the data is complete**; don't spend credits you don't need.
  67. 1. **Read the stub.** Pull `email`, `first_name`/`last_name`, `company`, `linkedin`, `user_group_correct`, `last_order_date`, `outreach_pipelines`, and the `## Outreach Log`. Note which fields are already filled vs `[TBD]`/empty, and what's already been said to this person. A "reason to reach out" that was used last quarter isn't one.
  69. 2. **Apollo people-match by email** (`apollo_people_match`, 1 credit if found). The workhorse. A match returns the person *and* an embedded `organization`: person + company in one credit. Extract per the field map below.
  70. - If `person.title` / `person.id` come back but most fields are null (name-only), treat as a **miss**; that's common for personal/small-org domains (`@gmail`, nonprofit, indie eCommerce). Go to step 4.
  72. 3. **Apollo org-enrich** (`apollo_organizations_enrich`, 1 credit if found), ONLY if people-match matched the person but returned no `organization`, OR missed the person but you have a real company domain. Skip it when step 2 already returned the org.
  74. 4. **Company LinkedIn posts** (`harvestapi/linkedin-company-posts` via Apify `call-actor`, ~$0.002/post). Best source for the reason to reach out. Derive the slug from `company_linkedin` (`linkedin.com/company/example-brightwater-provisions` → `example-brightwater-provisions`). Input: `maxPosts: 5`, reactions/comments off, and set `postedLimit` to the window that matters for the play (see briefs below). Pick the 2-4 most outreach-relevant posts (product launches, retail/store expansion, events, hiring in the contact's department, funding) and write them as dated Signals lines, each with its post URL as source. Skip engagement-bait.
  75. - **The Apify connector has not been available on this account** (confirmed on the 2026-08-10 run). If it's still missing, skip this step and lean on WebSearch; say so in the run summary rather than silently returning thinner signals.
  77. 5. **WebSearch (free)**: press not on LinkedIn (funding, trade press, event calendars), and person/company basics when Apollo missed. For Winback, this is also the survival check.
  79. 6. **Apify LinkedIn profile fallback** (`harvestapi/linkedin-profile-scraper`, ~$0.004/profile), ONLY when Apollo missed the *person* AND the stub already has a `linkedin` URL. Never scrape by name. No known URL → leave `[TBD]`.
  81. ## Per-pipeline briefs
  83. ### 24: Partner Tier Upgrade (`partner_outreach`)
  84. Active clients (ordered within 12 months), either never contacted or newly crossed into a higher tier.
  85. - Lead with **what the company is doing that needs displays**: new locations, retail rollouts, trade shows and event calendars, sponsorships, rebrands, hiring in marketing/events.
  86. - Confirm the contact is the **right** contact. Capture `seniority` and department; if the stub's person is in ops/finance and the marketing or events owner is findable, note that in Signals. It's the most actionable thing you can hand over.
  87. - Tier-upgrade cases: say plainly what changed (headcount growth, funding, new sites). The upgrade conversation is easier with a reason attached.
  88. - `postedLimit: "3months"`. Full recipe including Apollo, since these are often thinly enriched.
  90. ### 26: Winback (`winback`)
  91. Dormant 12+ months. The copy lives in Bitrix's cat-26 automation, so enrichment is **not** feeding a drafted email. It's feeding the judgment call on whether to advance the deal. Answer three questions and put each under Signals:
  92. 1. **Is the company still operating?** Closure, acquisition, rebrand, dead domain. Web search first: it's free, and it stops you buying an Apollo credit on a company that no longer exists.
  93. 2. **Is the contact still there?** Job change is the single most common reason an account went quiet, and the funnel has a "Changed Companies" stage for exactly this. Compare Apollo `employment_history` (`current: true`) against the stub's `company`. If they've moved, say so, name the new employer, and name a successor at the old company if one is findable. That's two live leads out of one dead one.
  94. 3. **Is there a re-activation trigger?** New locations, event season, rebrand, funding: anything that means new signage.
  95. - `postedLimit: "12months"`, because the point is what happened during the silence.
  96. - **Scale guard:** the winback-eligible pool runs to several hundred clients. Never enrich the whole cohort. Enrich the slice about to be advanced out of the client bucket, in batches, with the credit total quoted first.
  98. ### 36: Quarterly Check-In (`quarterly_checkin`)
  99. Active, previously contacted, quiet 3+ months. These stubs usually already have person/company basics.
  100. - **Don't re-buy what you already have.** Skip Apollo unless person or company is genuinely `[TBD]`; run posts + web only.
  101. - What you're after is one specific, recent, dateable hook. Set `postedLimit` to cover the span since `last_touch` (default `"3months"`), so the hook is newer than the last conversation.
  102. - Cross-check the `## Outreach Log`: don't hand back a signal that was already used as an opener.
  104. ### 16: Abandoned Carts
  105. Audit-only. It's not a routing target, its deals are titled `Cart - <id>`, and the people in it are often guests who were never partner clients.
  106. - **If there's no stub in `client-stubs/`, skip them.** Don't create a stub, don't write a scratch file, don't research them. At the end of the run, state the count skipped: one line, no report. The funnel is there for provenance; Matt can see it himself in Bitrix.
  107. - If a cat-16 person **does** have a client stub, enrich it under whichever brief matches their real standing (active → 24/36, dormant → 26). The cart itself is not enrichment output; its contents and date live in Plinth/Bitrix.
  108. - Never draft cart-recovery copy here. That's `matt-guerra-email`, and only if Matt asks.
  110. ## Field map (Apollo people-match → stub)
  111. Frontmatter + Snapshot (update only if currently empty/`[TBD]`, unless told to overwrite):
  112. - `title` ← `person.title`
  113. - `seniority` ← `person.seniority`
  114. - `city` ← `person.city`, `state` ← `person.state`
  115. - `linkedin` ← `person.linkedin_url`
  116. - `company` ← `person.organization.name`
  117. - `company_linkedin` ← `person.organization.linkedin_url`
  118. - `industry`, `company_website` ← the org record. **The script can't write these** (not in its `FM_KEYS`), so fill them by hand.
  120. `## Research → ### Person / LinkedIn`:
  121. - headline (`person.headline`), current title + company + start_date (from `employment_history` where `current: true`), location, LinkedIn URL.
  123. `## Research → ### Company` (extract this TIGHT subset; never dump the raw payload):
  124. - name, primary_domain, website_url, company LinkedIn
  125. - industry, estimated_num_employees, founded_year
  126. - HQ city/state
  127. - `short_description` (the human-readable summary; keep it)
  128. - `annual_revenue_printed` if present
  129. - headcount growth (`organization_headcount_six_month_growth`, `_twelve_month_growth`) as a momentum signal
  130. - latest funding (`latest_funding_stage`, date, amount) if present
  131. - Do NOT copy `keywords`, `technology_names`, `current_technologies`; they're noise.
  133. `## Research → ### Recent News & Signals`:
  134. - Most recent `funding_events[]` (each has a citable `news_url`)
  135. - Notable headcount growth
  136. - Anything from WebSearch (new locations, events, launches), each with its URL
  137. - Pipeline-specific findings from the brief above (contact departure, company closure, upgrade justification), stated plainly and dated.
  139. `## Research → ### Sources`:
  140. - Every claim needs a source. Apollo-derived: `Apollo enrichment (people-match / org-enrich), <date>`. Funding: the `news_url`. Web: the page URL. LinkedIn: the profile/post URL. **No source, no claim.**
  142. ## Writing it back
  143. Use the helper scripts so the write is deterministic and the contract is honored. `--stubdir` is always `03-Clients/client-stubs`.
  145. ```
  146. python3 scripts/enrich_writeback.py --stub "<path to stub .md>" --payload "<path to payload.json>"
  147. ```
  149. - `enrich_writeback.py`: single stub, rebuilds the whole `## Research` block from a payload (schema in its header).
  150. - `patch_research.py`: surgical: replace or append individual subsections, leave the others byte-for-byte. Use this on re-enrichment so you don't blow away a good Company section to add one signal.
  151. - `batch_enrich.py`: batch write-back for posts + frontmatter mode.
  152. - `batch_web.py`: batch write-back for web-search signals (no credits).
  153. - `merge_writeback.py`: batch write-back combining Apollo + web.
  154. - `_stub.py`: the frontmatter helpers the write-back scripts share; not run directly.
  156. All of them:
  157. - update only empty/`[TBD]` frontmatter keys (use `--force` to overwrite),
  158. - write only inside `## Research`, stamped with today's date,
  159. - never touch `## Human Notes`, the title line, `## Order History`, `## Outreach Log`, or `## Links`,
  160. - leave the tier (`user_group`) and outreach (`outreach_type`) wikilinks intact.
  162. **Frontmatter date key: fixed 2026-08-11.** The scripts stamp the stub's *existing* date key, preferring `last_modified` (what every vault stub and the weekly driver use) and falling back to `updated`. They no longer hardcode `updated:`, which used to append a second date key that then drifted. If you see both keys on a stub, it was written before this fix, so delete the stray `updated`.
  164. Two related fixes landed at the same time: `FM_KEYS` now includes `industry` and `company_website` (previously unwritable, filled by hand), and the frontmatter regexes use `[ \t]*` instead of `\s*`. `\s*` also matches a newline, so a bare `key:` line read the *next* line as its value, decided the field was already filled, and silently skipped it. Keys written as `key: ''` were unaffected, which is why this hid for so long.
  166. Still outside the scripts' write scope: the `## Snapshot` table's `| Title |` row. It will read `[TBD]` even after frontmatter `title` is populated; update it by hand if it matters.
  168. Editing by hand is fine if you follow the same rules. Either way: confirm `## Human Notes` is byte-identical after the write.
  170. **Stay out of the XML.** `partner-client-master-list.xml` is derived from stubs plus Bitrix; enrichment doesn't change identity, tier, or pipeline placement, so it doesn't touch the census. If enrichment turns up a genuine identity or tier correction, fix the stub and flag it. Mirroring into the XML is a separate, deliberate change-set.
  172. ## After writing (required)
  173. Append ONE entry to root `LEDGER.md` for the change-set (batch many stubs into one entry), attributed to the active session user, timestamped from the system clock (`date`). **Name the pipeline and cohort in the entry** ("enriched 40 of the active cat-26 Winback cohort") so the other operator can see what was covered. Follow the format already in `LEDGER.md`. This is a session requirement, not optional.
  175. ## Cost-aware batching
  176. 1. Resolve the cohort, drop the suppressed, and report the count.
  177. 2. Split into (a) corporate emails worth an Apollo match and (b) personal/eCommerce domains where Apollo will likely miss.
  178. 3. Quote the Apollo credit ceiling for group (a) and get confirmation. Run group (b) through web search first (free), reaching for Apify only where a LinkedIn URL exists.
  179. 4. For big funnels (Winback especially), enrich in waves sized to what's actually about to be sent. Research ages; buying it months early is buying it twice.