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.