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

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