Initial commit

2025-11-29 17:55:08 +08:00
commit 30e333bf4e
9 changed files with 1435 additions and 0 deletions
--- a/commands/analyze-interviews.md
+++ b/commands/analyze-interviews.md
@@ -0,0 +1,364 @@
+---
+description: Extract themes and insights from interview transcripts with intelligent agent scaling
+argument-hint: [output-name] [transcripts-directory] [--context-file]
+---
+
+# Analyze Interview Transcripts
+
+Analyze all interview transcripts in a directory, extract themes, rank insights, and generate a comprehensive report.
+
+## Step 1: Discover and Validate Transcripts
+
+**Scan the transcripts directory ($2):**
+- Find all text files (.txt, .md, .doc, .docx)
+- Count total transcripts
+- Calculate total file size and estimated token count
+- Identify any context files (ICP, research goals, methodology docs)
+
+**Look for context file ($3):**
+- If --context-file argument provided, read that file
+- If not provided, look for common files in directory:
+  - `icp.md` or `ideal-customer-profile.md`
+  - `research-goals.md` or `objectives.md`
+  - `methodology.md`
+  - `customer-profile.md` or `persona.md`
+
+**Report to user:**
+```markdown
+## 📁 Transcripts Discovered
+
+**Directory:** $2
+**Transcripts found:** [number] files
+**Total size:** [size in MB]
+**Estimated tokens:** ~[number]k tokens
+
+**Files:**
+- [filename 1] ([size])
+- [filename 2] ([size])
+- [etc.]
+
+**Context documents found:**
+- [ICP/research goals/methodology if found, or "None"]
+
+Would you like to proceed with analysis?
+```
+
+**Wait for user confirmation.**
+
+---
+
+## Step 2: Determine Agent Scaling Strategy
+
+Based on workload, intelligently determine how many parallel agents to use:
+
+**Agent Scaling Logic:**
+
+```
+If 1-3 transcripts:
+  → Use 1 agent (sequential analysis is fine)
+
+If 4-8 transcripts:
+  → Use 3 parallel agents
+  → Divide transcripts evenly (e.g., Agent 1: transcripts 1-3, Agent 2: 4-6, Agent 3: 7-8)
+
+If 9-15 transcripts:
+  → Use 5 parallel agents
+  → Divide transcripts evenly
+
+If 16+ transcripts:
+  → Use 8 parallel agents (optimal for most systems)
+  → Divide transcripts evenly
+
+ALSO consider total token count:
+If total tokens > 150k:
+  → Increase agent count by 1-2
+  → Example: 6 transcripts but 200k tokens → use 5 agents instead of 3
+
+If total tokens < 30k:
+  → Decrease agent count
+  → Example: 10 short transcripts with 25k tokens → use 3 agents instead of 5
+```
+
+**Present strategy to user:**
+```markdown
+## 🤖 Agent Strategy
+
+Based on [number] transcripts totaling ~[number]k tokens, I recommend using **[number] parallel agents** for efficient analysis.
+
+**How it works:**
+- Each agent will analyze [number] transcripts
+- Agents work simultaneously (faster than sequential)
+- All findings will be synthesized into final report
+
+**Agent assignments:**
+- Agent 1: [transcript names]
+- Agent 2: [transcript names]
+- [etc.]
+
+**Estimated time:** [minutes] minutes
+
+Would you like to:
+1. ✅ Proceed with this strategy
+2. 🔄 Adjust agent count (tell me your preference)
+3. ❌ Cancel
+```
+
+**Wait for user approval or adjustment.**
+
+---
+
+## Step 3: Launch Theme Extraction Agents
+
+For each agent, use the Task tool with the **theme-extractor** agent:
+
+**Provide each agent with:**
+- Its assigned transcripts (full text)
+- Context file contents (if available)
+- Instructions to identify 3-5 major themes
+- Request supporting quotes for each theme
+
+**Track progress:**
+```markdown
+## 🔍 Extracting Themes
+
+- ✅ Agent 1: Complete (found 4 themes)
+- ✅ Agent 2: Complete (found 5 themes)
+- 🔄 Agent 3: In progress
+- ⏳ Agent 4: Pending
+- ⏳ Agent 5: Pending
+```
+
+**Once all agents complete, collect results:**
+- All themes from all agents
+- Supporting quotes
+- Frequency counts (how many transcripts mentioned each theme)
+
+---
+
+## Step 4: Synthesize and Rank Themes
+
+Use the **insight-ranker** agent to:
+
+**Consolidate themes:**
+- Merge duplicate/similar themes across agents
+- Example: "Pricing concerns" + "Cost barriers" → "Pricing and cost concerns"
+
+**Rank themes by:**
+1. **Frequency** - How many transcripts mentioned it
+2. **Relevance** - Alignment with ICP/research goals (if context provided)
+3. **Impact** - Magnitude of the insight (pain point severity, opportunity size)
+
+**Present ranked themes to user:**
+```markdown
+## 🎯 Top Themes Identified
+
+### Theme 1: [Theme Name]
+**Mentioned in:** [X] of [Y] transcripts ([percentage]%)
+**Relevance:** [High/Medium/Low based on ICP]
+**Key insight:** [One sentence summary]
+
+**Representative quote:**
+> "[Quote from transcript]"
+> — Participant [number/name]
+
+---
+
+### Theme 2: [Theme Name]
+[Same format...]
+
+---
+
+[Continue for top 5-7 themes]
+
+---
+
+**Would you like me to:**
+1. ✅ Proceed with final report generation
+2. 🔎 Deep dive into specific themes (tell me which ones)
+3. 🔄 Re-rank themes with different criteria
+```
+
+**Wait for user feedback.**
+
+---
+
+## Step 5: Generate Comprehensive Report
+
+Create a structured markdown report with:
+
+### Report Structure
+
+```markdown
+# Interview Analysis Report: [Output Name]
+
+**Analysis date:** [Date]
+**Transcripts analyzed:** [Number]
+**Context:** [ICP/research goals summary if available]
+
+---
+
+## Executive Summary
+
+[2-3 paragraph overview of most important findings]
+
+---
+
+## Methodology
+
+**Transcripts:**
+- [List of transcripts with dates if available]
+
+**Analysis approach:**
+- [Number] parallel agents
+- Theme extraction and consolidation
+- Ranking by frequency and relevance
+
+**Context documents:**
+- [List context files if used]
+
+---
+
+## Key Themes
+
+### 1. [Theme Name] ([frequency]% of interviews)
+
+**Summary:** [Detailed explanation of this theme]
+
+**Why it matters:** [Relevance to ICP/business goals]
+
+**Supporting quotes:**
+1. "[Quote]" — Participant [ID]
+2. "[Quote]" — Participant [ID]
+3. "[Quote]" — Participant [ID]
+
+**Recommendations:**
+- [Actionable insight 1]
+- [Actionable insight 2]
+
+---
+
+[Repeat for each major theme]
+
+---
+
+## Cross-Cutting Insights
+
+[Patterns that span multiple themes]
+
+---
+
+## Recommendations
+
+1. **[Priority]** [Recommendation based on findings]
+2. **[Priority]** [Recommendation based on findings]
+[etc.]
+
+---
+
+## Appendix: All Themes
+
+[Comprehensive list of all themes found, including lower-frequency ones]
+
+---
+
+**Analysis performed by:** Interview Transcript Analyzer plugin for Claude Code
+**Generated:** [Timestamp]
+```
+
+**Save report to:** `analysis/$1-analysis.md`
+
+---
+
+## Step 6: Deliver Results
+
+**Report to user:**
+```markdown
+## ✅ Analysis Complete!
+
+**Report location:** analysis/$1-analysis.md
+**Transcripts analyzed:** [number]
+**Themes identified:** [number] major themes, [number] total
+**Top insights:** [number]
+
+**Report sections:**
+- Executive Summary
+- Methodology
+- [Number] Key Themes (with quotes and recommendations)
+- Cross-cutting insights
+- Actionable recommendations
+
+**Next steps:**
+1. Review the full report
+2. Use `/extract-quotes [theme]` to find more quotes on specific themes
+3. Use `/rank-insights` to re-rank with different criteria
+```
+
+---
+
+## Error Handling
+
+**If no transcripts found:**
+```
+❌ No transcripts found in directory: $2
+
+Please ensure:
+- Directory path is correct
+- Transcripts are in supported formats (.txt, .md, .doc, .docx)
+- Files are readable
+
+Expected structure:
+  interviews/
+    ├── interview-1.txt
+    ├── interview-2.txt
+    └── context/
+        └── icp.md
+```
+
+**If context file specified but not found:**
+```
+⚠️ Warning: Context file not found: $3
+
+Would you like to:
+1. Proceed without context (insights won't be ranked by ICP relevance)
+2. Specify a different context file
+3. Cancel and add context file first
+```
+
+**If agent fails during analysis:**
+- Save partial results from completed agents
+- Report which agent failed and why
+- Offer to retry with fewer agents or different allocation
+
+---
+
+## Usage Examples
+
+```bash
+# Basic analysis
+/analyze-interviews customer-feedback ./interviews/
+
+# With ICP context for relevance ranking
+/analyze-interviews product-research ./research/transcripts/ --context-file ./research/icp.md
+
+# Large-scale analysis (automatically uses more agents)
+/analyze-interviews enterprise-study ./enterprise-interviews/
+```
+
+---
+
+## Tips for Best Results
+
+**Organize transcripts clearly:**
+- Use descriptive filenames (`interview-customer-name.txt`)
+- Include dates if relevant (`2024-01-15-interview-acme-corp.txt`)
+- Keep transcripts in dedicated directory
+
+**Provide context:**
+- ICP document helps rank insights by relevance
+- Research goals ensure findings align with objectives
+- Methodology doc helps interpret findings appropriately
+
+**For large datasets:**
+- The plugin will automatically scale agents (no manual config needed)
+- More transcripts = more agents = faster analysis
+- Expected speed: ~15-20 transcripts in 15-20 minutes with 8 agents