# Leads → Signal grade (S / A / B / C / Excluded)

## What it does

Every lead carries one **signal grade**: how strong this person's buying signal is, read from the
CRM's own records. The Leads list's **Filters** panel opens with a **Signal grade** row of chips,
**S · A · B · C · Excluded**, each with how many of the viewer's leads it holds, and a one-line
legend.

Founder, 2026-10-12:

| Grade | Means |
|---|---|
| **S** | Booked or bought a property with us **in the last 6 months** |
| **A** | No recent booking, but a lot is known and the signal is strong and current |
| **B** | Some signal, not yet clear |
| **C** | Weak or no signal |
| **Excluded** | Staff, agents, fake leads, someone who told us to stop, a refund or complaint |

A lead who booked **more than 6 months ago** is graded on what they are doing **now**, like anybody
else.

**Not the lead DISTRIBUTION buckets.** `lead_tiers` holds "Bucket A/B/C" for round-robin assignment
(`Src\LeadDistribution\LeadTier`). This grade is unrelated to them, so the code, the table and the
filter all say *signal grade* and never tier or bucket. The filter key is `signal_grade`, not bare
`signal`, because the Readiness row in the same panel already calls its yellow state "signal".

## How it works

### The ladder: the first rule that matches wins

[`Src\Lead\Support\SignalGrade`](/src/Lead/Support/SignalGrade.php) is an evidence **ladder**, not a
score. The handbook forbids scores ([sales-insights.md](sales-insights.md)). Each grade is stored with
the rule that decided it (`reason`), the signal behind it (`signal_key`) and that signal's date
(`reason_at`). The codes and their plain-word meanings are constants on
[`LeadSignalGrade`](/src/Lead/LeadSignalGrade.php) (`REASON_*` / `REASONS`, `SIGNAL_*` / `SIGNALS`).
They are kept for diagnosis; the list does not print them yet.

| Step | Rule | `reason` |
|---|---|---|
| Excluded | Any of: a `do_not_contact` or `dispute` stance still in force (`dnc` / `dispute`, see below); `is_staff`; a company e-mail (`INTERNAL_EMAIL_DOMAINS`); a test or look-alike domain (`TEST_EMAIL_DOMAIN_PATTERN`: example., test., testing., propertylab…); an agent or fake **a person confirmed** (`agent_verdict` / `fake_verdict` = yes). The **AI's** guesses exclude only in two cases: an **agent** (never the softer "agent-linked") who has not paid, booked or shown any strong signal; a **fake** who shows no activity at all | `staff` / `agent` / `fake` |
| **S** | A booking that is live or completed (`bookings.status` 1 / 3), dated (`booking_date`, else `created_at`) within **6 months**, by whole days (`subMonthsNoOverflow`) | `booked` |
| **A** | A strong **record** within **180 days**, or strong **words** within **90 days**. Words means a price question, a poll "yes", an unresolved objection, or a booking that fell through (`STRONG_SAID`) | `strong` |
| **A** | A strong signal within a **year**, while the lead **did something themselves** in the last **90 days** (`SELF_STARTED`; WhatsApp counts only on 2+ days) | `strong` |
| **A** | An AI reading of strong interest within 90 days, **plus** their own two-way activity in 90 days (WhatsApp on 2+ days, or the portal) | `ai_lift` |
| **A** | Active in **3+ different ways** in 90 days, from: WhatsApp on 2+ days · a call ≥ 60 s or an AI call they spoke on · the portal · 90+ webinar minutes inside the window · a WhatsApp link tap | `broad` |
| **B** | A strong signal within a year that has gone quiet | `strong_stale` |
| **B** | A medium signal within a year | `medium` |
| **C** | Nothing within a year (the reason names the newest thing we ever had) / nothing at all | `stale` / `none` |

