# Pre-Call Briefing 0.1% Plan

> **Status:** READY FOR CC2
> **Created:** Jan 17, 2026
> **Priority:** #10
> **CC1 Investigation Complete**

---

## Executive Summary

Transform the fragmented pre-call experience into a **full-screen AI-powered briefing page** that loads BEFORE the call starts. Currently intel loads during calls (2-3 sec delay), scripts are matched by basic DB rules (no AI), and users must click through multiple modals. The 0.1% solution gives sales reps everything they need in one glance with zero delay when the call connects.

---

## Problem Statement

### Current Pain Points

1. **Intel loads DURING call** - 2-3 second delay while customer is already on the line
2. **Collapsed by default** - Intel hidden behind clicks during live calls
3. **Scripts matched by DB only** - No AI analysis of lead context, history, or similar wins
4. **Single stage visibility** - Can only see current script stage, not the full flow
5. **Suggestions auto-dismiss** - Can't reference objection counters after 10 seconds
6. **Two clicks to start** - Modal → "Ready to Call" → Modal → "Start Call"

### User Impact

- Sales rep scrambling to read intel while customer waits
- Missing context because they didn't click to expand
- Using wrong script because AI didn't analyze the lead
- Forgetting objection counter because it disappeared

---

## Solution: Full-Screen Pre-Call Briefing

### New Flow

```
CallList/LeadProfile → Click "Call" → /call-prep/:leadId (Full Screen)
    │
    │  [Everything pre-loads while user reviews]
    │
    ├─ HEADER: Lead name + company + score badge
    │
    ├─ LEFT PANEL: AI Intel Brief
    │   ├─ 30-second summary (bold, large text)
    │   ├─ Opening line (copy button)
    │   ├─ 3 talking points (numbered)
    │   ├─ Predicted objections (with counters)
    │   └─ Similar wins ("Leads like this converted when...")
    │
    ├─ RIGHT PANEL: AI-Recommended Script
    │   ├─ Script name + success rate badge
    │   ├─ WHY this script (AI explanation)
    │   ├─ All 5 stages visible:
    │   │   ├─ Opener (highlighted as first)
    │   │   ├─ Discovery Questions
    │   │   ├─ Value Props
    │   │   ├─ Objection Handlers
    │   │   └─ Closing Techniques
    │   └─ Each stage expandable/collapsible
    │
    ├─ BOTTOM: Company + Person Intel Cards (collapsible)
    │
    └─ FLOATING ACTION: "Start Call" button (green, pulsing)
        │
        └─ Click → Call starts with ZERO delay (everything pre-loaded)
```

### Key Features

| Feature | Description |
|---------|-------------|
| **Full-screen page** | Dedicated `/call-prep/:leadId` route, not a modal |
| **AI script recommendation** | Analyzes lead history, comms, objections, similar wins |
| **All stages visible** | See entire script flow, current stage highlighted |
| **Pre-loaded intel** | Everything fetched before call, passed to LiveCopilot |
| **One-click start** | Single "Start Call" button, no confirmation modal |
| **Persistent during call** | Intel panel stays visible (collapsible) during call |

---

## Technical Design

### 1. New Page: CallPrepPage.jsx

```jsx
// admin/src/pages/CallPrepPage.jsx
// Full-screen pre-call briefing

State:
- lead (from API)
- intelBrief (AI-generated)
- recommendedScript (AI-selected)
- similarWins (array)
- companyIntel (Perplexity cache)
- personIntel (Perplexity cache)
- loading (boolean)
- readyToCall (boolean - all data loaded)

Flow:
1. Mount → Fetch all data in parallel
2. Display loading skeleton while fetching
3. When all loaded → Enable "Start Call" button
4. Click "Start Call" → Navigate to /call/:leadId with pre-loaded data
```

### 2. New Endpoint: AI Script Recommendation

```javascript
// GET /api/scripts/ai-recommend/:leadId
// Returns AI-analyzed script recommendation

Input: leadId

Process:
1. Get lead with full history (comms, notes, callbacks)
2. Get recent objections from copilot_sessions
3. Get similar wins (same trade, same stage, converted)
4. Get all active scripts for lead_type

AI Analysis (GPT-4o-mini):
- Analyze lead context (score, status, days since contact)
- Analyze communication history (positive/negative sentiment)
- Analyze previous objections encountered
- Match against script effectiveness data (success_count/times_used)

Output:
{
  "recommendedScript": { ...script },
  "reason": "Why this script for this lead",
  "confidence": 0.85,
  "alternativeScripts": [ ...top 3 others ],
  "customizations": {
    "skipDiscovery": false,  // If already qualified
    "emphasizeValue": true,  // If price objection likely
    "urgentClose": false     // If hot lead
  }
}
```

