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.