# PLAN — Two-round AI nurture for signal-grade B leads (2026-10-15)

**Status: SUPERSEDED (2026-10-15).** The owner chose a manual table instead of this automatic flow — every call a
button the account manager presses, on its own My Workspace tab. What was built: [ai-rounds.md](/docs/modules_handbook/manage/my-work/ai-rounds.md).
This file is kept for the facts in section 2 and the reasoning. Sibling of
[signal-grade.md](/docs/modules_handbook/manage/leads/signal-grade.md); touches the AI caller
([voice-agent](/docs/modules_handbook/shared/voice-agent/readMe.md)), My Workspace
([my-work](/docs/modules_handbook/manage/my-work/readMe.md)) and the lead reps
([leads readMe](/docs/modules_handbook/manage/leads/readMe.md)).

## 1. The ask (the boss, 2026-10-15)

> **Grade B — some signal, not yet clear:** run two AI rounds. Learn their problem, send them a
> solution, book an appointment; once booked, or once they turn keen, hand them to sales.

1. **AI call 1** asks the lead about their problem.
2. **AI drafts an answer**; the lead's sales person **checks and approves** it.
3. **AI call 2** explains the approved answer and **asks for an appointment with a human**.
4. **Booked, or keen → handed to sales.**

Plus: it must follow the grade as it moves (a new lead graded B, a lead rising into B, a lead
leaving B), and each lead's REP / account manager must be able to see, approve, call and update.

## 2. Facts this plan rests on (checked in code and on production, 2026-10-15)

**The leads**
- Production now: S 66 · A 297 · **B 3,030** · C 9,506 · not graded 164. Of the B leads, **2,529
  have a phone**, 288 were ever AI-called, 156 spoke on one.
- What made them B: webinar 90+ min 1,438 · WhatsApp reply 1,150 · portal 68 · call ≥ 60 s 67 ·
  2+ webinars 63 · spoke on an AI call 53 · WhatsApp price question 50 · others < 50.
- **Every B lead has an account manager and an active REP**, and all 3,030 sit with **5 account
  managers** (49 to 763 each, about 600 on average). Human approval is the bottleneck, not cost.

**The grade cannot see itself change**
- `LeadSignalGradeRepository::sync()` is a blind upsert: no previous grade, no history, no event.
  `leads:refresh-readiness` regrades every lead hourly (about 70 s on production). A new lead is
  first graded only by that run. A grade also moves with time alone (a strong signal ageing past
  180 days turns A into B) — only the hourly sweep sees that.

**Who is the lead's person**
- **Account manager** (`leads.assigned_admin_id`): exactly one per lead, set by round robin, by hand,
  by the funnel hand-off or by the Top-REP move; history in `lead_assignments`. Funnel work in My
  Workspace → Sales steps goes to the account manager.
- **REPs** (`lead_reps`): any number — the account manager (always a rep), closers, anyone handed a
  task, anyone who called / Zoomed / WhatsApped, anyone added by hand. A rep gets visibility and a
  place in the Top-REP ranking, but work only as an assigned task.
- Sales agents and leaders hold **view-leads-all** on this install (migration 2026-10-05), so
  everyone can already open every lead and every colleague's board. The design decides who gets
  the WORK, not who can see.

**What the AI caller already does**
- **Call 1 is nearly ready:** the AI-profile "Stage 1 Needs" preset already asks and extracts
  `looking_now`, `buy_intent`, `buying_timeline`, `current_problem`, `help_needed`, `must_haves`,
  `budget` (`StageOneNeedsQuestions`).
- **Call 2 is nearly ready:** a profile with the `appointment` goal proposes times and extracts
  `appointment_time`, `appointment_booked`, `wants_human`, `main_objection`, `callback_time`. A call
  can carry long per-lead text as a dynamic variable (the Appointment Engine sends 12,000-char
  `script` / `knowledge`); the repeat-call precedent `is_repeat_call` + `previous_summary` exists.
- **Missing:** nothing drafts a solution from an AI call's transcript, and the CRM has no
  "human approves, then the AI calls again" step.
- **Booking:** in the CRM a time the lead agrees to becomes a **pending appointment request** and a
  `confirm_appointment` task for a human (`FunnelAppointmentRequest`), never an automatic booking.
  Only the Appointment Engine books outright.
- **Guards** every call already passes (`PlaceAiVoiceCall`): profile callable → valid phone →
  ContactSuppression → do-not-call list / WhatsApp-blocked → **daily budget (US$15, shared by all
  AI calls)** → call window. **A WhatsApp STOP does not stop AI calls** today.
- Cost measured on production: US$23.78 for 255 connected minutes ≈ **US$0.09 / minute**.

**Patterns to reuse**
- State machine: the funnel Journey engine's *pattern* (transition table with only-from guards,
  `JourneyRule` interface, 5-minute scanner on `next_check_at`, fail-soft `guard()` hooks). Its table
  is per funnel, so not the table itself.
- Approval: `LeadActionProposal` / `ConversationActionPlan` (AI draft → a human edits and approves →
  frozen, stamped who and when).