### 3. Enhanced Intel Brief

```javascript
// Extend /api/ai/intel-brief/:leadId

Add to response:
{
  ...existingBrief,
  "scriptRecommendation": {
    "scriptId": "uuid",
    "scriptName": "Contractor Re-engagement",
    "reason": "Lead went cold 14 days ago, similar leads responded to value-first approach",
    "customTips": [
      "Skip intro - they know RateRight already",
      "Lead with new feature announcement",
      "Ask about their current hiring pain"
    ]
  },
  "callStrategy": {
    "approach": "consultative",  // or "direct", "relationship", "urgent"
    "timeEstimate": "5-7 min",
    "primaryGoal": "Re-engage and book follow-up",
    "fallbackGoal": "Get permission to send case study"
  }
}
```

### 4. Update LiveCopilot to Accept Pre-loaded Data

```jsx
// admin/src/components/LiveCopilot.jsx

New props:
- preloadedIntel: Object (skip API fetch if provided)
- preloadedScript: Object (skip API fetch if provided)
- preloadedSimilarWins: Array

Modified useEffect:
if (preloadedIntel) {
  setIntelBrief(preloadedIntel);
} else {
  loadIntelBrief(); // Existing behavior
}
```

### 5. Script Stage Visibility Component

```jsx
// admin/src/components/ScriptStagesBar.jsx

Props:
- script: Object
- currentStage: string ('opener' | 'discovery' | 'value' | 'objection' | 'close')
- onStageClick: (stage) => void

Render:
- Horizontal bar with 5 stage pills
- Current stage: blue background, white text
- Past stages: green checkmark
- Future stages: gray outline
- Click any stage to jump (manual override)
```

### 6. Persistent Suggestions Panel

```jsx
// admin/src/components/SuggestionsPanel.jsx

Props:
- suggestions: Array of { type, content, timestamp }
- onDismiss: (id) => void
- onPin: (id) => void

Features:
- Collapsible panel on right side during call
- New suggestions slide in at top
- Pinned suggestions stay visible
- History scrollable (last 10)
- Manual dismiss (X button)
```

---

## Database Changes

### None Required

All data structures already exist:
- `lead.ai_intel_brief` - Cached intel brief
- `scripts` table - Script library with stages
- `copilot_sessions` - Previous objections
- `company_intel` / `lead_intel` - Perplexity cache

---

## API Changes

### New Endpoint

```
GET /api/scripts/ai-recommend/:leadId
```

Response:
```json
{
  "success": true,
  "recommendation": {
    "script": { ...fullScript },
    "reason": "AI explanation",
    "confidence": 0.85,
    "customizations": { ... },
    "alternatives": [ ...top3 ]
  }
}
```

### Modified Endpoint

```
GET /api/ai/intel-brief/:leadId
```

Add to response:
```json
{
  ...existing,
  "scriptRecommendation": { ... },
  "callStrategy": { ... }
}
```

---

## Frontend Changes

### New Files

| File | Purpose |
|------|---------|
| `admin/src/pages/CallPrepPage.jsx` | Full-screen pre-call briefing |
| `admin/src/components/ScriptStagesBar.jsx` | Visual script stage indicator |
| `admin/src/components/SuggestionsPanel.jsx` | Persistent suggestions during call |
| `admin/src/components/AIScriptCard.jsx` | Script recommendation with AI reason |

### Modified Files

| File | Changes |
|------|---------|
| `admin/src/App.jsx` | Add route `/call-prep/:leadId` |
| `admin/src/components/LiveCopilot.jsx` | Accept preloaded props, add SuggestionsPanel |
| `admin/src/components/EliteCallUI.jsx` | Add ScriptStagesBar, persistent intel toggle |
| `admin/src/pages/CallList.jsx` | "Call" button → navigate to `/call-prep/:leadId` |
| `admin/src/pages/LeadProfile.jsx` | "Call" button → navigate to `/call-prep/:leadId` |

### Backend Files

| File | Changes |
|------|---------|
| `src/routes/scripts.js` | Add `/ai-recommend/:leadId` endpoint |
| `src/routes/ai.js` | Extend intel-brief with script recommendation |
| `src/services/ai.js` | Add `recommendScriptForLead()` function |

