CLAUDE-clients.md

03-Clients/CLAUDE-clients.md

1. ---
2. type: claude-instructions
3. scope: 03-Clients
4. tags: [claude, outreach, clients, rag]
5. created: 2026-06-16
6. updated: 2026-08-12
7. ---
9. # CLAUDE: 03-Clients (scoped rules)
11. Governs everything under `03-Clients/`. Logged in root [[CLAUDE]]. Read this before
12. creating, editing, or enriching anything in this folder.
14. ## Folder layout: what lives where
15. ```
16. 03-Clients/
17. ├── CLAUDE-clients.md ← this file (the only .md at this level)
18. ├── partner-client-master-list.xml ← Partner Program master list (schema 3.0)
19. └── client-stubs/ ← ALL client stubs, one .md per client, flat
20. ```
21. - **Every client stub lives in `client-stubs/`.** Never at the `03-Clients/` root, never in
22. new subfolders. The root holds exactly two files: this one and the XML map.
23. - Dataview rollups elsewhere (tier notes, outreach notes, [[00-Index]]) query
24. `"03-Clients/client-stubs"`, so a stub saved anywhere else silently drops out of every
25. rollup. Keep the folder flat rather than "fixing" the queries.
27. ## The two layers, and which one you touch
28. 1. **Stubs (`client-stubs/*.md`):** the full per-client record. This is the write target
29. for enrichment and human-facing work.
30. 2. **Master list (`partner-client-master-list.xml`):** the client-centered RAG-chunked
31. census of the Partner Program, derived from the stubs plus Bitrix. It never holds
32. information that contradicts a stub. **When the two disagree, the stub wins** and the XML
33. gets corrected.
35. ## Stub anatomy: the live shape
36. Stubs are authored by `_create_stub()` in `07-Automation/weekly_partner_pipeline.py`.
37. `_templates/client-stub.md` mirrors it (plus a `plinth_id` slot, see Known drift). Build any
38. hand-made stub from that template so hand-made and driver-made stubs stay identical.
40. Sections, in order:
42. `frontmatter` → `# First Last` → `## Snapshot` → `## Order History` →
43. `## Research` (`### Company`, `### Person / LinkedIn`, `### Recent News & Signals`,
44. `### Sources`) → `## Human Notes` → `## Outreach Log`
46. `## Outreach Log` uses the six-column header shared by all stubs:
47. `| Date | Pipeline | Channel | Template | Outcome | Next step |`
49. There is **no `## Links` section**, and stubs carry **no tier or outreach wikilinks**.
50. Segmentation is frontmatter-driven: see below.
52. ### Frontmatter: universal keys
53. In this order (every key is on every stub except `plinth_id`; see Known drift):
55. `type` · `bitrix_id` · `plinth_id` · `first_name` · `last_name` · `email` ·
56. `user_group` · `user_group_correct` · `industry` · `company` · `phone` · `ltv` ·
57. `repeat_revenue` · `title` · `company_website` · `total_orders_count` ·
58. `last_order_date` · `source` · `last_modified` · `tags`
60. ### Conditional
61. - `outreach_pipelines`: present only once a client enters a Bitrix funnel. Keys:
62. `partner_outreach` (cat 24, Partner Tier Upgrade), `quarterly_checkin` (cat 36),
63. `winback` (cat 26). Each carries `stage`, `status`, `entered`, `last_touch`, `next_step`,
64. `next_date`. Omit the block entirely rather than writing an empty one; this mirrors
65. `<pipelines count="0" />` in the XML.
67. ### Do not add these
68. - `enrichment_status`, `email_one_status`, `email_two_status`: retired. Added 2026-06-16,
69. dropped by the 2026-07-23 rebuild; the driver has never written them since. 0 stubs.
70. - `updated`: an old `enrich_writeback.py` defect left it on some stubs of the live book (none in the sample). **The date key is
71. `last_modified`.** Normalize it away if you touch a stub that has both.
72. - `outreach_type`, `seniority`, `total_orders_usd`, `city`, `state`, `winback_done_before`,
73. `linkedin`, `company_linkedin`: legacy pre-2026-07 fields. 0 stubs.
75. ## Segmentation: which field to trust
76. - **`user_group_correct` is the tier.** Pipeline-computed. In the shipped sample:
77. Palladium 86 / Platinum 29 / Iridium 8 / Rhodium 7. Filter and roll up on this.
78. - **`user_group` is the raw Plinth store group and is blank on every sample stub (130 of
79. 130).** Never filter on it. It is kept only as a record of what Plinth reports.
80. - **Outreach play comes from `outreach_pipelines`**, not from a field.
82. ## Master-list contract (schema 3.0)
83. - **Root:** `<partner_client_master_list schema_version="3.0">`. One `<client>` element per
84. partner client = one self-contained retrieval chunk. Chunk at the `<client>` boundary;
85. each `<pipeline>` repeats `<client_ref>` so per-pipeline sub-chunks stay self-identifying.
86. - **Dual identifiers:** every `<client>` carries `<bitrix_id>` (CRM contact id) and
87. `<plinth_id>` (Plinth backend user id) alongside the stable `id` attribute (the RAG key).
88. A blank `<bitrix_id />` means the client isn't in the CRM yet.
89. - **Stable key:** `id` = Bitrix contact / tracker id for pipeline-mapped clients; for a
90. partner client not yet in Bitrix, `id` = `pl-<Plinth user_id>`. Never reuse or renumber.
91. Reconcile when the client later gets a Bitrix contact and enters a pipeline.
92. - **`<summary>` is auto-generated** from the other fields. Regenerate it whenever any field
93. of that client changes; never hand-edit it in isolation.
94. - **Stub pointers:** `<stub><relative_path>` is `/03-Clients/client-stubs/<file_name>`, and
95. the same path ends the `<summary>`. Rename or move a stub and both must be updated.
96. - **Coverage:** every partner client (Palladium and up) should have a `<client>` chunk
97. whether or not they're in a pipeline. The weekly `refresh-xml` stage adds missing chunks
98. and re-stamps the rest. Two Plinth accounts that are the same person (same name + email)
99. share one chunk; colleagues on a shared company mailbox each get their own. Non-partner
100. customers are not auto-added.
101. - **Sync duty:** any change to a client's identity, tier, or pipeline placement in a stub must
102. be mirrored into that client's chunk (fields + regenerated `<summary>`) in the same
103. change-set.
104. - **Validate the XML parses after any edit**
105. (`python3 -c "import xml.etree.ElementTree as ET; ET.parse(...)"`). A broken map is worse
106. than a stale one.
108. ## The scraping-dump contract
109. - Append scraped/enriched data **only** under `## Research`, inside the labelled subsections
110. (Company, Person / LinkedIn, Recent News & Signals, Sources).
111. - Every scraped claim gets a source URL under `### Sources`. **No source, no claim.**
112. - **Never** write into `## Human Notes`: that space is Matt's and Hazel's.
113. - Update frontmatter (`title`, `industry`, `company_website`, `phone`) when scraping confirms
114. or corrects it, and bump `last_modified`.
115. - If a field is unknown, leave the `[TBD]` marker. Do not invent it.
117. ## Linking
118. - Link to a stub by **bare name** (`[[Celia Iverson]]`), not by path. Bare names resolve
119. wherever the stub lives.
120. - Exception: if the target filename is ambiguous (the same basename exists in more than one
121. folder), use a path-qualified link with an alias, or you may resolve to the wrong file.
122. - Stubs do **not** link out to tier or outreach notes. Don't add such links; the rollups
123. read frontmatter.
125. ## Known drift: verified 2026-09-21
126. Flagged, not fixed. Read around these until they're resolved:
127. - **A stub's `## Order History` body can lag its frontmatter.** The driver writes the body
128. only when it creates the stub (`_create_stub()`); upgrades (`_upgrade_stub()`) refresh
129. frontmatter only (`ltv`, `repeat_revenue`, `total_orders_count`, `last_order_date`,
130. `user_group_correct`, `last_modified`). **Frontmatter is the live record;** trust it over
131. the body. Example: [[Celia Iverson]] shows a higher `ltv` in frontmatter than in her body.
132. - **The driver does not write `plinth_id` into stub frontmatter.** Stubs carry it only where
133. it was backfilled by hand (none of the sample stubs do). The census `<plinth_id>` is always
134. set, so resolve a stub's Plinth account through its XML chunk.
136. ## Ledger
137. Any change in this folder (stub edits, XML updates, moves) is a vault change: one batched
138. entry in [[LEDGER]] before the turn ends.