mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

SKILL.md

Language Markdown10.7 KB225 lines

skills/matt-easy-win-bitrix-triage/SKILL.md

---
name: matt-easy-win-bitrix-triage
description: >-
Identify Meridian Display Co. Bitrix24 leads that should close as Junk (not a viable lead:
promotional or notification email, spam, bad contact info, recruiting traffic, calls that never
got through the phone menu, or a prospect who never replied to our first reply) or Out Of Scope (a
real inquiry falling outside what Meridian can produce), and produce a reviewed worklist before
anything closes. Use whenever Matt or anyone at Meridian wants to junk leads, mark leads out of
scope, or clean up the lead queue: "move these to junk", "junk this one", "that's not even a
lead", "we can't make that", "clear the noise out of Bitrix". Also use to check whether a lead
already closed as Junk or Out Of Scope was filed correctly. Critical: Bitrix's internal stage ID
for Unconverted Lead is literally the string JUNK, and the button opening the close dialog is
itself labelled "Junk Lead", so these get confused constantly. Consult this skill before closing
any Meridian lead as either.
---
# Junk and Out Of Scope at Meridian Display Co.
Meridian closes leads with one of several terminal reasons. This skill covers the
two that pull a record *out* of the sales funnel rather than recording a sales
outcome: **Junk** and **Out Of Scope**.
Getting these right matters because both are routinely misfiled as Unconverted
Lead, which inflates the "opportunities we lost" number with records that were
never opportunities. A phone provider's billing notice counted as a lost sale is noise in
every report downstream.
Source of truth for the definitions: the team's lead-management SOP (the
internal guidance doc on managing leads in Bitrix24). Where this skill goes
beyond the SOP it is marked as practice rather than policy.
## Two naming traps, both involving the word "junk"
**Trap 1: the stage ID.** In Bitrix's data model the internal `stageId` for
**Unconverted Lead** is the literal string `JUNK`. The real Junk close reason is
stage `3`. Whenever you're reading raw field data or an API response, `JUNK`
means **Unconverted Lead**. Never reason from that string; use the table below.
**Trap 2: the button.** In the Bitrix UI, closing a lead means opening the last
stage in the top bar, **Complete Lead**, then pressing the red button labelled
**Junk Lead**. That button does not junk anything; it opens the close dialog
where you pick the actual reason. Pressing it is a step on the way to *every*
close, including Converted Lead. Someone reading over a colleague's shoulder, or
reading the SOP quickly, can easily come away thinking every close is a junking.
### Lead stage IDs (verified against the Bitrix UI)
| Close reason | `stageId` | `stageSemanticId` |
|---|---|---|
| **Junk** | `3` | `F` |
| **Out Of Scope** | `UC_R4TQ2N` | `F` |
| Reorder Completed | `1` | |
| Unconverted Lead | `JUNK` | `F` |
| Converted New Lead | `CONVERTED` | `S` |
Converted Lead has a separate ID that hasn't been identified yet; look it up
before writing to it rather than assuming it's `CONVERTED`.
Older triage output compounds the confusion: a board tag reading `[→Unconvert]`
has repeatedly been applied to records that are really Junk or Out Of Scope,
because whoever wrote it hit Trap 1. Treat those tags as unverified and classify
from the record itself.
### Reading current state: use `list_records`, not `pipeline_summary`
`pipeline_summary` collapses every closed status into one reported bucket,
`Unconverted Lead [JUNK]`, at a count far below reality: in one check it reported
412 against a true 3,870 in Junk and 216 in Out Of Scope. Anything built on it
will mis-sort.
`list_records` with an explicit `stage` reads each column correctly and at its
true count, and `get_record` returns a single lead's real `stageId`. Use those:
- `list_records(entity_type="lead", stage="3")`: everything in Junk
- `list_records(entity_type="lead", stage="UC_R4TQ2N")`: everything in Out Of Scope
- `get_record(entity_type="lead", record_id=...)`: one lead's actual close reason
`stage` wants the ID, not the label; passing "Out Of Scope" returns nothing
rather than erroring, which reads as "no such leads" and is easy to misread as
an empty column.
## Junk
Per the SOP: *the lead is not viable, either due to incorrect information or
promotional emails, disinterest.* In practice this covers:
- Promotional email, marketing blasts, newsletters
- System, service and billing notifications: expiring trials, delivery-failure
bounces, automated privacy notices
- Spam and irrelevant requests
- Vendor and agency solicitations, cold sales calls into our line
- Recruiting traffic: job applicants, application status chasers, staffing firms
- Records whose contact information is wrong or unusable
- **Phone calls that never got through the phone menu**, including our own
callbacks that land in another company's IVR
- **A prospect who never replied to our first reply**
That last one is the SOP's own criterion and it is easy to get backwards, so it
gets its own section.
### "Never replied to first reply" versus "went quiet"
These sound alike and close differently.
**Junk** is for a contact who never engaged at all. We replied; nothing ever came
back; there was never a conversation, a requirement, or a quote. There was no
opportunity here to lose.
**Unconverted Lead** is for a real prospect who *did* engage: we learned what
they wanted, we answered or quoted them, and then they went silent or went
elsewhere. Bitrix largely handles this on its own: a lead sitting in Quote Sent
for 16 business hours moves to No Reply, and 178 hours in No Reply moves it to
Unconverted Lead. Don't race that automation by junking a quoted lead.
The dividing question is whether a real exchange ever happened, not how long the
silence has run. A prospect who described a job in chat and received pricing is
Unconverted no matter how quiet they've gone; an address that received our reply
and never responded at all is Junk on the SOP's terms.
Where a record sits close to that line (a short call with an untranscribed
recording, or a single inbound with an ambiguous body), hold it rather than
guessing. Someone needs to listen to the call or read the thread.
Age and silence otherwise don't apply to Junk. A promotional email is junk the
moment it lands; there's no waiting period and no follow-up owed.
## Out Of Scope
Per the SOP: *the lead's request falls outside the company's services or
capabilities.* A real inquiry from a real prospect that we decline because we
can't produce what they need. Typical shapes:
- The spec isn't feasible in the material they need, such as an over-the-street banner
requiring a mesh openness we can't print
- Hardware we don't stock, such as an odd-length replacement bar
- Graphics for another manufacturer's frames; ours fit our own hardware
- A compliance or code requirement our substrate doesn't meet
- A service we don't offer at all, asked in good faith
Against Junk: a person genuinely wanted to buy something from us. Against
Unconverted Lead: we're the reason it ended, and not through any failure: we
gave them a straight answer and it was no.
Out Of Scope requires that we actually *can't* produce it. Declining on price,
lead time, or stock availability is a lost sale, not a capability limit, and
belongs in Unconverted Lead.
Like Junk, this doesn't age. Once we've declined on capability it's Out Of Scope
whether they replied or not.
## What is *not* covered here
Leave these alone; they belong to other close reasons or to follow-up:
- **A prospect quoted or answered who then went quiet**: Unconverted Lead, and
the automation usually gets there by itself.
- **Anything that became an order**: Converted Lead, or Reorder Completed for a
returning client rebuying prior work.
- **A client who asked for time**: that's Parked, not a close.
- **Anything where we owe them something.** This is the big one. A great deal of
what looks like a dead lead at Meridian is our own silence: a quote we promised
and never sent, a callback never made, a question never answered. That is an
open task, not a close of any kind. In particular, a lead cannot be junked for
"never replied to first reply" if our first reply was an autoresponder; the
SOP criterion assumes a human actually replied. If the ball was ours, route it
to follow-up and say so.
## Producing the worklist
Default output is a review table, not a write:
```
## Junk (N)
| Lead | Who / source | Which junk criterion it meets |
## Out Of Scope (N)
| Lead | Who | What they wanted | Why we can't make it |
## Hold: ask Matt (N)
| Lead | Who | What's unclear |
```
Name the specific criterion in the Junk table rather than writing "not a lead".
"Promotional email", "IVR, never reached us", "no reply to first human reply"
are checkable; a bare assertion isn't.
Put anything ambiguous in Hold with the specific question. The cases worth
naming rather than guessing:
- A short call with a recording nobody has transcribed: it may be a real
inquiry. Don't call it a dead call until someone has heard it.
- A decline that was really about price, lead time or stock: Unconverted, not
Out Of Scope.
- A lead whose only outbound was an autoresponder: our silence, not theirs.
- Internal, test, or staff-created records: flag, don't close.
Also flag, rather than silently correct, any lead whose existing close reason or
title tag disagrees with the evidence.
## Writing back
Closing leads is a bulk write to production CRM. Confirm the specific list
before anything executes, and re-verify current state at that moment.
Worklists drawn from a triage board go stale within a day or two as the team
works the queue, so drop anything already closed rather than re-closing it.
Two things to establish before trusting `set_lead_fields` for this:
**Does the write land on the right stage?** Unverified. Reading works, so the
write path is plausible, but the failure mode that matters is silent: a write
accepted while the lead quietly lands in Unconverted Lead, recreating at scale
the exact problem this skill exists to prevent. Test on one throwaway lead, then
read it back with `get_record` and confirm `stageId` is `3` or `UC_R4TQ2N`. The
read-back is the check; a successful-looking write response is not evidence.
**Do stage qualifiers block it?** The SOP notes that certain stages are gated:
Bitrix refuses to move a lead there until required fields are filled, once per
lead. Whether those gates apply to these two close reasons, and whether the API
enforces or silently bypasses them, is unconfirmed. A refusal is the good case;
a bypass that skips required data is worse than a manual close.
If either check fails, deliver the worklist and let Matt apply the closes
through the UI: **Complete Lead** → red **Junk Lead** button → pick the reason →
**Save**. It takes a few seconds per lead and is not worth a risky automation.