- Work queue: `LeadActionItem` in My Workspace → **Sales steps** via a `responsibility_queue`.
- Switches: an env master switch plus a DB `Setting` that is on only when exactly `'1'`.

## 3. The design

### 3.1 Grade changes become events (needed first, useful on its own)

- `sync()` reads each batch's current grades under lock before the upsert, and writes every change
  to a new `lead_signal_grade_changes` table (`lead_id`, `from_grade`, `to_grade`, `changed_at`).
- After commit (the `guard()` style: fail-soft, never breaks the grading run) it raises
  `enteredGrade(lead, B)` / `leftGrade(lead, B, to)` hooks.
- A new lead is graded a few minutes after creation (queued like the round-robin job), not after up
  to an hour, through the same `sync()`.
- **Launch:** the history table is seeded from today's rows first, so the 3,030 existing B leads do
  NOT all look "just entered" at once. They join through the backlog intake (3.3).
- The grade is shown on the lead page, the lead modal and as a Leads-list column (today it is only
  a filter), so the REP / account manager sees why a lead is in the flow.

### 3.2 One nurture per lead: `lead_ai_nurtures`

A small state machine of its own, built on the funnel Journey pattern:

| Step | Means | Next |
|---|---|---|
| `queued` | enrolled, waiting for today's intake slot and the call window | call 1 |
| `call1` | discovery call placed / retrying (no answer → up to N tries, days apart) | answered → `drafting`; never reached → ends `unreachable` |
| `drafting` | the AI is writing the answer from call 1 | → `approval` |
| `approval` | waiting for the account manager to approve, edit or decide | approved → `call2`; "I'll call myself" → hand-over; "not suitable" → ends |
| `call2` | the solution call placed / retrying | appointment / keen → hand-over; not interested → ends |
| `handed_over` | a human task exists; the flow is done | — |
| `ended` | stopped, with a reason | — |

