pipeline-routing-rules.md

07-Automation/pipeline-routing-rules.md

1. ---
2. type: reference
3. scope: 07-Automation
4. tags: [claude, outreach, routing, automation]
5. created: 2026-08-06
6. status: rules ratified; implementation pending
7. ---
9. # Pipeline Routing Rules: Partner Client Outreach
11. Ratified by Matt 2026-08-06 from the operations team's written procedure for pulling the quarterly check-in and Winback client lists (a Google Doc maintained by Ines and operations, updated 06-2026, not included here) plus Matt's in-session rulings. This note is the canonical rule set the weekly pipeline's future routing stage implements. **Nothing routes automatically yet**; see Implementation status.
13. > Where this note and the operations doc disagree, this note wins: the doc's operational
14. > steps compute a 180-day Winback threshold; Matt ruled **12+ months** (2026-08-06).
15. > The doc's "$2,500 total" is the Partner Program definition (lifetime), not a
16. > trailing-window spend.
17. >
18. > **Scale note (2026-08-06):** most of the partner base is dormant 12+ months (in the
19. > sample, 75 of the 128 partner clients at the 2026-09-14 run), so Winback is by far the
20. > largest wave. Under the one-touch rule, each of those
21. > clients gets exactly one pass of Bitrix's automated cat-26 sequence and then
22. > permanent silence unless they order.
24. ## The three pipelines
26. | XML key | Bitrix funnel | categoryId | Play |
27. |---|---|---|---|
28. | `partner_outreach` | **Partner Tier Upgrade** (renamed 2026-08-06 from "Partner Outreach"; same categoryId) | 24 | First touch + tier upgrades |
29. | `quarterly_checkin` | Quarterly Check-In Flow | 36 | Quarterly relationship touch |
30. | `winback` | Winback | 26 | Re-engage dormant clients |
32. ## Audit scope: NOT the same as routing scope *(Matt, 2026-08-10)*
33. The three pipelines above are what `route` **writes candidates into**. The weekly outreach
34. audit (Stage F5) **reads** a wider set: those three plus **Abandoned Carts (cat 16)**:
35. **four funnels, and only these four.**
37. | Bitrix funnel | categoryId | In routing scope | In audit scope |
38. |---|---|---|---|
39. | Partner Tier Upgrade | 24 | yes | yes |
40. | Winback | 26 | yes | yes |
41. | Quarterly Check-In Flow | 36 | yes | yes |
42. | Abandoned Carts | 16 | no | yes |
44. Everything else in Bitrix (New Orders, Processing, Rush/PO Processing, Parked, Claims,
45. Automation Testing, Pre-Production, Production, Post Production, 7 Days Delivery Up-Keep,
46. Cold Outreach) is **out of both scopes**. A 2026-08-10 session read "look in all of the
47. pipelines" literally and swept 28 and 30 into the weekly job as well; they were removed the
48. same day. If someone asks for "all the pipelines", it means **this table**, not every funnel
49. that exists. `AUDIT_FUNNELS` in `partner_pipeline/stages.py` is the executable copy of this
50. table: the two must agree, and widening either one is a decision to be asked about, not a
51. tweak.
53. ## Entry rules: evaluated weekly, per client, in this order
55. A client holds **one open outreach pipeline at a time**. **Exclusion evidence is identity-level, not chunk-level** (2026-08-06, the duplicate-twin finding): duplicate census chunks for one person can split the record, with a Not-Interested closure or open deal on one twin while the blockless twin routes clean. `route` therefore unions opt-out / open-deal / winback-done evidence across every chunk sharing an email or normalized full name, partner or not. Inheritance only ever excludes; eligibility is never inherited. The first live run caught the original case and several more, most of them twins whose other account had just entered cat 24: each a double contact prevented. The sample carries one such pair: [[Delphine Hartigan]] and [[Delphine Hartigan-Vance]] share one mailbox, only the first carries the Not Interested closure, and `route` excludes the second as "inherited from identity twin".
57. **Opt-outs never route anywhere**, and per Matt (2026-08-06) opt-out means BOTH:
58. - an explicit email unsubscribe / stop request (e.g., one client who replied on 2026-07-30 asking to be taken off the list), and
59. - **any funnel closure at a "Not Interested" stage** (cat 24 LOSE, cat 36 "Not Interested"): that closure records a request to stop receiving emails, so the client is fully suppressed from every pipeline, permanently, until Matt personally reverses it. In the sample, 3 partner clients are excluded as opt-outs.
61. 1. **Winback (cat 26)**: lifetime partner AND **no order of any size in the last 12 months**. Prior contact does NOT matter: a never-contacted dormant client is a Winback, not a first touch (Matt, 2026-08-06). Dormancy trumps everything.
62. - **Winback outreach is automated inside Bitrix, but not from the first stage** (Matt, 2026-08-06): routing a client into cat 26 drops them into the **Client bucket, the first stage, which is NOT automated**. Bitrix's automation fires only when **Nora moves the deal to a later stage**. So deal creation is safe (it parks the client), Nora's stage move is the send, and Nora controls the outreach pace. No vault-drafted emails either way: the copy lives in the Bitrix automation.
63. - **One winback touch per dormancy spell.** Once routed, the client is not routed again (to Winback or anywhere else) while they remain dormant ("reached out last month, still no order → we don't reach out again"). Only a **new order** resets them; opt-out exits them.
64. 2. **Partner Tier Upgrade (cat 24)**: active clients (an order within the last 12 months) only; two doors in:
65. - **First touch:** lifetime partner ($2.5K+, Palladium and up) AND never contacted by a client success rep. Bitrix is the source of truth for "contacted": no deal in any of the three funnels and no recorded client success touch.
66. - **Tier upgrade:** an existing client crosses into a higher tier (weekly `user_group_correct` change, including crossings produced by approved merges in `data/merge_registry.json`).
67. 3. **Quarterly Check-In (cat 36)**: previously contacted, **an order within the last 12 months**, and no outreach touch in the last 3 months (any pipeline).
68. - The order-within-12-months condition is what makes Winback suppression hold: a dormant, already-winbacked client must not fall through to the quarterly cadence.
69. 4. **No route**: everyone else, including dormant clients already winback-touched: they stay untouched until they order.
71. ## Precedence when cat 24 and cat 36 collide *(Matt, 2026-08-12)*
73. "One open outreach pipeline at a time" and the **tier-upgrade door** in rule 2 contradict
74. each other as originally written, and the contradiction is structural rather than accidental:
75. a tier upgrade by definition applies to an **active** client (an order within 12 months),
76. which is exactly the eligibility condition for Quarterly Check-In. Every tier upgrade of an
77. in-cadence client therefore produces two open pipelines.
79. **Ruling: an open cat-24 deal takes precedence. Quarterly Check-In is PAUSED, not cancelled.**
81. - A client with an open **Partner Tier Upgrade** deal does not run the quarterly
82. cadence concurrently. Park them in cat 36 **Dormant** (`C36:UC_LXCMAV`) rather than closing
83. the check-in deal: the relationship is not over, the sequence is just deferred.
84. - When the cat-24 sequence closes (won or lost), the existing exit clause takes over
85. (*"cat 24 completes → client is 'in relationship'; the quarterly cadence takes over"*) and
86. the client re-enters the check-in flow on the normal 3-month rule.
87. - **Do not close a mid-flight cat-24 deal to resolve an overlap.** Cat 24 runs
88. `TIER CHANGE EMAIL SENT → Need Artwork/Mockup → Gift Mockup Sent → Client Approved →
89. Gift Sent → Gift Delivered`; closing it mid-sequence abandons gifting work in progress.
90. - The one-open-pipeline rule stands. This clause says which one wins, not that two are allowed.
92. **Legacy backlog (2026-08-12).** A group of clients was found holding two active pipelines,
93. most of them with cat 24 at **TIER CHANGE EMAIL SENT**, from a bulk tier-change push Hazel ran
94. on 2026-07-20/21, over two weeks **before** these rules were ratified. This is legacy overlap,
95. not a routing failure: `route` already excludes any client with an open deal, so it cannot
96. recreate the condition. The working list at the time (deal ids, cat-36 side flagged for
97. parking) was a 04-Working note, not included here; the sample's equivalent is
98. `04-Working/dual-active-pipelines_2026-09-21.md`. The stage moves are Hazel's deals and stay
99. human-gated.
101. **Not a violation:** one active block alongside `completed` or `lost` ones. Closed deals are
102. deliberately retained as the evidence for "previously contacted" and "winbacked this spell".
103. In the sample's census, 35 of the 45 pipeline blocks are active, 6 completed and 4 lost.
105. ## Exit / reset
107. - **Winback client places an order** → deal closes won; dormancy clock resets; quarterly cadence eligibility resumes.
108. - **Quarterly Check-In completes** → eligible again 3 months after `last_touch`.
109. - **Cat 24 completes** → client is "in relationship"; the quarterly cadence takes over.
110. - **Opt-out** → suppressed from all pipelines, permanently, until Matt reverses it.
112. ## Execution model (Matt, 2026-08-06)
114. 1. **Winback goes live now.** Every current Winback-eligible client is loaded into the cat 26 **Client bucket**; Nora advances them at her own pace (her stage move = the send). The eligible list is **refreshed weekly**.
115. 2. **Partner Tier Upgrade (cat 24)** gets its eligible clients dropped in, with the weekly automation owning the refresh: the driver gains a routing stage (revisions to the current automation, Matt-approved).
116. 3. **Quarterly Check-In gets a new first stage: "Dormant"** (Matt is creating it in Bitrix). All check-in-eligible clients park there; Matt manually feeds **N at a time** into the flow, longest-since-last-outreach first. **N is decided with Ines.**
117. 4. **Overlap guard:** a client currently in Winback never enters the Check-In pipeline (or its Dormant stage) until they place a new order. One open pipeline per client stands.
119. First candidate list (**v2**, corrected same day after Matt ruled Not-Interested = full opt-out): `routing-candidates_2026-08-06.xlsx` (not included here): Winback by far the largest list, then the cat 24 first touches, a short Dormant queue, and the excluded clients (opt-outs, open deals, winback-done-this-spell). The sample's 2026-09-14 run has the same shape: **Winback 50 / cat 24 first-touch 29 / Dormant queue 4 / excluded 45** (open deals 33, winback-done-this-spell 4, never-contact domains 5, opt-outs 3).
121. ## Implementation status + prerequisites
123. **IMPLEMENTED 2026-08-06** in `weekly_partner_pipeline.py`: `reconcile-deals` (absorbs a weekly Bitrix deals pull into census blocks + stubs) and `route` (evaluates this note read-only; emits routing-candidates_<date>.json + the Winback import/role-review CSVs to `05-Outputs/partner-runs/`). Suppression = `data/suppression_list.json` + Not-Interested closures, enforced inside `route`. Wired into the Monday run as Stages F3/F4 ([[Weekly-Partner-Pipeline-SOP]]), **pending Matt syncing the external scheduled-task prompt**. Autonomy unchanged; Bitrix deal creation stays human-gated; `client-enrich` on approved cohorts before sending. Initial loads 2026-08-06: the cat 24 first-touch cohort pushed live; the Dormant queue blocked on the connector seeing the new stage; Winback (role-named rows held) handed to a separate session via the import CSV.
125. Prerequisites before the routing stage can be built:
126. 1. ~~Pipeline blocks on the in-flow census chunks~~ **DONE 2026-08-06:** full three-funnel reconcile: new blocks written and existing ones refreshed across the census, so every matched client's chunk now carries pipeline placement (incl. closed deals: status vocabulary active / completed / lost; closed deals are the "previously contacted" and "winbacked this spell" evidence). Unmatched deals and ambiguous ones (duplicate-account pairs) parked in a 04-Working review note (not included here).
127. 2. ~~Winback email template~~ **Not needed (2026-08-06):** Winback copy lives in Bitrix's cat-26 automation, not the vault. Deal creation only parks the client in the (non-automated) first-stage bucket; **Nora's stage move is the send**, so she is the natural throttle. Worth documenting in [[Winback-Outreach]] once confirmed: which stages fire, sequence length, stop conditions.
128. 3. **First-wave throttling**: with dormancy trumping first-touch, the day-one split is mostly Winback, with cat 24 limited to the never-contacted slice of the active clients. Winback pace is throttled naturally by Nora's stage moves out of the bucket; the open question is bucket-fill pace (dropping the whole Winback cohort into one stage at once has usability costs for her): Matt + Nora's call.
129. 4. **`bitrix_id` backfill**: **partial 2026-08-06:** all known-wrong values (Plinth/tracker ids) blanked vault-wide; **verified real contact ids set** for every client with an open cat 26/36 deal, resolved by the authoritative rule *bitrix_id = the contact the client's live deal is attached to* (corroborated by the two 07-24 hand-verified ids). The remainder (mostly not-in-pipeline clients) can wait ("contacted" checks run off pipeline blocks, not contact ids) and is best done inside the weekly run or a dedicated session where the Bitrix MCP is fast.