# Revenue Intelligence Assistant — PropertyLab

## Decision

Keep the five channel agents. Add one customer-level coordinator that maintains a current understanding of each customer, chooses one useful next action, gives it to the responsible staff member or channel agent, and checks what happened. Staff should spend their time helping customers. The CEO should see exceptions that need a business decision, rather than reviewing every lead.

The first AI Copilot tab is **Revenue Intelligence** at `/manage/ai-copilot`. Summary moves to `/manage/ai-copilot/summary`; the other tabs retain their routes.

## What was actually inspected

- The deployed application at `/var/www/html/peta`, configured for `https://wk.propertylab.com.my` and database `petav3wk`.
- Live SELECT queries with `SET SESSION TRANSACTION READ ONLY`, on 16 September 2026 at approximately 04:06–04:12 Malaysia time. The MySQL session clock is UTC; application dates default to Asia/Kuala_Lumpur. This distinction matters when implementing deadlines.
- Table schemas, active-record counts, lead linking, staff/test/historical traffic, action-plan status, readiness-score arithmetic, and small purposive samples from every channel. Samples were selected for recency, useful sales content, high readiness, and cross-channel overlap. They are diagnostic examples, not a random sample or a conversion study.
- The actual Zoom RIA curriculum: `resources/js/Pages/Manage/Zoom/Playbook/Partials/RiaChapter.vue`, its scoring prompt, the channel models/controllers, `SalesWorkQueue`, and `LeadSalesCoachContextBuilder`.
- The initial local database was a development fixture containing one lead and no channel conversations. It was excluded from the business findings below.

### Live evidence that changes the design

| Finding | Observed evidence | Product implication |
|---|---|---|
| Analysis is not reliably becoming work | 226 draft action plans, 4 approved plans; 21 open lead tasks across 14 leads, none scheduled | Create routine next actions automatically after validation. Do not require someone to open and approve every conversation report. |
| Readiness is conversation-specific | 207 scored avatars cover 154 distinct linked leads; a sampled customer has scores of 85 and 43 in different conversations | Maintain one chronological customer profile. Do not average scores or pick the highest, and do not use batch-mining time to decide what happened last. |
| Showroom intelligence cannot reach the customer | All 7 active F2F recordings are unlinked; 5 have analysis | Identify the customer reliably before using badge evidence. Queue unresolved identity as a capture exception. |
| WhatsApp volume includes very different behavior | 47,201 active message rows; direct chats include imported history, templates, questions, acknowledgements and media | Measure meaningful customer engagement separately from reminders and imported messages. Never increase readiness just because many messages were sent. |
| “Unanswered” does not always mean follow-up needed | Samples include a next-class question, “Noted.Tq”, and an unrelated car advertisement | Interpret the actual request and business relevance. Acknowledgements can be closed without another message. |
| Recording tests contaminate a naïve ranking | The latest three sampled linked phone analyses were a recording test, an unrelated conversation, and repeated greetings | Filter by content/relevance before extracting readiness. Silence or a test recording must not reduce an established customer's score. |
| Portal evidence is useful but incomplete | 67 wealth plans across 50 leads, 28 analyses across 8 leads, 32 AI conversations across 24 leads, and 90 lesson-progress records across 32 leads; some records belong to staff | Exclude staff activity and empty plan shells. A page visit is evidence of activity, not proof of financial capacity or buying intent. |
| Generated sales copy can overstate certainty | Sampled stored recommendations included absolute financing assurances and an assurance about bank scrutiny | Do not forward legacy `say_this` text automatically. Generate from approved facts and validate claims before customer delivery. |

Counts above are active/non-deleted rows where that table supports soft deletion. Avatars are not unique customers. Zoom meetings and Zoom recording files are different units. These measurements describe this database at the inspection time, not all company activity.

### Real examples, anonymized

