# Sales Coach follow-ups — design

**Date:** 2026-08-05 (decided in the product meeting the same day)
**Target:** local `dev-chen` / petaV3 demo
**Status:** approved design

Three follow-ups raised by Wai Kit and Shawn in the 2026-08-05 meeting, on top of the
shipped Lead Sales Coach and per-recording Ask AI chat.

---

## A. Coach reachable from the Lead quick-view modal

**Problem.** The coach renders only on the Lead Show page. From the Zoom Action Items
board — the actual demo path — clicking a customer name opens the quick-view
`LeadDetailModal`, and the coach is deliberately absent there: `Drawer.vue` does not join
`Modal.vue`'s Escape stack, so Escape closed the host modal too, and the Drawer's
`onUnmounted` reset of `document.body.style.overflow` broke the host's scroll lock.

**Decision — inline, not a drawer.** In the modal host the coach renders as an expandable
panel inside the Discussion right rail rather than opening a second overlay. No nested
overlay means neither defect can occur, and `Drawer.vue` / `Modal.vue` stay untouched.

- Lead Show page: unchanged — card + drawer as today.
- Quick-view modal (`writeMode === 'modal'`): the same card, but "Open coach" expands the
  conversation in place, below the card, inside the existing rail scroll.
- Both hosts share one conversation component and the same `useSalesCoachChat` engine; only
  the container differs.
- Still gated on `features.lead_sales_coach_demo`.

Teaching `Drawer.vue` to join the Modal stack remains the correct long-term fix and is
still tracked, but it is not required by this design and is out of scope here.

## B. Chat inside Review Action Plan

**Purpose.** While a Super Admin reviews the AI-drafted checklist, they can ask why the AI
wrote those steps and how to improve them.

**Decision — advisory only.** The chat NEVER rewrites the steps. It answers and suggests;
the reviewer edits by hand in the existing editor. This preserves the read-only contract the
shipped coach was reviewed under, and keeps customer-authored text (which is in the context)
from ever driving a write.

**Context.** This meeting plus the steps currently in the editor:
- the meeting's identity and its `ai_analysis` (the same shape the recording chat uses), and
- the **live, unsaved** draft steps from the review editor, sent with the request, so the
  answer addresses what the reviewer is looking at rather than what is stored.

Explicitly NOT included: the lead's other conversations or history. That is the Lead Sales
Coach's job, and duplicating it here would blur the three chats' distinct remits. Transcript
is included on the same truncated terms as the recording chat.

**Prompt.** New key `action_plan_review_chat`. It must: ground every claim in the supplied
meeting + steps; explain its reasoning about the steps; suggest concrete edits as text the
reviewer can copy; never claim to have changed anything; treat everything inside the
delimiter as quoted untrusted data.

**Flag.** Reuses `features.zoom_action_plan_demo` — it is part of that workflow's surface.

## C. Step-level agree / disagree feedback

**Purpose.** Chatting with the AI does not make the AI better. To improve the prompt we need
the people who actually work the steps to say, per step, whether it was any good — and why,
when it was not.

**Decision — the salesperson rates the work they were given.** Feedback lives on the
GENERATED Lead Action Items, not on the draft in review. Wai Kit's "收东西的那个人" — the
person receiving the task — is the salesperson, and rating after doing the work reflects
whether the step was actually useful, not merely whether it looked plausible.

- On each generated action item, an assignee sees agree / disagree.
- Disagree requires a short reason; agree does not.
- One rating per user per item, changeable.
- Ratings are advisory data only. Nothing in the product reads them at runtime — no
  auto-tuning, no feeding them back into a prompt. A human reads them and edits the prompt.
- Storage: a new `lead_action_item_feedback` table (item, user, verdict, reason, timestamps).
  Verdict is an integer constant per GUIDELINES §4, not a string.
- Read surface for now: a simple listing an admin can page through. Aggregation by
  salesperson / project is explicitly deferred until there is enough data to want it.

Not a chat feature; no AI call is involved in recording feedback.

---

## Non-goals (all three)

- No auto-assignment, no priority/H-M-L tagging, no commission or scoring columns — those
  were also raised in the meeting and are separate work.
- No auto-tuning of prompts from feedback.
- No changes to `Drawer.vue` or `Modal.vue`.
- Nothing is enabled in production: every surface stays behind its existing demo flag.