**Strong** (`SignalGrade::STRONG`):
- an open deal: engagement status 1–5, dated by its own `last_activity_at`;
- paid a **property** membership (any code not in `Membership::AI_CODES`) or a project fee;
- opened a checkout without paying, in the last 90 days, excluding AI-course checkouts;
- priced a property: a property analysis, a Property Match with 3+ answers, the customer's own rental estimate (`booking_id` null), a wealth plan with a goal, or the units tab opened;
- a financial profile: an FPA, a WhoPay report, or a signed consent;
- a 1-to-1 Zoom that happened;
- asked about price on WhatsApp;
- a booking that fell through;
- said yes to the "considering buying" poll;
- an unresolved objection.

**Medium** (`SignalGrade::MEDIUM`):
- replied on WhatsApp;
- a call ≥ 60 s;
- spoke on an AI call;
- used the portal **themselves**: an activity-log row counts only when its actor is the lead's own user, or an account merged into it (`users.merged_into_user_id`), never a colleague acting for them;
- 90+ webinar minutes, or 2+ webinars (joins under 10 minutes do not count);
- answered a poll;
- tapped a WhatsApp link;
- an **AI-course** payment;
- a past deal;
- an AI reading of strong interest.

Every threshold is a named constant on `SignalGrade`: `S_MONTHS`, `ACTIVE_DAYS`,
`STRONG_FRESH_DAYS`, `MEDIUM_DAYS`, `WEBINAR_SECONDS`, `WEBINAR_JOIN_SECONDS`, `WEBINARS_MIN`,
`CALL_SECONDS`, `PROPERTY_MATCH_ANSWERS`, `BROAD_KINDS`, `WHATSAPP_DAYS` and `TEMPLATE_LEADS`.

### Why these choices: each one fixes a misgrade found on production data

The rules were run against a full local copy of production on 2026-10-12. About 15 leads per grade
were sampled, and every pattern found was sized over all 13,037 leads. Each choice below fixes
something that sampling caught.

- **Webinar attendance alone never keeps a lead current.** A member who paid long ago and still
  watches is a learner, not a buyer. Only what the person did themselves (`SELF_STARTED`)
  refreshes an old strong record.
- **A join under 10 minutes is not attendance.** 0-second joins exist. Counting them kept 105 B
  leads off C, for example "2 webinars" from 23 minutes in total.
- **One WhatsApp message is not a thread.** "Any old record plus one message" made 26 leads A.
- **Strong evidence ages out after a year.** Without that, a booking that fell through in 2022
  ranked B while a 2022 completed buyer ranked C. Many legacy bookings carry the placeholder dates
  2020/2021/2022-01-01.
- **A live booking is dated by its booking date,** so a booking older than 6 months is judged on
  current signals, as the founder asked. 50 of 84 "Active" bookings already have their engagement
  at Completed: the status is not maintained.
- **An AI-course payment, or an AI-course checkout, is not property intent** (`Membership::AI_CODES`).
- **A colleague's rental estimate against a booking is after-sales.** It is not the customer pricing
  a property, and it had put 15 past buyers in A.
- **A registration is not activity.** Many `lead_funnels.registered_at` values are bulk-import stamps
  (536 in one minute on 2026-07-19). Imported wealth plans (`petav2_id`) count only when they were
  opened after the import.
- **Engagement dates before 2026-07-19 come from an import.** An open deal is dated by its own
  `last_activity_at`. A past deal is undated: it can mark a lead as C-with-history, never as current.
- **"booking fee" is not a price question.** It mostly appears in payment confirmations. Inbound
  bodies sent word for word by 5+ leads (prefilled buttons) are ignored as templates.
- **Words decay faster than records.** A poll tick from 5 months ago is not A on its own.
- **An AI guess alone does not hide a customer.** A lead who paid RM2,388 on 16 Sep and wrote 19
  WhatsApp messages had been "Not graded" because the enrichment guessed "agent". A "fake" with
  4,073 webinar minutes is clearly a person.
- **Company and test e-mails are internal.** Non-staff leads on `propertylab.*`, `example.com` and
  `test.com` included test records created by staff.
- **Nothing dated after "now" is read.** A mistyped future booking, payment or consent date cannot
  hold a lead up. The dates a person types (bookings, deals, payments, consents, plans) are cut in SQL,
  so an earlier real date still counts; any other row dated after now is dropped as it loads.