Every row keeps: the account manager at enrolment, both call ids, the **approved solution text** (+
the AI's original draft, who approved, when), retry counts, `next_check_at`, `ended_reason`.
Ending reasons: `appointment`, `keen`, `self_call`, `not_suitable`, `not_interested`,
`unreachable`, `opted_out`, `left_grade`, `approval_expired`, `stopped_by_staff`.

A 5-minute scanner (like `funnel-journey:advance`) moves due rows; the AI-call aftermath gets one
hook line (as `aiCallAnswered` today) so a finished call moves its nurture at once.

### 3.3 Who enters, and how fast

**Eligible:** grade B · a phone · not a WhatsApp opt-out / blocked / do-not-call / suppressed · not
in an active funnel Journey or with an open sales task (no double contact) · no AI call in the last
N days · not already nurtured in the last N days.

**Entering:**
- **Live:** a lead that *enters* B (new or upgraded) is queued.
- **Backlog:** the 3,030 existing B leads are queued by a **daily intake cap** (e.g. 20–50 a day),
  freshest signal first. `--dry-run` shows who would go next.

**Leaving B while in the flow:**
- **Up to A / S** → they are keen: stop and hand over (3.6).
- **Down to C** → carry on: the nurture's own calls are what should lift them.
- **Not graded** (marked agent / fake / staff) → stop at once.

### 3.4 Call 1 — discovery

A dedicated AI profile ("B nurture · discovery") with the Stage 1 Needs fields and a short brief:
introduce, ask what is holding them back, listen, no selling. Its own **caller ID**, **call window**
and **follow-up WhatsApp number** (the per-profile settings shipped 2026-10-13). After it:
- lead spoke and gave a problem → `drafting`;
- not interested / wrong person / asked not to be called → `ended` (an opt-out writes a suppression);
- no answer → retry later (optionally a "sorry we missed you" WhatsApp — needs its own approved
  template).

### 3.5 The answer, and the human approval

**Drafting (AI):** a job sends the call-1 transcript + extracted fields + what the CRM knows (grade
reason, webinars, past contact, the AI Summary reading) through the shared `AiClient` (prompt key
registry, `ai_requests` log) with a **knowledge pack the owner supplies** (the company's answers to
common problems — loan quota, down payment, which area / project, rental, programmes) and writes:
problem recap · 2–3 point answer · the offer (a session with our specialist) · what NOT to say
(no promised prices or returns).

**Approval (human):**
- A task for the **account manager** lands in **My Workspace → Sales steps** in a new lane
  ("AI nurture · approve"). If the account manager is inactive or missing, it goes to round robin.
- It opens a review panel showing the call-1 summary, transcript and recording link, the AI draft
  (editable), and three buttons:
  - **Approve & let AI call** → `call2`, with the text frozen, who approved, and when;
  - **I'll call myself** → hand-over now; they use the normal phone / Record-contact path;
  - **Not suitable** → ends, with a note.
- **Reminder** after 2 days; **expires** after 7 (a week-old answer to a phone conversation is
  stale) → ends `approval_expired`, or goes to the team leader (owner decision).
- Leaders / super admins can approve any; another REP can see it but does not get the task.

### 3.6 Call 2 — the answer and the appointment

A second profile ("B nurture · solution") with the **appointment goal**, given
`{{approved_solution}}`, `{{previous_summary}}` and `{{lead_name}}`.
- **A time agreed** → a pending appointment request + `confirm_appointment` task to the account
  manager (the CRM's existing rule: a human confirms; nothing is booked by the AI).
- **Keen without a time** (`wants_human`, high interest) → a "call them back — keen" task.
- **Not interested** → ends.
- **No answer** → retries, then a task "AI could not reach them for the answer — your call?".

Hand-over always means a task in **Sales steps** for the account manager, and the nurture closes.

### 3.7 What the REP / account manager sees and does

| Where | What |
|---|---|
| **My Workspace → Sales steps** | new lanes: *approve the AI answer*, *confirm appointment*, *call back — keen*, *AI could not reach* — the same board they already work |
| **Lead page / lead modal** | the grade badge, and an **AI nurture** card: the steps so far, both calls (summary, transcript, recording), the approved answer, who approved; actions **Pause**, **Stop**, **Call now with AI** (call 2, inside the window), **I'll take it** |
| **Leads list** | grade column; filter "in AI nurture" by step |
| **Their own call** | unchanged: the existing phone call / Record-contact flow; a recorded contact on a nurture lead ends the nurture as `self_call` |

### 3.8 Switches, money and safety

- **Off until the owner switches it on:** env master switch + a DB setting, plus the daily intake
  cap. Each step can be held on its own: enrol, call 1, call 2.
- **Budget:** its own daily budget, so nurture calls can never use up the US$15 that registration
  welcome calls need (or raise the shared cap — owner decision).
- **Rough cost:** about 4 min (call 1) + 3 min (call 2) per reached lead ≈ **US$0.65**. For the whole
  backlog (2,529 with a phone, if about 40% are reached) ≈ **US$400–700** over its run.
- **Consent and safety:**
  - Honour WhatsApp STOP and every opt-out before an AI call. Today the caller does not, so this
    needs fixing first.
  - The agent says it is an AI (Retell's terms).
  - Use a calling window of e.g. 10:00–20:00.
  - Never call from the dev box: it is bound to the real Retell account.
  - Test only on staff phones.
- **Fix before scaling** (from the 2026-10-13 audit, still open):
  - Inspector logs the Retell key.
  - AI follow-up WhatsApps skip STOP.
  - The budget fuse trips at about 4 concurrent calls.

## 4. Owner decisions needed

| # | Question | Recommendation |
|---|---|---|
| D1 | Who approves the AI answer? | The **account manager**; leaders may approve any; a REP only sees |
| D2 | Backlog speed: how many existing B leads a day? | Pilot **20/day for 2 weeks**, then 50 |
| D3 | Which B leads first? | Freshest signal first; WhatsApp-reply and price-question leads before webinar-only |
| D4 | Money: a separate nurture budget, or raise the shared US$15? | Separate, **US$10/day** to start |
| D5 | Calling window and days | **10:00–20:00, Mon–Sat** |
| D6 | Retries for each call | **3 tries** (day 0, +2, +5) |
| D7 | Missed-call WhatsApp? From which number? | Yes, from the Cloud API number, after an approved template |
| D8 | Approval not done in time | Remind at 2 days, end at 7 (or pass to the team leader) |
| D9 | What is "keen"? | Wants a human, high interest / actively looking, or graded up to A / S |
| D10 | Appointment: human confirms, or book directly? | **Human confirms** (today's CRM rule) |
| D11 | Leads in a webinar funnel flow, or with open sales tasks | Skip them |
| D12 | Re-nurture the same lead again? | Not within **90 days** |
| D13 | Language of the calls | Mandarin with English; a Cantonese pair for HK leads later |
| D14 | The knowledge pack for drafting answers | The owner supplies the common problems and approved answers |

## 5. Phases

| Phase | Work | Estimate |
|---|---|---|
| P0 | Safety first: STOP / opt-out checked before AI calls and follow-ups, Inspector key redaction, budget per purpose | 1 day |
| P1 | Grade changes: history table, entered / left hooks, early first grade, grade badge + column | 1–2 days |
| P2 | Nurture table + scanner + enrolment (switch off) + call 1 profile + aftermath hook + dry-run | 3 days |
| P3 | AI drafting (AiClient prompt + knowledge pack) + approval task, lane and review panel | 3 days |
| P4 | Call 2 + appointment request / keen hand-over + leaving-B handling + lead-page card | 2–3 days |
| P5 | Pilot on staff phones → 20 real leads → handbook (`ai-nurture.md`), tests, report numbers | 2 days |

About **2½ weeks** of engineering.

## 6. Out of scope (v1)

- Grades A, C and S (A and S already belong to sales; C could get a lighter flow later).
- The AI booking straight into the calendar (it stays a human-confirmed request).
- SMS or e-mail rounds.
- Changing the grade rules themselves.
