STORYTELLING_QUICK_START.md

# Market Research Storytelling - Quick Start Guide

## What's New?

Your TranscriptorAI now generates **professional market research reports** that tell compelling, data-driven stories for business clients.

---

## Key Changes in 3 Bullets

1. **Reports now sound like consulting firms**, not research papers - business language, "So What?" orientation, clear action items
2. **Participant quotes are automatically extracted and integrated** - brings findings to life with authentic human voice
3. **Professional visual elements** - stat callouts, insight boxes, quote highlights, color-coded priority recommendations

---

## Before & After Example

### BEFORE (Academic Style):
```
Summary of Findings

This analysis includes 12 HCP transcripts with an average quality score of 0.82.

Strong Consensus Findings:
- 10 out of 12 participants (83%) mentioned reimbursement challenges

Majority Findings:
- 8 out of 12 participants (67%) discussed efficacy concerns
```

### AFTER (Market Research Style):
```
Executive Summary

THE HEADLINE: Prior authorization delays are creating a 6-month sales cycle gap
and pushing HCPs toward competitor products with faster approvals.

KEY TAKEAWAYS:
• Reimbursement Barrier: 10 of 12 HCPs (83%) cite prior authorization as their
  #1 prescribing barrier → Your sales team needs patient assistance resources
  during the 4-6 week approval window → Launch patient bridge program (IMMEDIATE)

  As one oncologist noted: "By the time insurance approves, the patient's
  cancer has often progressed to the point where we need more aggressive options."

• Competitive Threat: 7 of 12 HCPs (58%) mention switching to Competitor X
  specifically due to their co-pay card program → Market share at risk without
  similar offering → Evaluate co-pay assistance program (WITHIN 60 DAYS)
```

---

## How To Use

### Option 1: Standard Analysis (App Tab 1)
1. Upload transcripts as usual
2. Select interviewee type (HCP/Patient/Other)
3. Click "Analyze Transcripts"
4. **NEW:** Reports now automatically include quotes and business-focused language
5. Download CSV and PDF as before

**What's Different:**
- Summary text now has "THE HEADLINE" and business implications
- PDF has visual callout boxes for key stats
- Quotes are woven into findings

### Option 2: Narrative Report (App Tab 2)
1. First run analysis in Tab 1
2. Go to "Narrative Report" tab
3. Upload the CSV from step 1
4. Select report style:
   - **Executive**: Concise, C-level focused (best for stakeholder presentations)
   - **Detailed**: Comprehensive analysis (best for product/marketing teams)
   - **Presentation**: Slide-ready format (best for sales enablement)
5. Click "Generate Narrative Report"
6. Download PDF, Word, or HTML

**What's Different:**
- Reports follow management consulting structure
- 5-8 participant quotes integrated throughout
- Visual elements: stat callouts, quote boxes, priority recommendations
- Actionable recommendations with timelines (IMMEDIATE/30d/90d)

---

## Report Structure (New Format)

```
📄 EXECUTIVE SUMMARY
   └─ THE HEADLINE: One sentence, most important finding
   └─ KEY TAKEAWAYS: 3-4 bullets (finding → implication → action)

📄 RESEARCH CONTEXT
   └─ Who we spoke with, data quality

📄 KEY INSIGHTS (3-5 sections)
   └─ Each finding with:
      • Specific numbers and percentages
      • Business implication ("why this matters")
      • Supporting quote from participant
      • Connection to competitive landscape

📄 MARKET OPPORTUNITIES & BARRIERS
   └─ Unmet needs (with frequency)
   └─ Competitive vulnerabilities
   └─ White space opportunities

📄 PARTICIPANT PERSPECTIVES
   └─ Points of consensus (80%+ agreement)
   └─ Areas of divergence (where opinions split)
   └─ Notable outliers and why they matter

📄 STRATEGIC RECOMMENDATIONS
   ├─ 🔴 IMMEDIATE: Launch patient bridge program
   ├─ 🟠 WITHIN 30 DAYS: Develop early follow-up protocol
   └─ 🟡 WITHIN 90 DAYS: Evaluate co-pay assistance program
```

---

## Visual Elements (Automatically Added to PDFs)

### 1. Key Stat Callouts
Large, bold numbers with context - perfect for opening the report

```
┌─────────────────────────────────┐
│                                 │
│              12                 │
│   HCPs Interviewed              │
│ In-depth qualitative research   │
│                                 │
└─────────────────────────────────┘
```

### 2. Quote Boxes
Participant voice highlighted and styled

```
┌─────────────────────────────────────┐
│ "By the time insurance approves,    │
│  the disease has often progressed." │
│                                      │
│            — Oncologist, Transcript 3│
└─────────────────────────────────────┘
```

### 3. Recommendation Boxes
Color-coded by priority for quick scanning

```
┌────────┬──────────────────────────────────┐
│IMMEDIAT│ Launch patient bridge program    │
│   E    │ Address the 4-6 week prior auth  │
│ (RED)  │ gap identified by 83% of HCPs    │
└────────┴──────────────────────────────────┘
```

---

## Writing Style Rules (What the LLM Now Follows)

**DO:**
- ✅ Lead with impact: "THE HEADLINE: [most important finding]"
- ✅ Active voice: "HCPs prefer..." not "It was found that..."
- ✅ Specific numbers: "8 out of 12 (67%)" not "most"
- ✅ Business implications: Every finding → "What this means for you"
- ✅ Participant quotes: 5-8 per report, naturally integrated
- ✅ Prioritized actions: IMMEDIATE vs. 30 days vs. 90 days
- ✅ Skimmable: Key points visible in headers and first sentences