---

## Implementation Steps

### Phase 1: Backend - AI Script Recommendation
- [ ] 1.1 Create `recommendScriptForLead()` in `src/services/ai.js`
- [ ] 1.2 Add `GET /api/scripts/ai-recommend/:leadId` endpoint
- [ ] 1.3 Extend intel-brief response with script recommendation
- [ ] 1.4 Test endpoint with sample leads

### Phase 2: Frontend - CallPrepPage
- [ ] 2.1 Create `CallPrepPage.jsx` with layout skeleton
- [ ] 2.2 Add route `/call-prep/:leadId` in App.jsx
- [ ] 2.3 Implement parallel data fetching
- [ ] 2.4 Build left panel (AI Intel Brief)
- [ ] 2.5 Build right panel (AI Script Recommendation)
- [ ] 2.6 Build bottom section (Company/Person intel)
- [ ] 2.7 Implement "Start Call" button with preloaded data pass

### Phase 3: Frontend - ScriptStagesBar
- [ ] 3.1 Create `ScriptStagesBar.jsx` component
- [ ] 3.2 Integrate into CallPrepPage (shows all stages)
- [ ] 3.3 Integrate into EliteCallUI (shows current + highlights)
- [ ] 3.4 Add click-to-jump functionality

### Phase 4: Frontend - SuggestionsPanel
- [ ] 4.1 Create `SuggestionsPanel.jsx` component
- [ ] 4.2 Integrate into EliteCallUI
- [ ] 4.3 Add pin/dismiss functionality
- [ ] 4.4 Connect to existing suggestion system

### Phase 5: Integration
- [ ] 5.1 Update LiveCopilot to accept preloaded props
- [ ] 5.2 Update CallList "Call" button to navigate to prep page
- [ ] 5.3 Update LeadProfile "Call" button to navigate to prep page
- [ ] 5.4 Test full flow: CallList → CallPrep → Call → End

### Phase 6: Polish
- [ ] 6.1 Loading skeletons for all sections
- [ ] 6.2 Error states and fallbacks
- [ ] 6.3 Mobile responsive layout
- [ ] 6.4 Keyboard shortcuts (Enter to start call)

---

## UI/UX Specifications

### CallPrepPage Layout

