SKILL.md

skills/partner-pipeline-push/SKILL.md

1. ---
2. name: partner-pipeline-push
3. description: >-
4. Push a cohort of Meridian Display Co. clients from the quarterly-outreach vault
5. (03-Clients/client-stubs) into a Bitrix deal funnel and post each client's enrichment profile as a
6. comment on their deal. Use when Matt says "push these clients into the pipeline", "load this
7. cohort into Partner Tier Upgrade" (or its old name, "Partner Outreach"), "create deals for these
8. graduates", "push the [tier/segment] clients into Bitrix", "add them to the partner pipeline",
9. "compile the CRM mapping and push them", or "post the enrichment comments on those deals", or
10. hands over a cohort (e.g. Retail -> Palladium Partner graduates) and wants them created as deals,
11. linked to their contact, tagged with User Group, and annotated with their vault research. One deal
12. per client; deal name = first_name + " " + last_name. Do NOT use for drafting outreach emails
13. (matt-guerra-email) or for enriching the stubs themselves (client-enrich).
14. ---
16. # partner-pipeline-push
18. Turns a selected cohort of client stubs into Bitrix deals, wires up the client +
19. tier fields, and drops each client's research into the deal as one clean comment.
20. End to end: **cohort -> cohort mapping -> create deals -> link contact + User Group
21. -> (locate stubs by stage) -> post enrichment comment.**
23. This is a **live CRM write** workflow. Confirm scope and cost-of-mistake before
24. mass writes, and always verify with a single test write before batching.
26. > Verified against live Bitrix 2026-08-12. Names and enum values below were wrong
27. > in earlier versions of this skill and made it fail outright. If anything here
28. > disagrees with `list_pipelines` / `find_field`, trust the live call and fix this file.
30. ## Prerequisites
32. 1. Read `03-Clients/CLAUDE-clients.md` and root `MEMORY.md`.
33. 2. **The target Bitrix funnel must be write-enabled** in the "Bitrix24 CRM - Meridian
34. Display" connector. Key the allowlist on **categoryId 24**, not the display
35. name. The funnel was renamed from "Partner Outreach" to
36. **"Partner Tier Upgrade"** on 2026-08-06, and the stale name sitting in
37. the allowlist silently broke **every deal write in every funnel** for five days.
38. If a write returns `Configured write funnel '...' not found`, that is this bug.
39. **Editing the config is not enough: the app must be fully restarted**, because
40. the MCP server holds the allowlist in memory.
41. 3. The cohort's stubs should already be enriched (their `## Research` populated by
42. `client-enrich`). This skill only *reads* the stub research; it doesn't create it.
43. 4. Bitrix tools are usually deferred, so load them first with ToolSearch, e.g.
44. `select:mcp__Bitrix24_CRM__Meridian_Display___create_deal,...link_deal_contact,...set_deal_fields,...add_deal_comment,...list_records,...list_pipelines,...pipeline_summary,...get_record,...find_field`
45. (the server-id prefix may differ; match by the `..._create_deal` etc. suffix).
47. ## Reference values (Partner Tier Upgrade)
49. - Funnel: **Partner Tier Upgrade**, categoryId **24**. Renamed 2026-08-06;
50. the vault/XML pipeline key `partner_outreach` is unchanged.
51. - Entry stage: **LinkedIn Research & Connection** = `C24:UC_7KD3PA`.
52. - Other live stages include `Update Info Plinth`, `TIER CHANGE EMAIL SENT`,
53. `Need Artwork/Mockup`, `Gift Mockup Sent`, `Client Approved`, `Client Replied`,
54. `Qtly Touch-Point Scheduled`, `Deal won` = `C24:WON`, `Not Interested` = `C24:LOSE`,
55. plus several `... - HAZEL ONLY` Potential-Partner stages.
56. - **Re-read stages with `list_pipelines` or `pipeline_summary` before relying on any
57. code.** Stages get retired: `1st Reachout (Email/LinkedIn)` (`C24:PREPARATION`) no
58. longer exists but appears in older notes and returns a bare token.
59. - **User Group** field = `UF_CRM_5F2C19A7B3D41` (enumeration). Options:
60. `Retail | Palladium Partner | Platinum Partner | Iridium Partner | Rhodium Partner | Potential Partner | Reseller`.
61. The values are the **full labels** ("Palladium Partner"), not the bare tier ("Palladium").
62. An earlier version of this skill passed the bare tier and `set_deal_fields` rejects it.
63. They match stub `user_group_correct` exactly.
64. Set by label: `set_deal_fields(id, {"User Group": "Palladium Partner"})`.
65. - The deal card's **"Client"** = the standard contact binding. Set it with
66. `link_deal_contact` (there is no custom field literally named "Client").
68. ## The pipeline
70. ### 1. Select the cohort
72. Filter `03-Clients/client-stubs/*.md` frontmatter. All stubs live flat in that
73. folder, one `.md` per client. Segmentation lives in `user_group_correct` (the
74. computed, true tier: **this is the one to filter on**) and `user_group` (the raw
75. Plinth store group, which is blank on most stubs; do not filter on it).
77. Example (the graduates case): `user_group == Retail` AND
78. `user_group_correct == "Palladium Partner"`.
80. Run `scripts/select_cohort.py` to list matches and emit the cohort mapping.
82. ### 2. Compile the cohort mapping
84. `scripts/select_cohort.py` writes `cohort-mapping.xml`: one `<client>` per person
85. with `bitrix_id`, `first_name`, `last_name`, `outreach_pipeline`, `stub_file_name`,
86. `relative_path`. Keep the tags valid (`<first_name>...</first_name>`).
88. > **This file is NOT the vault census.** The vault's master list is
89. > `03-Clients/partner-client-master-list.xml` (schema 3.0), a complete census of the
90. > partner client base maintained by the weekly pipeline. `cohort-mapping.xml` is a
91. > throwaway working file for one push. Never write one over the other. (An older
92. > version of this skill emitted `crm_pipeline_mapping.xml`, which was the census's
93. > former filename, hence the confusion.)
95. ### 3. Create the deals (one per client)
97. For each client: `create_deal(pipeline="Partner Tier Upgrade",
98. title="<first> <last>", stage="LinkedIn Research & Connection")`.
100. - **Test one first**, confirm it returns `Created deal <id>...`, then batch the rest.
101. - For scale, fan the batch out to parallel sub-agents; the cost-of-mistake is real
102. so tell them the cohort is pre-approved and to record every returned deal id.
103. - Record `deal_id -> title` for the next steps.
104. - "One deal per client": if some clients may already have a deal in this funnel,
105. ask Matt whether to skip existing (true one-per-client) or create regardless.
106. - **Deal ids are not ordered against your input list.** Row 2 of a CSV can become a
107. higher id than row 100. There is no arithmetic shortcut from list position to id;
108. capture each returned id as you go.
110. ### 4. Link the contact + set User Group
112. For each deal:
114. - `link_deal_contact(deal_id, <client email from stub>)` links by **email**
115. (reliable key; it refuses if no contact matches, so record those). This fills "Client".
116. - `set_deal_fields(deal_id, {"User Group": "<their user_group_correct>"})`.
118. ### 5. (Optional) Locate stubs by stage
120. When asked "who's in stage X, find their stubs": `list_records(entity_type=deal,
121. pipeline=..., stage=<stage id or name>, created_from=..., created_to=...)`.
123. Match deal title -> `client-stubs` filename (normalized); fall back to last-name
124. fuzzy for name variants (e.g. deal "Jo-Anne Pritchard" -> `Margaret Pritchard.md`,
125. "Katherine Lowell" -> `Kathy Lowell.md`).
127. **Enumerating a large stage:** a whole-day `created_on` filter truncates at 200 rows.
128. Narrow sub-day windows do work, but the bounds resolve against Bitrix's own server
129. offset: pass `tz=Europe/Moscow` with your local wall-clock window and walk the
130. windows. Always verify coverage (union of windows == the stage's reported total)
131. rather than trusting one call.
133. ### 6. Post the enrichment comment (one per deal)
135. For each deal, take the client stub's `## Research` block and convert it to Bitrix
136. BBCode with `scripts/research_to_bbcode.py --stub PATH --title "<first last>"`, then
137. `add_deal_comment(deal_id, <bbcode>)`.
139. - Bitrix comments render **BBCode, not markdown**: `[B]HEADER[/B]`, `[LIST]`/`[*]`,
140. bare URLs auto-link. `[TBD: ...]` renders as literal text (fine).
141. - **Verify no truncation:** `add_deal_comment` echoes the posted char count, and it must
142. match the generated comment length. Comments here run ~650-2400 chars, well under
143. limits, so one comment holds the full profile.
144. - Batch via sub-agents for scale; pass each row's comment string verbatim.
146. ## Gotchas (the expensive lessons)
148. - **Write-enabled funnel gate.** Creation/updates refuse non-allowlisted funnels, and
149. a stale funnel *name* in the allowlist breaks writes everywhere, not just there.
150. Allowlist by categoryId 24. Restart the app after any config change.
151. - **User Group values are full labels ("Palladium Partner"), not bare tiers ("Palladium").**
152. `set_deal_fields` rejects the wrong label.
153. - **Link contacts by email, never by the stub `bitrix_id`.** Where populated,
154. `bitrix_id` now holds a verified deal-linked Bitrix contact id (backfilled
155. 2026-08-06, wrong values blanked), but coverage is partial and email→contact is not
156. 1:1: duplicate contacts per email are normal. Resolve via the client's live deal
157. when it matters.
158. - **Connector list/summary index lags live edits.** `pipeline_summary` / `list_records`
159. can miss a just-added stage or just-moved deals for a bit, while `get_record`
160. (single deal) is live. If counts look stale, re-sync/reconnect the connector or read
161. individual deals with `get_record`.
162. - **Shared/ops mailboxes** (marketing@, info@, careers@, supplychain@, or a colleague's
163. address on the stub) will link whatever contact owns that email, which may not be the
164. named person. Flag, don't assume. A deal-name / contact-email mismatch is **not**
165. automatically a defect: the named client is often the department head while the
166. email belongs to whoever approves the proof.
167. - **Screen out internal and role accounts.** Exclude any `@meridiandisplay.example` address
168. outright, plus role-shaped names (Marketing Vendors, Testing Testing). Name-only
169. screening has missed internal staff before.
170. - **Stub frontmatter is maintained by the weekly driver** (`07-Automation/weekly_partner_pipeline.py`).
171. Don't overwrite it from CRM.
172. - **Attribution/logging:** CRM-only actions don't change the vault, so no `LEDGER`
173. entry is required. Only log to `LEDGER` when you edit vault files.
175. ## Bundled scripts
177. - `scripts/select_cohort.py`: filter `client-stubs` by user_group /
178. user_group_correct; print the cohort and write `cohort-mapping.xml`.
179. - `scripts/research_to_bbcode.py`: read a stub's `## Research` and emit the BBCode
180. comment body (bold headers + bulleted lists) for `add_deal_comment`.
182. Both scripts must be the 2026-08-12 revision or later. Check `select_cohort.py`: its
183. `--vault` help must read `03-Clients/client-stubs` and its `--out` default must be
184. `cohort-mapping.xml`. If it still says `tracker-people` or `crm_pipeline_mapping.xml`,
185. it is the stale copy and will write a wrong `<relative_path>` into every record.