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

mattrguerra/meridian-outreach-vaultmainPrivate on GitHub, published here in full

CHANGELOG.md

Markdown15.6 KB63 lines

CHANGELOG.md

  1. ---
  2. type: changelog
  3. scope: project-root
  4. tags: [claude, outreach, changelog]
  5. created: 2026-06-16
  6. updated: 2026-09-21
  7. ---
  9. # CHANGELOG
  11. ### 2026-09-21: Tier and outreach rollups fixed; sample book added
  12. - **The tier and outreach rollups now read the fields the driver actually writes.** The five `01-Tiers/` notes filter on `user_group_correct`, the computed tier, instead of raw `user_group`, which is blank on most stubs and made every tier note under-report its own membership; [[Retail]] lists stubs computed as "Not a partner client" or with no tier. The four `02-Outreach/` notes select members by their `outreach_pipelines` key (`partner_outreach`, `quarterly_checkin`, `winback`), with [[Executive-Outreach]] as a tier-or-title cross-cut rather than a funnel. Every rollup displays only fields the stubs carry, and none sorts on the `ltv` currency string, which sorts lexically ($9,000 above $12,000). This closes the drift [[CLAUDE-clients]] flagged: queries that filtered, displayed or sorted on fields present in zero stubs.
  13. - **The vault now ships a generated sample book in `07-Automation/sample/`.** `generate_sample.py` invents the inputs (a partner roster workbook, Plinth order pages, Bitrix deals, contacts and stage histories, a merge registry and a suppression list), and `run_sample.py` replays two Monday runs, 2026-09-14 and 2026-09-21, through the real driver, `07-Automation/weekly_partner_pipeline.py`; the only thing the replay changes is the clock, pinned to each run date. Everything under `03-Clients/`, the run artifacts in `05-Outputs/partner-runs/`, the two audit workbooks in `05-Outputs/` and the state in `07-Automation/data/` is the driver's own output: 130 partner clients, 130 stubs, 130 census chunks. The 09-21 replay includes a day whose first page comes back at `suspect_row_count`, so the offset-and-dedupe paging is exercised, not just described.
  14. - See [[LEDGER]] (the 2026-09-14 and 2026-09-21 run entries) and [[HEARTBEAT]].
  16. ### 2026-08-11: `client-enrich` rebuilt for all four funnels; the Hazel fork retired
  17. - Rewrote the `client-enrich` skill from a single-cohort, folder-walking procedure into a **pipeline-aware** one covering the four in-scope funnels (24 Partner Tier Upgrade, 26 Winback, 36 Quarterly Check-In, 16 Abandoned Carts).
  18. - **Cohort resolution replaced folder-walking**: cohorts now come from `outreach_pipelines` in stub frontmatter (or a routing-candidates run, or the audit workbook), not from `03-Clients/Check-In/`, which has not existed since the 07-23 backfill.
  19. - **Suppression is now checked before any Apollo call** (`07-Automation/data/suppression_list.json` plus Not-Interested closures), so credits are never spent on opted-out clients.
  20. - **A research brief per play:** cat 24 hunts display-buying triggers and verifies the contact is the right one; cat 26 answers company-alive / contact-still-there / reactivation-trigger over a 12-month window instead of writing a hook (the copy lives in Bitrix automation); cat 36 skips Apollo by default and windows posts to since-`last_touch`; cat 16 with no stub is skipped outright and reported as a count only (Matt's call: the funnel is provenance).
  21. - Added a scale guard on Winback (by far the largest cohort: enrich in waves, never the whole cohort), a "stay out of the XML" rule, and a requirement that the [[LEDGER]] entry name the pipeline and cohort.
  22. - **Retired `client-enrich-hazel`**, a behaviorally identical fork; `client-enrich` is now the single shared skill. Rationale in [[DECISIONS]].
  23. - Updated [[SKILLS_REFERENCE]] (enrichment was listed as an unfilled gap) and [[HEARTBEAT]] (the migration off `crm_pipeline_mapping.xml`, the census's name before it was renamed `partner-client-master-list.xml`, no longer applies to either enrichment skill: verified, neither references it).
  25. ### 2026-08-10: Weekly run now emits two spreadsheets (Stage F5)
  26. - Added `outreach-pull-list` + `outreach-audit` to `weekly_partner_pipeline.py`; the weekly run now also produces `05-Outputs/Bitrix_Pipeline_Outreach_Audit_<date>.xlsx`: one sheet per outreach funnel (24/26/36/16, those four only), every client in them with Plinth locating details and the date each was last actually reached out to.
  27. - Encoded `SEND_TOKENS` (what counts as contact) and `RETIRED_STAGE_NAMES` (six deleted stage ids, three of them real sends).
  28. - Ran it live end to end; fixed cross-funnel history miscounting sends, silent partial-enumeration runs, and needless weekly re-pulls of parked cohorts.
  29. - Scope corrected to Matt's four funnels; 28 and 30 removed.
  30. - The cache holds every in-scope deal, so the next run re-pulls only the histories that can have changed (in the sample: 18 of 54).
  31. - **Fixed:** cat-36 `STAGE_NAMES` had `NEW` / `UC_LXCMAV` swapped since the 08-06 rename: `C36:NEW` is "Active Check-In List", `C36:UC_LXCMAV` is "Dormant".
  32. - Updated [[Weekly-Partner-Pipeline-SOP]] (Stage F5 + guardrail 6) and [[scheduled-task]] (prompt step 5a extended, new 5d and 5e).
  35. ## 2026-07-24: Cleanup of folders 01 to 06 + campaign note renamed to Client-Interaction
  36. Twice-audited cleanup (a reference check, then independent content verification: every deleted file proven to have no live references and no unique data). **Deleted several hundred redundant files:** the 2026-07-22 pre-restructure backup (all contents traced to live moved counterparts), a pre-refresh stub snapshot (all live and newer), a migration report, the pre-census XML backup (a newer copy is retained inside the kept snapshot), three stale June CSVs in `06-Resources` (a degraded twin of a kept workbook and superseded working copies), the June confidence-index doc, and the archived Email-2 drafts that were provably superseded or divergent sync-conflict copies (the never-redrafted ones kept pending Matt). **Kept deliberately:** one check-in reconcile backup as the single full rollback snapshot, the raw Plinth pull pages (the SOP's audit trail), and the sent first-email records: the second audit revealed an archive folder held the only copies of sent emails, so they were **moved to the Sent folder** (which now matches reality) instead of deleted. **Rename per Matt:** `Partner-Outreach.md` → [[Client-Interaction]] (internal campaign name `client-interaction`, from the Client Interaction Tracker); Bitrix funnel name and keys unchanged; an alias added so historical links resolve; the note's workbook pointer corrected. **Bonus staleness fix:** all four outreach-play notes ran dead Dataview queries (`outreach_type` no longer exists in stub frontmatter); repointed to `outreach_pipelines.*` membership, and Executive-Outreach to `user_group_correct`. Integrity after: every stub and census chunk accounted for, no broken links. See [[LEDGER]].
  38. ## 2026-07-24: Vault maintenance: root instruction files rewritten to the post-census reality
  39. The vault's scale and automation status had outrun its own documentation (the root files still described the founding-cohort vault as an unarmed template). Targeted rewrites: [[CLAUDE]] (project scope now the full partner base; XML map described as the complete partner census; `07-Automation/` re-mapped from "templates, not armed, don't run" to the **live scheduled pipeline** with its guardrails), [[MEMORY]] (new durable facts: scale, the live pipeline, the roster-workbook refresh convention, `user_group` vs `user_group_correct`; open items refreshed: the untiered-clients item closed as RESOLVED by the pipeline backfill, new items for the empty-pipeline census chunks, the legacy empty-`id` chunks, and the stub-less Q1 completed deals), [[00-Index]] (executive summary rewritten to the two-population framing: the partner census plus the original outreach cohorts; automation section added), [[HEARTBEAT]] (first real state update since init: live pipeline, pending decisions, known gaps), [[README]] and `07-Automation/README.md` (status flipped from "not seeded/armed/scheduled" to LIVE). Cleanup: removed a handful of `.DS_Store` files and one Office lock file; workflow folders and all backups left in place. Integrity verified after: every stub parses as YAML and the XML census parses clean. See [[LEDGER]].
  41. ## 2026-07-23: XML map now a complete partner census (every partner client mapped)
  42. Extended `refresh-xml` so the CRM map (then `crm_pipeline_mapping.xml`, since renamed `03-Clients/partner-client-master-list.xml`) accounts for **every** partner client (Palladium and up), not just the pipeline-mapped subset. Each run it stamps the partner clients already in the map and **adds a `<client>` chunk for any partner client missing from it**, with an empty `<pipelines count="0" />` section to populate when they enter a pipeline; new chunks are keyed `id="pl-<plinth_id>"` (stable, and collision-proof against Bitrix contact ids) and built from the client's stub. Idempotent: re-running only re-stamps, never duplicates. Dedup is by identity: two Plinth accounts that are the same person (same name + email) share one chunk, while colleagues on a shared company mailbox each get their own. Ran it against the vault: the map grew from the pipeline-mapped subset to **every partner client**, most of them new empty-pipeline chunks, 0 partner clients unrepresented, parses clean. Updated the [[CLAUDE-clients]] XML contract, [[Weekly-Partner-Pipeline-SOP]] Stage F, and [[scheduled-task]] so the weekly run keeps the census complete every time. See [[LEDGER]] and [[DECISIONS]].
  44. ## 2026-07-23: Pipeline activation prep: the roster workbook staged, runbook added
  45. Ines's partner roster workbook (the 2026-07-20 roster, not included; the sample's equivalent is `07-Automation/sample/inputs/Partner-Clients-Roster_2026-09-07.xlsx`) staged in `07-Automation/data/` and the seeder validated against it (both tabs map with zero manual overrides). The driver gained `--tab` selection, header aliases for the roster's columns, a baseline `repeat_revenue`, and an `excluded_order_statuses` filter, set to `[27, 28]` after verifying that the workbook's totals exclude cancelled orders (one long-standing account's total equals its excluding-cancelled sum to the cent), so weekly deltas stay on the baseline's counting basis. Added [[Activation-Runbook]] (validated two-pass seed commands, catch-up pull procedure, arming, reconciliation checks including known tier mismatches such as an Iridium-vs-Rhodium case, the manual first E to H pass, schedule enablement) and a seeded-history precondition to the [[scheduled-task]] prompt. The pipeline stays unseeded, unarmed and unscheduled until Matt runs the runbook. See [[LEDGER]] and [[DECISIONS]] (2026-07-22).
  47. ## 2026-07-22: Weekly Partner Client Pipeline rebuilt (v2, incremental) after the Plinth truncation diagnosis
  48. Diagnosed the lifetime-value discrepancy raised on today's Matt / Hazel / Ines call: Plinth `orders.fetch` silently truncates at ~70 orders per response (no "has more" flag, overlapping offsets), so single-call lifetime totals undercount exactly the biggest clients. On one long-standing account (Plinth customer 40115 in the sample's numbering) a one-shot query returns 70 of its 74 orders, and the missing orders are the newest ones. Rebuilt `07-Automation/weekly_partner_pipeline.py` around a local append-only order history (`07-Automation/data/order_history.json`): new `seed-baseline` (one-time load of the roster workbook, fuzzy column mapping + dry-run), `ingest` (dedupe by `order_ref`, upserts, a convergence signal for the pull loop), `classify` (computes lifetime = baseline + deltas locally; no more raw-dump args), and `verify` (no-shrink guardrail, exit 2 halts the run). Repointed `CLIENTS_DIR` to `client-stubs/` (closing the flag from the restructure), fixed `page_size` to the API's hard cap of 100, and updated [[partner-thresholds]] (the program's tier bands, new window and suspect-count keys, activation checklist), [[Weekly-Partner-Pipeline-SOP]] ("Why incremental" section, Stage A0/A rewrite, guardrail #6), [[scheduled-task]] (day-sliced pull prompt with the convergence loop), and the 07-Automation README. Tested end to end on synthetic fixtures (seed, dedupe, boundary exclusion, tier promotion, shrink flag, TBD guard: all pass). **Still not armed and no schedule created**: `min_orders_to_qualify` stays `TBD` until Matt seeds the roster tomorrow and activates. See [[LEDGER]] and [[DECISIONS]].
  50. ## 2026-07-22: 03-Clients restructured for RAG; 08-Planning added
  51. All client stubs moved from the `03-Clients/` root into a new flat `03-Clients/client-stubs/` subfolder; the root now holds only the rewritten [[CLAUDE-clients]] (new scoped rules built around the schema-2.0 XML map contract) and `crm_pipeline_mapping.xml` (since renamed `partner-client-master-list.xml`). Every stub path inside the XML (`<relative_path>` + `<summary>`) repointed to `client-stubs/`, and the stale path-form wikilinks in the draft files in `04-Working/` and `05-Outputs/` converted to bare-name links. Root [[CLAUDE]] updated with a full folder map: `07-Automation/` mapped as templates (hands off until armed) and the new root `08-Planning/` added as a human-only planning space (Matt, Hazel, Ines; Claude read-only). Dataview rollups needed no changes (`FROM "03-Clients"` is recursive). See [[LEDGER]] and [[DECISIONS]].
  53. ## 2026-06-23: Partner Outreach pipeline seeded
  54. Stood up the third outreach play. Took the storefront's customer export, kept only lifetime value ≥ $2,500 (all Retail), and deduped against the live Bitrix **Partner Outreach** funnel (cat 24, since renamed Partner Tier Upgrade): confirmed dups dropped, one likely dup kept on Matt's call. Created the outreach-play note for the funnel (then `Partner-Outreach.md`, now [[Client-Interaction]]) and seeded the survivors as un-enriched client stubs in a `03-Clients/partner-outreach/` folder (since flattened into `client-stubs/`), each wikilinked to the Retail tier note and the play note; Research left `[TBD]` for a later `client-enrich` pass. Review workbook and CSV in `05-Outputs` (since removed). See [[LEDGER]] and [[DECISIONS]].
  56. ## 2026-06-19: Email 1 templates reworked for Bitrix
  57. Turned the Email 1 set into Bitrix copy-paste HTML and finished the quarterly bullet-drafting prompt. [[Email-1-Drafting-Prompt]] moved from `_scratch` to `06-Resources` and is now a complete, reusable prompt: it takes the quarter's resource links, drafts the three "newest products & resources" bullets from the live pages in Matt's voice, and assembles the full [[Email-Success-CheckIn-1-Full]] HTML ready for Bitrix. Added a `## HTML (for Bitrix)` block to all three Email 1 templates: the Full cleaned (broken internal comment removed, copy aligned to verbatim, signature and image alt text added), the Short and Founder/CEO newly built. Verbatim approved copy preserved throughout. See [[LEDGER]] and [[DECISIONS]].
  59. ## 2026-06-16: Collaboration ledger added
  60. Created [[LEDGER]], an append-only who-changed-what log for the shared Matt + Hazel vault (separate Cowork projects, one vault over Obsidian sync). Baked a session requirement into [[CLAUDE]]: append a ledger entry on **any** vault change, attributed to the active operator by session email (`hello@meridiandisplay.example` = Matt; Hazel's email `[TBD]`). Wired [[LEDGER]] into [[00-Index]] and the reference-file map. See [[DECISIONS]] for the attribution rationale.
  62. ## 2026-06-16: Project initialized
  63. Scaffolded the Quarterly Outreach client database as an Obsidian vault. Generated the founding client stubs (the Check-In and Winback cohorts) from the original client spreadsheet (not included), segmented by `user_group` and `outreach_type`. Created the partner-tier notes (Palladium / Platinum / Iridium / Rhodium, plus Retail) from the Partner Program page, three outreach-play notes, and four verbatim email templates and two call scripts extracted from the original outreach design doc (not included). Every stub wikilinks to its tier and outreach notes; the tier and outreach notes pull members back via Dataview.