1. **Messages:** A customer said an unexpected commitment prevented attendance and asked whether there was another class. Next action: verify the next available class and answer that question. Sending another property pitch does not meet the need.
2. **Portal:** A customer compared two projects by rental yield, ROI, pricing and transport convenience. Next action: offer a comparison against their own decision criteria, using verified facts and clearly identified assumptions. Ask what remains unclear; do not infer available cash from the searched price.
3. **Zoom:** A customer discussed portfolio commitments, wanted to preserve financing for a future own-stay home, and questioned resale liquidity. Their portal plan was an empty shell and WhatsApp included trouble accessing a feature. The joined interpretation is to help complete the planning exercise and compare the competing goals, rather than infer a lack of interest from the empty plan.
4. **Phone:** One prospect requested an evening callback; another preferred a showroom visit and did not want Zoom. Store the promised callback time and preferred channel. A generic “book a Zoom” policy would disregard the evidence.
5. **Showroom:** An unlinked recording contains a request for large KLCC units and concern about appreciation. The first action is to identify the customer; only then prepare the relevant shortlist and evidence. No customer's profile should be changed by a guessed identity.

## Channel responsibilities

| Channel | Available behavior and evidence | Agent responsibility | Shared customer memory |
|---|---|---|---|
| Portal | Wealth plans and their state, financial-analysis/consent workflow, property analyses, concierge requests, AI questions, lesson completion/rewatching, area learning and AI E-Learning activity | Explain results; detect requested help, comparisons and incomplete journeys; offer the right learning or staff handoff | Goals, explicit criteria, unanswered questions, stated numbers, content actually used; distinguish an empty shell, a saved assumption and a confirmed fact |
| Messages | WhatsApp Cloud/QR and Messenger, text/media, delivery/failure/read state, live versus historical messages, direct versus group chat, templates, flows, AI drafts/replies/handoffs, block/opt-out state | Answer requests; extract new facts and objections; remember preferences and promises; follow up within the channel's actual rules | Who said what and when; customer versus staff statement; unanswered request; contact preference; objection resolution supported by a reply |
| Zoom | Scheduled/completed meetings, transcript and recording, analysis, customer avatar and CRS, objections, decision criteria, next steps, live/post-call copilot, coaching and action plans | Brief staff before a meeting; observe decision criteria and participants; extract commitments and unresolved issues afterward | Decision-maker participation, proof accepted/rejected, specific objections, promised material, next appointment, relevant score evidence |
| Phone Call | Uploaded/ingested calls, lead matching, duration/status, transcripts and analysis, ignored/non-sales calls, callback commitments, briefs and action plans | Distinguish contact attempts from consultations; respect callbacks; clarify one gap; carry the result back to the shared profile | Availability, preferred channel, stated intent, objections and actual progress; missed calls never count as a failed qualification |
| Showroom F2F | Badge/manual recordings, capture/transcription state, agent/device association, manual customer linkage, analysis and follow-up | Ensure correct customer linkage; record unit reactions, attending decision-makers, questions and commitments; follow through on the visit | Who attended, what was preferred, what remained unresolved and what was actually agreed; no facial/emotional guesswork |

Each channel publishes facts and proposed actions. The coordinator owns prioritization and prevents two agents from contacting the same customer with conflicting instructions.

## The operating loop

1. **Capture:** A new message, completed analysis, portal action, task outcome or deal-stage change marks the customer as changed. Keep source event time and ingestion time separately.
2. **Check relevance and identity:** Filter staff/test/group/imported traffic according to purpose. Unlinked or conflicting identities go to a small exception queue. Imported history may inform context but cannot trigger a “just now” alert.
3. **Update memory:** Merge explicit facts, statements, preferences, promises and unresolved questions into the customer's profile, preserving source references. A newer explicit correction can supersede an old statement. An uninformative call cannot erase established knowledge.
4. **Assess readiness:** Reassess only affected dimensions from the accumulated evidence. Validate structure, bounds and evidence references in code. Keep uncertainty visible.
5. **Choose the next action:** Honor opt-outs and active commitments first; answer customer requests; keep promises; resolve the most important obstacle; then offer the next suitable appointment or learning step. Respect the customer's timing.
6. **Assign and prepare:** Resolve the owner from lead/opportunity assignments, prepare a specific instruction and draft, set a proposed deadline, and upsert one task. Auto-assignment follows an explicit distribution rule; unowned leads are not silently assigned to the CEO.
7. **Execute through the existing channel engine:** Use the existing inbox/flow/send path, its connection checks, permitted templates, limits and handoff rules. One send lease per customer prevents duplicate contact.
8. **Observe outcome:** Delivery, reply, document receipt, appointment attendance, task completion and stage changes are different events. A sent message is not a resolved objection. Reassess when new evidence arrives.
9. **Brief the CEO:** Show only overdue commitments, missing owners, blocked integrations, identity/financial-term conflicts, and business decisions. Provide a weekly movement report for a fixed cohort.