- **A colleague's action is not the customer's.** On the copy, 19 of the 25 WhoPay report saves and
  the only FPA-answers correction were made by staff FOR the customer, under the same activity-log
  types the portal writes. Counted as the customer's, they would lift a quiet lead (C → B, B → A).

### What they SAID: the three "said" grades and do-not-contact (owner, 2026-10-21; built 2026-10-22)

The ladder above reads what a lead DID. The owner's complaint: a person who told the AI "not
interested" stayed B for a year, because picking up the call is a medium signal. So every
conversation now also records what they **said** — [`LeadStance`](/src/Lead/LeadStance.php), table
`lead_stances`, one row per conversation: `stance` (wants_to_buy · exploring · **not_now · not_a_buyer
· not_interested · do_not_contact**), `persona`, the `quote` in their words, the `channel`
(ai_call · whatsapp · phone · f2f · zoom · poll · staff), `said_at`, and `expires_at` — how long it
holds (`STANCES[...]['months']`: not now 3 months or the date they gave, not a buyer and not interested
12 months, do not contact for good). Written by [`StanceRecorder`](/src/Lead/Support/StanceRecorder.php):
`fromAiCall()` after every AI call our own reading gave a `stance` to (`AiCallAftermath::analyzed()`),
`fromWhatsAppOptOut()` on a STOP keyword (`ProcessInboundWhatsAppWebhook`), `fromStaff()` from the AI
Rounds slide-out ("Correct"), `fromConversation()` after a **phone call / showroom visit / Zoom meeting**
is transcribed (one small Sonnet reading of its own, [`ReadConversationStance`](/app/Jobs/Conversation/ReadConversationStance.php),
prompt `lead_stance_reading`, queued from `ConversationAutomationService::queueFor()` — not a field of
the big conversation analysis, whose prompt production overrides), and `fromPoll()` for the webinar
poll **"最近有没有考虑买房？" answered No** ([`WebinarBuyingPlanSync`](/src/Lead/Services/WebinarBuyingPlanSync.php),
after every poll import and hourly) — and each one regrades that lead **at once** (`SignalGrade::persist()`),
not at the next hourly run. A recording moved to another lead takes its stance along (`relink()`).

How the ladder uses it (`SignalGrade::gradeOne()`, right after the S rule):
- the newest negative stance still in force (`signals()` loads one per lead) takes the lead off the
  ladder — **`GRADE_NOT_NOW` (5, key `l`), `GRADE_NOT_A_BUYER` (6, `o`), `GRADE_NOT_INTERESTED` (7,
  `n`)**, `reason = said`, `signal_key = said_*`;
- **unless they did something THEMSELVES since** (`selfStartedAt()` newer than `said_at` — a price
  question after a "no" is a change of mind: actions beat words);
- a **booking in S_MONTHS still wins** (S comes first);
- **do_not_contact** and **dispute** (a refund request or complaint, owner 2026-11-05) join the
  exclusions (`REASON_DNC`, `REASON_DISPUTE`): nothing the lead does lifts them, and neither does a later
  "not now" read from a call. A colleague's newer stance does ("Correct"); only a leader may lift a
  stop-all that way. A colleague's newer word lifts a "said no" too.

### What Excluded and "said no" actually stop (owner, 2026-11-05)

The grade alone stops nothing outside this page's lists, so [`ContactStop`](/src/Lead/Services/ContactStop.php)
pulls the real switches when `StanceRecorder` writes a stop-all stance, from any channel:

| | AI call | Other automated WhatsApp, email, SMS, funnel voice | A colleague typing on WhatsApp |
|---|---|---|---|
| **Do not contact** | Refused | Stopped | Stopped |
| **Refund or complaint** | Refused | Stopped | Still goes out: someone has to handle it |
| **Agent, fake** | No AI Rounds call | Carries on | Carries on |
| **Not now, not a buyer, not interested** | No bulk or scheduled AI Rounds call. A person's press, a new registration and their own "call me back" tap still ring | Carries on | Carries on |