```
┌─────────────────────────────────────────────────────────────┐
│  ← Back    PRE-CALL BRIEF: John Smith    Score: 78 🔥      │
├─────────────────────────────┬───────────────────────────────┤
│                             │                               │
│  AI INTEL BRIEF             │  RECOMMENDED SCRIPT           │
│  ─────────────────          │  ─────────────────────        │
│                             │                               │
│  📋 30-Second Summary       │  📜 Contractor Re-engagement  │
│  "John signed up 3 weeks    │  Success Rate: 72% ✓          │
│  ago but stalled at..."     │                               │
│                             │  WHY THIS SCRIPT:             │
│  💬 Opening Line            │  "Lead went cold, similar     │
│  "Hey John, quick one..."   │  leads responded to..."       │
│  [Copy]                     │                               │
│                             │  ┌─────────────────────────┐  │
│  📝 Talking Points          │  │ ○ Opener                │  │
│  1. Mention new feature     │  │ ○ Discovery             │  │
│  2. Ask about hiring pain   │  │ ○ Value Props           │  │
│  3. Offer case study        │  │ ○ Objections            │  │
│                             │  │ ○ Close                 │  │
│  ⚠️ Predicted Objections    │  └─────────────────────────┘  │
│  • "Too busy" (67%)         │                               │
│    → "Totally get it..."    │  [Expand All Stages]          │
│  • "Already using X" (45%)  │                               │
│    → "Many switched..."     │                               │
│                             │                               │
│  🏆 Similar Wins            │                               │
│  "Contractors in plumbing   │                               │
│  converted when we..."      │                               │
│                             │                               │
├─────────────────────────────┴───────────────────────────────┤
│  📊 Company Intel (expand)  │  👤 Person Intel (expand)     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                    [ 📞 START CALL ]                        │
│                     (green, pulsing)                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Mobile Layout (Stacked)

```
┌─────────────────────────┐
│ ← PRE-CALL: John Smith  │
├─────────────────────────┤
│ AI INTEL BRIEF          │
│ ───────────────         │
│ 30-sec summary...       │
│ Opening line [Copy]     │
│ Talking points...       │
│ Objections...           │
├─────────────────────────┤
│ SCRIPT: Re-engagement   │
│ ───────────────         │
│ [Opener] [Disc] [Value] │
│ [Objection] [Close]     │
│ (horizontal scroll)     │
├─────────────────────────┤
│ [Expand: Company Intel] │
│ [Expand: Person Intel]  │
├─────────────────────────┤
│   [ 📞 START CALL ]     │
└─────────────────────────┘
```

### ScriptStagesBar (During Call)

```
┌─────────────────────────────────────────────────────────┐
│  ✓ Opener  │  ● Discovery  │  ○ Value  │  ○ Obj  │  ○ Close  │
│   (done)   │   (current)   │  (next)   │         │           │
└─────────────────────────────────────────────────────────┘
```

### SuggestionsPanel (During Call)

```
┌─────────────────────────┐
│ SUGGESTIONS         [−] │
├─────────────────────────┤
│ 🟢 Buying Signal (2m)   │
│ "Mentioned budget..."   │
│ → Ask about timeline    │
│                    [📌] │
├─────────────────────────┤
│ 🟡 Objection (5m)       │
│ "Too expensive"         │
│ → "Compared to agencies │
│    you'd pay 30%..."    │
│                    [📌] │
├─────────────────────────┤
│ [Show older suggestions]│
└─────────────────────────┘
```

---

## AI Prompt for Script Recommendation

```javascript
const prompt = `You are a sales coach for RateRight, an Australian worker marketplace.

Analyze this lead and recommend the best script from the library.

LEAD CONTEXT:
- Name: ${lead.first_name} ${lead.last_name}
- Type: ${lead.lead_type} (${lead.lead_type === 'worker' ? 'looking for work' : 'hiring workers'})
- Score: ${lead.score}/100
- Status: ${lead.status}
- Days since last contact: ${daysSinceContact}
- Total communications: ${commsCount}

COMMUNICATION HISTORY:
${recentComms.map(c => `- ${c.direction}: "${c.content?.substring(0, 100)}..."`).join('\n')}

PREVIOUS OBJECTIONS ENCOUNTERED:
${previousObjections.map(o => `- "${o.objection}" (${o.wasOvercome ? 'overcome' : 'not overcome'})`).join('\n')}

SIMILAR WINS (leads like this who converted):
${similarWins.map(w => `- ${w.pattern}: "${w.what_worked}"`).join('\n')}

AVAILABLE SCRIPTS:
${scripts.map(s => `- "${s.name}" (${s.category}, success rate: ${s.success_rate}%): ${s.description}`).join('\n')}

Based on this analysis, recommend the BEST script and explain why.

Respond in JSON:
{
  "recommendedScriptId": "uuid of best script",
  "reason": "2-3 sentence explanation of why this script fits",
  "confidence": 0.0-1.0,
  "customizations": {
    "skipOpener": boolean,  // true if lead already knows RateRight
    "emphasizeValue": boolean,  // true if price sensitivity detected
    "urgentClose": boolean,  // true if hot lead
    "focusAreas": ["discovery", "value"]  // which stages to emphasize
  },
  "alternativeScriptIds": ["uuid1", "uuid2"]  // backup options
}`;
```

---

## Success Metrics

| Metric | Current | Target |
|--------|---------|--------|
| Time to first word after connect | 2-3 sec | 0 sec |
| Intel visibility during call | 30% (collapsed) | 100% (visible) |
| Script recommendation accuracy | N/A (no AI) | Track success rate |
| Clicks to start call | 2-3 | 1 |
| Suggestion reference rate | Low (auto-dismiss) | High (persistent) |

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| AI recommendation takes too long | Pre-fetch on CallList load, cache on lead |
| Wrong script recommended | Show alternatives, allow manual selection |
| Too much info overwhelms user | Collapsible sections, progressive disclosure |
| Mobile layout too cramped | Stacked layout with horizontal stage scroll |

---

## Out of Scope (Future)

- Voice-activated script stage advancement ("next section")
- Real-time script effectiveness learning
- A/B testing different scripts for same lead type
- Script builder with AI assistance

---

## Ready for CC2

**Blockers:** None

**Notes for CC2:**
- Start with backend (AI script recommendation endpoint)
- Use GPT-4o-mini for cost efficiency
- CallPrepPage is a new route, not a modal
- LiveCopilot already accepts lead prop - extend with preloaded data
- Test with different lead types (worker vs contractor)
- Mobile-first but desktop layout is important too

---

**Plan saved:** `docs/pre-call-briefing-plan.md`
**Ready for CC2:** Yes