Recommended cadence: coalesce bursts of messages into a single customer update; event-driven reassessment after that; a morning reconciliation sweep to catch missed events; periodic due-task checks. Store every run's input watermark, model/prompt/rubric versions, cost, errors and completion state. Retry failed work with the same idempotency key.

## Readiness contract

Retain the existing five dimensions, each 0–20: **trust, framework awareness, loan, cash, decision-maker**. Calculate totals in code. Retain the existing three flags:

- **No compelling event:** ask about genuine timing; cap Booking-Ready at Sales-Ready. Never fabricate scarcity or deadlines.
- **Objection debt:** two or more unresolved objections; cap Booking-Ready and block closing actions until resolved with evidence.
- **Competitor active:** increase priority without subtracting points or lowering the readiness band. Present fair comparisons.

Add `evidence_status` (`known`, `unknown`, `conflicting`, `stale`), `evidence_ids`, `observed_at` and `scoring_version` per dimension. An unknown dimension is not a factual diagnosis of inability. Preserve the legacy scoring rubric during migration, but report coverage alongside totals; do not interpret a score jump caused only by more complete evidence as improved customer readiness.

Separate four concepts in both data and UI: **readiness**, **relationship/contact preference**, **urgency**, and **confidence/coverage**. Opening three property pages can increase the urgency of offering help; it cannot establish loan approval or decision-maker agreement.

Do not optimize for more messages or a higher number. Optimize for the customer making informed progress: a question answered, a criterion clarified, a concern resolved, the right person included, or a suitable appointment attended. Only later customer evidence can substantiate CRS improvement.

## Autonomy without a second full-time reviewer

| Work | Default behavior |
|---|---|
| Summarize, classify, retain sourced facts, refresh readiness, prioritize, prepare drafts and briefs, detect overdue work | Automatic after machine validation; log the decision |
| Straightforward FAQ or agreed reminder grounded in approved current facts | Eligible for automatic delivery through the existing channel engine after the relevant playbook passes evaluation and contact rules |
| Ambiguous need or missing financial/timing information | Ask a narrow clarification through the appropriate staff/channel workflow; do not invent an answer |
| Identity conflict, refund/contract decision, disputed commitment, exceptional price/financing terms | Escalate the specific decision with evidence and a proposed resolution |
| Approval, guarantee, binding price/stock commitment or unsupported claim | Never infer it from model prose |

The human exception list should be short because the system prepares the facts and recommendation. It should not ask someone to review every customer transcript. Employees still hold conversations, deliver service and make decisions within their authority.

## Backend implementation

Reuse `ConversationAnalysis` for legacy/current schema reads, channel source adapters for provenance, `LeadVisibility` and `AccountVisibility` for every read, `LeadActionItem` for accepted/executable tasks, `AiClient`/`AiJob`/`ai_requests` for model work and cost, and the existing WhatsApp engine for delivery.

Add:

- `lead_revenue_profiles`: one current profile per lead; source watermark, normalized dimensions/flags, confidence/coverage and current action objective.
- `lead_revenue_evidence`: source type/id, lead id, source event time, ingestion time, fact/claim type, evidence excerpt or reference, supersession and retention metadata.
- `lead_revenue_runs`: status, input hash/watermark, prompt/model/rubric versions, retry state, cost and output validation result.
- Extend `lead_action_items` with coordinator origin/idempotency and outcome metadata; do not create a competing task checklist. Preserve existing plan approvals for their current workflow. Routine coordinator tasks have their own explicit origin and do not masquerade as approved conversation plans.
- A customer-change listener and debounced job; a daily reconciliation command; a deterministic next-action policy; a channel execution adapter; a global pause and per-channel operating controls.