- The switch is `revenue_contact_policies`, which [`ContactSuppression`](/src/RevenueJourney/Operations/ContactSuppression.php)
  reads at send time: `is_do_not_contact` for do not contact, `hold_reason = ContactPolicy::HOLD_DISPUTE` for a
  refund or complaint. Stopping also cancels what is queued, opts every WhatsApp contact of the lead out, and
  (do not contact only) puts the number on the AI do-not-call list.
- **Staff are never stopped** (`reason = staff`): they ring themselves to test.
- **Not covered:** a colleague dialling by hand, posts inside a WhatsApp group, Messenger and LINE, and login codes
  and receipts.
- **The WhatsApp STOP words** are in `config/whatsapp.php`. A word that can sit inside an ordinary sentence goes in
  `opt_out_exact_keywords`, matched only as the whole message: `退出` as a contained keyword opted out a real buyer who
  wrote "太啰嗦的话我会提早退出".
- **Applying a reviewed list:** `php artisan leads:apply-contact-review` reads `lead_id,action,message_id` (actions:
  `agent`, `do_not_contact`, `dispute`, `not_interested`, `not_now`, `no_call`, `false_opt_out`). It lists by default, and
  `--actor=<e-mail> --apply` writes. It skips an agent who paid us or whom a person already judged, and a "not now" that has
  already run out. The list of 2026-11-04 holds only ids, in `database/data/lead_contact_review/`.

The stored numbers 5–7 sit above C only because the column is unsigned; `LeadSignalGrade::ranks()`
is the order (S > A > B > C > not now > not a buyer > not interested > not graded) for anything that
sorts by grade. The Leads list filter and its counts pick the new keys up from `GRADES` unchanged.
A poll **Yes** is not a stance: it is the lead's own dated act (`poll_buy_yes`), so a later Yes outranks
an earlier No by the actions-beat-words rule above without a row being written.

### The cache and when it refreshes

- `lead_signal_grades` holds one row per lead. `grade` is the rank: 4 S, 3 A, 2 B, 1 C, 0 not graded — plus 5 not now, 6 not a buyer, 7 not interested (see *What they SAID*).
- **Hourly**, inside `leads:refresh-readiness`, as a second pass after the readiness cache.
  - It is fail-soft: a grading error is logged and never holds readiness back.
  - Then `LeadSignalGradeRepository::prune()` drops the rows of leads that no longer exist.
  - Grading 13k leads takes about 3 s; the whole command takes about 10 s.
- **It is not regraded when an AI channel reading is saved.** The grade does not read
  `lead_channel_insights`. Its AI signal comes from the analyses stored on calls, Zoom meetings and AI
  calls.
- **Merge:** the loser's row is deleted (`IdentityChildMap`: SPECIAL) and the winner is regraded on
  the next run. **Purge:** the row is deleted by lead.
- A lead created since the last run has **no row yet**, and matches no chip until the next hour.
- **Right after the deploy that creates the table, the cache is empty:** every chip shows 0 until the
  first hourly run. Run `php artisan leads:refresh-readiness` once after `migrate`.

### The filter and its counts

- `LeadQueryRequest::filterSignalGrade`: `signal_grade[]=s|a|b|c|x`, an EXISTS on the cache.
- `LeadsController@index` sends `signalOptions` (`LeadSignalGrade::options()`, with the window
  filled in from `S_MONTHS`) and `signalCounts`. The counts are one GROUP BY on the **same** cache,
  scoped by `LeadVisibility`, so a count can never disagree with what clicking the chip returns.
- `LeadFilterBar.vue` draws the **Signal grade** row first in the Filters panel. Its legend is built
  from the server's own words, and each chip shows its meaning on hover.

### Sizes on the production copy (2026-10-12)

| S | A | B | C | Not graded |
|---|---|---|---|---|
| 78 | 292 | 2,552 | 9,958 | 162 |

**A, by the signal that decided it:**