**DON'T:**
- ❌ Vague language: "many", "most", "some", "often"
- ❌ Academic style: "Findings indicate that..."
- ❌ Data without context: Numbers need interpretation
- ❌ Generic recommendations: "Consider exploring options"
- ❌ Passive voice: "It was observed that..."

---

## Quote Extraction (How It Works Behind the Scenes)

**Automatic Process:**
1. System scans all transcripts after analysis
2. Identifies quotes using patterns:
   - Direct quotes: "quoted text"
   - Speaker labels: `HCP: statement`
   - Narrative references: `As one patient noted, "quote"`
3. Filters out greetings, administrative text, too short/long
4. Scores each quote for storytelling impact (0.0 to 1.0):
   - Higher scores for: emotional language, specific details, numbers, comparisons
   - Lower scores for: generic phrases ("it depends", "maybe")
5. Categorizes by theme (e.g., prescribing, barriers, symptoms, QoL)
6. Selects top 10-15 quotes for inclusion in reports
7. LLM weaves quotes into narrative naturally

**You don't need to do anything** - it happens automatically!

---

## Report Styles Explained

### Executive Style
**Best for:** C-suite, investors, board presentations
**Characteristics:**
- Concise (1000-1200 words)
- ROI focus
- Strategic recommendations
- Minimal methodology detail
- 3-5 key insights maximum

### Detailed Style
**Best for:** Product managers, marketing teams, researchers
**Characteristics:**
- Comprehensive (1400-1600 words)
- Full analysis depth
- All supporting data included
- 4-6 key insights
- Detailed methodology notes

### Presentation Style
**Best for:** Sales teams, field force, client briefings
**Characteristics:**
- Slide-ready format (1200-1400 words)
- Talking points emphasized
- Visual elements maximized
- Key messages highlighted
- Quote-heavy for impact

---

## Troubleshooting

### "Reports still sound too academic"
**Fix:** Make sure you're using the narrative report tab (Tab 2) with report style selected. The basic analysis (Tab 1) is improved but not as dramatically transformed.

### "Not seeing participant quotes in my report"
**Check:**
1. Do your transcripts have speaker labels or quotation marks?
2. Are quotes at least 30 characters long?
3. Check console output for "[Quotes] Extracted X quotes" message
4. Try different transcripts to verify quote extraction is working

### "Visual elements not showing in PDF"
**Try:**
1. Update reportlab: `pip install --upgrade reportlab`
2. Check that all imports succeeded (no errors on startup)
3. Try generating HTML version instead (always works)

### "Recommendations are all labeled 'MEDIUM'"
**Reason:** LLM needs clearer priority signals in the data
**Fix:** In your analysis instructions (Tab 1), mention specific urgency or timing requirements

---

## Tips for Best Results

### 1. Provide Business Context in Analysis Instructions
Instead of:
> "Analyze these HCP interviews"

Try:
> "Analyze these interviews focused on understanding barriers to prescribing.
> Our client needs to know what's blocking sales and what to prioritize for Q1."

### 2. Use the Right Report Style
- Busy executive who'll spend 5 minutes? → **Executive style**
- Team doing deep dive? → **Detailed style**
- Preparing talking points for field team? → **Presentation style**

### 3. Review Quote Quality
Check the console output after analysis:
```
[Quotes] Extracted 47 quotes, top impact score: 0.87
```
- 20-50 quotes extracted is typical for 10-12 transcripts
- Top scores above 0.70 indicate high-quality quotes
- If top score < 0.50, transcripts may lack substantive quotes

### 4. Customize for Client Industry
In analysis instructions, mention:
- Client's industry (pharma, medical device, payer, etc.)
- Competitive landscape
- Specific business questions they need answered

---

## Examples of Good vs. Poor Quotes

### ✅ HIGH IMPACT (Score: 0.85)
```
"By the time insurance approves, the patient's cancer has often progressed
to the point where we need to consider more aggressive options."
```
**Why:** Specific, emotional, causal reasoning, medical detail

### ✅ MEDIUM IMPACT (Score: 0.65)
```
"I've switched three patients to Competitor X this month because
of their co-pay assistance program."
```
**Why:** Specific numbers, comparative, action-oriented

### ❌ LOW IMPACT (Score: 0.30)
```
"It depends on the situation."
```
**Why:** Generic, vague, no detail

### ❌ FILTERED OUT (Not included)
```
"Thank you, that's interesting."
```
**Why:** Administrative, non-substantive

---

## Need Help?

**Documentation:**
- Full details: `MARKET_RESEARCH_ENHANCEMENTS.md`
- This guide: `STORYTELLING_QUICK_START.md`

**Code Reference:**
- Quote extraction logic: `quote_extractor.py`
- Narrative prompts: `story_writer.py` lines 10-100
- Visual elements: `narrative_report_generator.py` lines 19-255

**Common Questions:**
- "Can I disable quotes?" → Yes, they're optional. Edit `app.py` line 242 to skip extraction.
- "Can I adjust quote scoring?" → Yes, edit `score_quote_impact()` in `quote_extractor.py`
- "Can I change visual colors?" → Yes, edit hex codes in `narrative_report_generator.py`

---

## Quick Wins Checklist

- [ ] Run a test analysis with 3-5 transcripts
- [ ] Review the "THE HEADLINE" in the output
- [ ] Check console for "[Quotes] Extracted X quotes" confirmation
- [ ] Generate a narrative report in all 3 styles (executive, detailed, presentation)
- [ ] Compare PDFs to see visual elements (stat callouts, quote boxes, recommendation boxes)
- [ ] Share with one internal stakeholder for feedback
- [ ] Run full production analysis with client transcripts

---

**Ready to create compelling client deliverables!** 🚀

Your reports now tell stories that drive business decisions.