All writes use transactional repositories. Model calls and network sends happen outside transactions. Before committing an assessment, compare the input watermark with the latest lead state; stale results are discarded and rescheduled. Task creation is idempotent on customer, objective and triggering evidence. Completion never simply deletes a recommendation: preserve its outcome and suppress regeneration until relevant new evidence appears.

Example action contract:

```json
{
  "lead_uuid": "...",
  "objective": "clarify_decision_maker",
  "why_now": "Customer asked to discuss the comparison with their partner",
  "evidence_ids": ["..."],
  "owner_user_id": 123,
  "recommended_channel": "whatsapp",
  "instruction": "Offer a short joint discussion focused on their two open questions",
  "draft": "...",
  "due_at": "...",
  "due_source": "proposed_service_target",
  "status": "ready",
  "success_condition": "Joint discussion accepted or customer specifies an alternative",
  "input_watermark": "...",
  "idempotency_key": "..."
}
```

A proposed service target is visibly different from a date promised by the customer. Draft text must not introduce guarantees, fabricated deadlines, unsupported financing assumptions, or claims that a task is complete.

## First-tab implementation in this change

The new page is a working read-only evidence queue, backed by current database queries rather than hardcoded sample records. It groups prospective-customer signals and existing assigned tasks by lead, shows a suggested next step, permits filtering/search, exposes dated evidence and the last valid scored conversation, and links into the actual customer/inbox workflows.

The queue filters non-sales recording categories and ignored calls; excludes converted/lost leads from new prospect outreach while retaining explicit existing service tasks; excludes blocked contacts, historical inbound traffic, sandbox/group chats and personal CEO channels; excludes empty wealth-plan shells; distinguishes acknowledgements from potential questions; resolves avatar order by conversation time; recalculates CRS totals and flag caps; and marks evidence older than 14 days for confirmation. It never reuses legacy AI `say_this` as a ready-to-send message.

**Limits:** request recognition is a conservative rules baseline, not a semantic classifier. It cannot prove that a later unrelated outbound message answered a question. The displayed CRS is historical, not a newly merged cross-channel score. Portal lessons, area learning, Messenger, event attendance and source failures need additional adapters before claiming complete behavioral coverage. The page recomputes on open/refresh; it does not yet schedule model reassessment, send messages, infer task completion or operate a background monitoring service.

## Build order and acceptance gates

1. **Evidence queue and channel contract:** this change. Confirm customer visibility, source dates and real-world relevance; provide a useful first tab immediately.
2. **Unified memory and incremental reassessment:** add evidence/profile/run persistence and event listeners, then the scheduled reconciliation job. Backfill in bounded batches, with a cost limit. Start with linked sales conversations and direct customer messages.
3. **Task lifecycle:** auto-create routine tasks, resolve owners, propose deadlines, record outcome, snooze/cancel stale work and prevent duplication. Add a calendar/channel-specific execution path using existing services.
4. **Channel completeness and exceptions:** add the remaining portal/Messenger/event inputs; fix F2F linking; report coverage gaps and disconnected agents in the CEO exception list.
5. **Selective autonomous execution:** evaluate each playbook against historical cases, then enable only the playbooks that pass. Measure meaningful replies, fulfilled promises, appointments attended, customer complaints/opt-outs and validated readiness movement.

Required regression cases include the actual observed patterns: a greeting-only call does not lower readiness; a class-reschedule request receives scheduling help; “Noted.Tq” does not trigger another contact; car advertisements do not enter the sales queue; two channels cannot send duplicate follow-ups; a converted customer is not pitched the same deal; an old “Monday” is not treated as a future appointment; an unlinked showroom recording never changes a guessed lead; a read receipt never resolves an objection; failed sends do not count as answers; user and channel scope changes revoke access immediately.

## What the CEO should see each morning

“Here are the customers needing a conversation today, the commitments at risk, and the few decisions that need you. Each staff member already has their own next steps and prepared context. Here is what the agents completed, what changed after customers responded, and what is blocked.”

That is the target operating system. Agent dashboards and scorecards remain useful supporting views; the daily action-and-outcome loop is the product that removes the review burden.