docs: AI coaching panel implementation plan — 8 tasks

Covers: suggestion rules engine, structured AI output, summary card,
suggestions component, chat panel rewrite, context panel wiring,
settings UI, deploy + test.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/plans/2026-04-17-ai-coaching-panel.md

@@ -0,0 +1,140 @@
+# AI Coaching Panel Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the AI chat panel with a three-zone coaching surface — structured summary card, rule-driven suggestions with scripts, and contextual chat with progressive suggestion updates.
+
+**Architecture:** CallerContextService (already built) pre-fetches caller data into Redis. Rules engine evaluates caller facts against seeded suggestion rules, producing triggers. AI system prompt includes caller context + suggestion triggers + structured output instructions. Every AI response returns `{ message, suggestions }` JSON. Frontend parses and renders across three zones.
+
+**Tech Stack:** React 19 + Tailwind (frontend), NestJS + Vercel AI SDK + json-rules-engine + Redis (sidecar), FontAwesome Pro icons
+
+---
+
+## File Structure
+
+### Sidecar (helix-engage-server)
+
+| File | Responsibility |
+|------|----------------|
+| `src/rules-engine/suggestion-rules.ts` | NEW: Default suggestion rule definitions + evaluator function |
+| `src/caller/caller-context.service.ts` | MODIFY: Add suggestion evaluation, render suggestions for prompt |
+| `src/ai/ai-chat.controller.ts` | MODIFY: Inject suggestion rules into system prompt |
+| `src/config/ai.defaults.ts` | MODIFY: Update ccAgentHelper prompt with structured JSON output format |
+
+### Frontend (helix-engage)
+
+| File | Responsibility |
+|------|----------------|
+| `src/components/call-desk/ai-summary-card.tsx` | NEW: Zone 1 patient profile card |
+| `src/components/call-desk/ai-suggestions.tsx` | NEW: Zone 2 suggestion pills with expand/script/tell-me-more |
+| `src/components/call-desk/ai-chat-panel.tsx` | REWRITE: Orchestrates 3 zones, parses structured JSON responses |
+| `src/components/call-desk/context-panel.tsx` | MODIFY: Remove P360 tab toggle, single surface |
+| `src/pages/rules-settings.tsx` | MODIFY: Display suggestion rules in Automations tab |
+
+---
+
+## Task 1: Suggestion Rules Engine (Sidecar)
+
+**Files:**
+- Create: `helix-engage-server/src/rules-engine/suggestion-rules.ts`
+- Modify: `helix-engage-server/src/caller/caller-context.service.ts`
+
+- [ ] **Step 1:** Create `suggestion-rules.ts` with types (`SuggestionType`, `SuggestionPriority`, `SuggestionTrigger`), department-to-package mapping, cross-sell mapping, and `evaluateSuggestionRules(facts)` function that evaluates 5 default rules: (1) package upsell by department, (2) reschedule missed appointments, (3) cross-sell related departments, (4) first-visit health checkup, (5) returning patient re-engagement. Max 4 triggers returned. Also export `SUGGESTION_RULE_DEFINITIONS` array for Settings UI display.
+
+- [ ] **Step 2:** In `caller-context.service.ts`, add `suggestionTriggers: SuggestionTrigger[]` to the `CallerContext` type. Import `evaluateSuggestionRules`. Call it in the `build()` method after fetching all data, passing caller facts (isNew, appointments, calls, interestedService, contactAttempts, leadSource, utmCampaign). Add `renderSuggestionsForPrompt(triggers)` method that formats triggers for the AI system prompt.
+
+- [ ] **Step 3:** Build and verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 4:** Commit: `feat: suggestion rules engine + caller context evaluation`
+
+---
+
+## Task 2: Structured Output in AI System Prompt (Sidecar)
+
+**Files:**
+- Modify: `helix-engage-server/src/config/ai.defaults.ts`
+- Modify: `helix-engage-server/src/ai/ai-chat.controller.ts`
+
+- [ ] **Step 1:** In `ai.defaults.ts`, append structured output instructions to `CC_AGENT_HELPER_DEFAULT` template. The AI must respond with valid JSON: `{"message": "...", "suggestions": [{"id", "type", "title", "script", "priority"}]}`. Rules: always include suggestions on first response, update on subsequent, no markdown in message field, max 4 suggestions, personalized scripts using caller's name/doctor/department.
+
+- [ ] **Step 2:** In `ai-chat.controller.ts` stream endpoint, after the caller context injection block, inject suggestion rules: `if (callerCtx.suggestionTriggers?.length) systemPrompt += this.callerContext.renderSuggestionsForPrompt(callerCtx.suggestionTriggers)`
+
+- [ ] **Step 3:** Build and verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 4:** Commit: `feat: structured JSON output + suggestion rules in AI system prompt`
+
+---
+
+## Task 3: AI Summary Card Component (Frontend)
+
+**Files:**
+- Create: `helix-engage/src/components/call-desk/ai-summary-card.tsx`
+
+- [ ] **Step 1:** Create Zone 1 component. Props: `caller: CallerSummary | null`. Renders: patient avatar + name + NEW/RETURNING badge, phone number, 2-line AI summary (line-clamped), source + campaign badges, compact appointment pills (next upcoming with green bg, last completed with gray bg). For null caller: centered placeholder text. Uses Badge component, FontAwesome icons (faUser, faCalendarCheck, faPhone).
+
+- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 3:** Commit: `feat: AI summary card component (Zone 1)`
+
+---
+
+## Task 4: Suggestions Component (Frontend)
+
+**Files:**
+- Create: `helix-engage/src/components/call-desk/ai-suggestions.tsx`
+
+- [ ] **Step 1:** Create Zone 2 component. Props: `suggestions: Suggestion[]`, `onTellMeMore: (suggestion) => void`. Exports `Suggestion` type (id, type, title, script, priority). Renders: collapsible section header "Suggestions (N)", list of compact pill cards. Each pill: type icon (faArrowUp/faTag/faRotate/faClipboardCheck), title, priority dot (red/yellow/green). Click toggles expand with script text + "Tell me more" link. Collapse/expand toggle for entire section.
+
+- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 3:** Commit: `feat: AI suggestions component (Zone 2)`
+
+---
+
+## Task 5: Rewrite AI Chat Panel (Frontend)
+
+**Files:**
+- Rewrite: `helix-engage/src/components/call-desk/ai-chat-panel.tsx`
+
+- [ ] **Step 1:** Rewrite to orchestrate 3 zones. New props: `callerSummary?: CallerSummary | null`. Adds `suggestions` state managed from parsed AI responses. `parseAiResponse(content)` extracts `{ message, suggestions }` from JSON, falls back to raw text on parse failure. Zone 1: AiSummaryCard (not shown for supervisor). Zone 2: AiSuggestions with `onTellMeMore` that appends "Tell me more about X" as chat message. Zone 3: chat with `displayMessages` that strips JSON wrapper showing only the message field. Auto-fire kept. Supervisor mode unchanged (quick actions, no summary/suggestions). Keep existing MessageContent + parseLine helpers.
+
+- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 3:** Commit: `feat: rewrite AI chat panel — 3-zone coaching surface`
+
+---
+
+## Task 6: Wire Context Panel (Frontend)
+
+**Files:**
+- Modify: `helix-engage/src/components/call-desk/context-panel.tsx`
+
+- [ ] **Step 1:** Remove P360 tab toggle (activeTab state, tab buttons, P360 sections — appointments list, call history list, follow-ups list). Build `callerSummary` object from `selectedLead` + `appointments` data: name, phone, isNew, aiSummary, leadSource, utmCampaign, nextAppointment (first SCHEDULED after now), lastAppointment (first COMPLETED). Pass `callerSummary` to AiChatPanel as new prop. Single surface — AiChatPanel is the only content.
+
+- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 3:** Commit: `feat: remove P360 toggle, single coaching surface`
+
+---
+
+## Task 7: Settings UI — Suggestion Rules Display
+
+**Files:**
+- Modify: `helix-engage/src/pages/rules-settings.tsx`
+
+- [ ] **Step 1:** Add `SUGGESTION_RULES` array (5 items: name, category, description, enabled) to the Automations tab. Render below existing automation rules with "AI Suggestions" subheading. Same card pattern: category badge, name, description, enabled/disabled dot. All enabled, read-only.
+
+- [ ] **Step 2:** Verify: `npx tsc --noEmit` exits 0
+
+- [ ] **Step 3:** Commit: `feat: display suggestion rules in Settings > Automations`
+
+---
+
+## Task 8: Build, Deploy, Test
+
+- [ ] **Step 1:** Build sidecar: `cd helix-engage-server && npm run build`
+- [ ] **Step 2:** Build frontend: `cd helix-engage && npm run build`
+- [ ] **Step 3:** Deploy sidecar to ECR + pull on EC2
+- [ ] **Step 4:** Deploy frontend to EC2 via rsync + restart Caddy
+- [ ] **Step 5:** Test on Tauri: rebuild frontend with Global URL, launch, trigger call. Verify: Zone 1 summary card, Zone 2 suggestions from rules, click expand shows script, "Tell me more" sends to chat, progressive suggestion updates, server logs show cache hits and no tool calls for patient data
+- [ ] **Step 6:** Final commit and push both repos