| Signal | Leads |
|---|---|
| 1-to-1 Zoom | 66 |
| Financial profile | 61 |
| Priced a property | 59 |
| Open deal | 31 |
| Property payment | 22 |
| Active in 3+ ways | 20 |
| Price question | 17 |
| Checkout | 5 |
| AI lift | 5 |
| Fell-through booking | 4 |
| Objection | 2 |

**Not graded:** agent 114 · staff / company / test 40 · fake 8.

### What the data cannot say yet

- **"Will buy within 3 months"** has no structured field anywhere. The closest are the
  "considering buying" poll (Apr–May 2026 only) and the AI caller's `looking_now`.
- **Unresolved objections** exist for only a handful of leads (`zoom_objection_records`).
- Portal views, lessons, Property Match, AI calls and rental estimates only started being recorded
  between July and September 2026, so a grade leaning on them favours recent leads.
- `ai_voice_calls.outcome` is never written, so only `status` (completed) + `lead_spoke` are used.
- **Not handled yet:** 8 open engagements bulk-created in one minute on 2026-08-02 from June payments
  read as open deals. One of those payments was refunded.

## Related files

- **Rules**: [src/Lead/Support/SignalGrade.php](/src/Lead/Support/SignalGrade.php)
- **Model + constants**: [src/Lead/LeadSignalGrade.php](/src/Lead/LeadSignalGrade.php) (`GRADES`, `REASON_*`, `SIGNAL_*`, `INTERNAL_EMAIL_DOMAINS`, `TEST_EMAIL_DOMAIN_PATTERN`, `options()`) · [src/Membership/Membership.php](/src/Membership/Membership.php) (`AI_CODES`)
- **Repository**: [src/Lead/Repositories/LeadSignalGradeRepository.php](/src/Lead/Repositories/LeadSignalGradeRepository.php)
- **Migration**: [database/migrations/2026_10_12_100000_create_lead_signal_grades.php](/database/migrations/2026_10_12_100000_create_lead_signal_grades.php)
- **Refresh**: [app/Console/Commands/RefreshLeadReadiness.php](/app/Console/Commands/RefreshLeadReadiness.php)
- **Filter / counts**: [app/Http/Requests/Manage/Leads/LeadQueryRequest.php](/app/Http/Requests/Manage/Leads/LeadQueryRequest.php) · [app/Http/Controllers/Manage/Leads/LeadsController.php](/app/Http/Controllers/Manage/Leads/LeadsController.php)
- **UI**: [resources/js/Pages/Manage/Leads/Partials/LeadFilterBar.vue](/resources/js/Pages/Manage/Leads/Partials/LeadFilterBar.vue) · [resources/js/Pages/Manage/Leads/Index.vue](/resources/js/Pages/Manage/Leads/Index.vue)
- **Shared definitions reused**: [MessageEngagement::joins()](/src/Lead/Support/MessageEngagement.php) (a real 1:1 WhatsApp message) · [LeadQuality](/src/Lead/Support/LeadQuality.php) (agent / fake state) · [ZoomMeeting::applyHappened](/src/Zoom/ZoomMeeting.php)
- **Merge / purge**: [src/Lead/Support/IdentityChildMap.php](/src/Lead/Support/IdentityChildMap.php) · [src/Lead/Repositories/LeadRepository.php](/src/Lead/Repositories/LeadRepository.php)
- **What they said**: [src/Lead/LeadStance.php](/src/Lead/LeadStance.php) · [src/Lead/Support/StanceRecorder.php](/src/Lead/Support/StanceRecorder.php) · [src/Lead/Repositories/LeadStanceRepository.php](/src/Lead/Repositories/LeadStanceRepository.php) · migration `2026_10_22_120000_create_lead_loan_profiles_and_lead_stances_tables.php`
- **Tests**: [tests/Feature/Lead/SignalGradeTest.php](/tests/Feature/Lead/SignalGradeTest.php) · [LeadFilterBar.test.js](/resources/js/Pages/Manage/Leads/Partials/LeadFilterBar.test.js)
