SKILL.md

skills/bitrix-pipeline-board/SKILL.md

1. ---
2. name: bitrix-pipeline-board
3. description: >-
4. Build an interactive visual board of the Meridian Display Co. open lead pipeline, broken down by
5. owner and stage, with a live clickable link to every lead in Bitrix. Use this skill whenever Matt
6. asks to see, chart, visualize, or break down the pipeline by who owns what and what stage things
7. are in, with phrasings like "chart the open leads by owner and stage", "who owns what in the
8. pipeline", "show me the pipeline board", "lead distribution by rep", "visualize the open leads",
9. "board of open leads with links", or any time he wants the open lead pipeline turned into
10. something he can look at and click through rather than a flat count. Also trigger when he asks
11. "where are all our open leads sitting" or wants to spot owner concentration, orphaned leads, or a
12. parked backlog. Defaults to leads; can run the same board on deals if asked.
13. ---
15. # Bitrix Pipeline Board
17. Turn the open Bitrix pipeline into one interactive board: a stacked bar of leads-per-owner, owner and stage filters, and a table where every row links straight to the lead in Bitrix. End with the analytical read, not just the picture.
19. ## Constants
21. - **Bitrix lead link base:** `https://meridian.bitrix24.example/crm/lead/details/{id}/`
22. - **Deal link base** (if running on deals): `https://meridian.bitrix24.example/crm/deal/details/{id}/`
23. - **Active CS / sales owners** (for orphan detection): Matt Guerra, Hazel Okafor, Marco Ibáñez, Ines Carvalho, Theo Bassett.
24. - **Known former owner to flag:** Owen Pryce. Any lead still assigned to him is orphaned, so surface it.
26. ## Workflow
28. ### 1. Pull the stage map and counts
29. Load the Bitrix tools (`tool_search` for "bitrix pipeline summary leads stages"), then call `pipeline_summary` with `entity_type=lead`, `scope=open`. This returns every stage with its human name, internal stage ID, and exact count. The grand total is the headline number. Don't hardcode stage IDs from this skill. Read them fresh each run, since stages get renamed and added.
31. ### 2. Scale guard: check the total before enumerating
32. This board enumerates every record and links every row, which only works at lead scale (hundreds). Look at the `pipeline_summary` grand total first. If it's more than ~400 records, or spans multiple pipelines/categories, **do not fan out and render every row**: you'll trigger dozens of paginated pulls and an unusable table. Instead either (a) ask which pipeline/stage to scope to, or (b) drop to counts-only mode: build the owner×stage bar from `pipeline_summary` called once per owner (`assigned_to=<name>`), with no per-record table or links. The open lead funnel normally sits in the hundreds, so leads almost always take the full path; deals usually do not (see the deal section).
34. ### 3. Pull the records in each non-zero stage
35. For every stage with count > 0, call `list_records` with `entity_type=lead`, `stage=<stage ID>`, `limit=50`. The summary line for each lead exposes the owner as `@Owner Name`; that is where the assignee comes from. Parse out lead ID (the `[#####]`), title, and owner.
37. Reconcile: the sum of your per-stage pulls must equal the `pipeline_summary` total. State the arithmetic so it's checkable.
39. **50-cap caveat:** stage-filtered `list_records` (no date filter) caps at 50 rows. If `pipeline_summary` shows a stage over 50, that one pull truncates. Work around it by splitting that stage with `created_from`/`created_to` date windows (date-filtered queries auto-paginate to 200) and stitching the results, or by pulling that stage per-owner. Flag it if you hit it.
41. ### 4. Bucket each lead into a stage group
42. Three groups drive the chart and the row badges. Classify by stage name, not a frozen ID list:
43. - **intake**: pre-work stages: New/Unassigned, Assigned.
44. - **parked**: Parked, and any holding / "need to sort" stage.
45. - **active**: everything else open (First Reply, Client Replied, Need Follow Up, Waiting For Client, No Reply, Reorder in Progress, Consultation Scheduled, Quote Sent, Quote Approved, etc.).
47. ### 5. Render the board
48. Load the visualizer guidance (`read_me` with modules `["interactive","chart"]`), then build the widget using `references/widget-template.html` as the scaffold. Drop the parsed leads into the `D` array and let the script compute the per-owner stacked bar and build the filterable table. The chart is a horizontal stacked bar (owners on the y-axis, intake/active/parked segments). The table row links each lead ID to the Bitrix base + id.
50. ### 6. Give the read, not just the chart
51. A board nobody acts on is wallpaper. After the widget, surface in prose whatever is actually true this run:
52. - **Owner concentration**: if one rep holds a lopsided share (e.g. >60%), name it and the risk (bottleneck / single point of failure if they're out).
53. - **Orphaned leads**: any lead owned by a former employee (Owen Pryce) or sitting unassigned; recommend reassign or kill.
54. - **Parked backlog**: how big the parked block is relative to active; if parked is the largest single bucket, flag it for a sweep (dead vs. neglected).
55. - **Thin back end**: call out if the late stages (Quote Sent / Quote Approved) are near-empty while replies pile up earlier.
57. Keep it to what the numbers support. Don't manufacture a finding that isn't there.
59. ## Running on deals: read this first
60. Deals are NOT a bigger version of leads. The open deal set is far larger and spans many separate pipelines/categories (orders, production, fulfillment, LinkedIn outreach, partner outreach, etc.), and includes terminal-ish stages like "Order Delivered" that hold large numbers of fulfilled orders and are not "in progress" in any pipeline sense. The lead approach (enumerate every record, link every row, bucket into intake/active/parked) does not transfer.
62. So for deals:
63. - **Never enumerate all open deals.** The scale guard in step 2 applies hard here.
64. - **Make Matt scope it** to one pipeline/category or a specific stage before building anything ("which deal pipeline: orders, the sales/LinkedIn funnel, production?"). A board only makes sense within one funnel.
65. - Once scoped to a single pipeline of manageable size, run the same flow with `entity_type=deal`, the deal link base, and an intake/active/parked (or stage-appropriate) classification for *that* pipeline's stages.
66. - If the scoped set is still large or links aren't needed, use counts-only mode: `pipeline_summary(deal, open)` for the stage counts, called per owner for the owner split, rendered as the stacked bar with no per-record table.
68. `scope=open` is still required (won/lost are out of scope).