Youtube Analyzer

YouTubeAnalyzer Skill

Purpose: Comprehensive YouTube video analysis with content-type detection, specialized format workflows (tutorial/finance/general/etc.), multi-agent orchestration for long videos, and optional GitHub repo cross-referencing for tutorial content.

Architecture: This file is the orchestration spine — 4 phases with blocking gates. Mechanical detail is progressively disclosed via references/*.md (loaded by phase) and content-analysis rules live in workflows/*.md (passed into sub-agents).

---

Invocation Flags

Parse the user's invocation BEFORE Phase 1. Flags pre-set Phase 2 outputs and suppress the matching prompt.

Syntax accepted (any of these forms):

• --chat <url> — deliver inline, no file written
• --chat: <url> / --chat=<url>
• --document <url> (explicit; default behavior)

Parsing rules: 1. Strip the flag token (and any trailing : or =value) before extracting the URL 2. If a flag was passed: set mode and SKIP Q5 3. Both flags present → last one wins 4. Unknown flags (--foo) → warn user inline, proceed without it

When a flag was detected, surface it: "Flag detected: `--chat` → mode preset to chat (Q5 skipped)."

---

Required External Tools

Verify these are installed before Phase 1. If missing, surface a single install message and stop:

• `yt-dlp` — pip install yt-dlp or brew install yt-dlp
• `youtube_transcript_api` — pip install youtube-transcript-api
• `bun` — curl -fsSL https://bun.sh/install | bash

command -v yt-dlp && command -v youtube_transcript_api && command -v bun

---

Capture invocation cwd

BEFORE Phase 1, capture the working directory the user invoked the skill from. Store as invocationCwd. Used by Step 4.7 (post-save copy prompt).

pwd

Persist that value through all phases. Sub-agents may run elsewhere — only the orchestrator's initial cwd counts.

---

Runtime Requirements

This skill runs from any agent context (the primary thread, or a delegated agent like general-purpose) provided the calling agent has: Agent/Task, AskUserQuestion, Write/Edit, Bash, Read, Grep. Agents lacking any of these (e.g. Explore) should defer — auto-detect via tool availability, not by name.

The terms "the orchestrator" and "the calling agent" both refer to whatever agent is executing this skill.

---

Orchestration Model

The orchestrator NEVER does analysis work directly. All content extraction, processing, and writing is delegated to specialized sub-agents via the Task tool. The orchestrator coordinates, routes, and writes files (in mode == "document") once results return.

EVERY phase has a BLOCKING GATE. Do not proceed until the gate checklist is satisfied.

---

PHASE 1: SOURCE SELECTION

BLOCKING GATE 1

PRE-CONDITIONS: External tools verified
MANDATORY OUTPUTS:
  - transcriptPath: string     # Path to loaded clean transcript file
  - transcriptSource: string   # "yt-dlp" | "youtube_transcript_api"
  - videoMetadata: object      # { title, channel, duration?, upload_date?, video_id?, topic? }
  - wordCount: number          # Estimated word count
  - transcriptQuality: string  # "HIGH" | "MEDIUM" | "NONE" | "UNAVAILABLE"

Mechanics: Read references/source-selection.md. It covers URL extraction, the 4-tier transcript fallback chain, and VTT cleanup.

Auto-detect: If the user already provided a YouTube URL, skip the URL prompt and go directly to metadata extraction.

Gate 1 checklist (verify ALL):

• [ ] transcriptPath exists and is readable
• [ ] transcriptSource is set
• [ ] videoMetadata.title and videoMetadata.channel are non-empty
• [ ] wordCount > 0
• [ ] transcriptQuality is set

"Phase 1 complete. {wordCount} words loaded from {transcriptSource}. Proceeding to config..."

---

PHASE 2: INTERACTIVE CONFIG

BLOCKING GATE 2

PRE-CONDITIONS:
  - transcriptPath exists and is readable
  - videoMetadata is populated (title + channel at minimum)
MANDATORY OUTPUTS:
  - category: string            # business, finance, technology, etc.
  - format: string              # tutorial | course | finance | interview | lecture | general
  - outputSelection: string[]   # Selected output types
  - depth: string               # "quick" | "standard" | "deep"
  - focusArea: string           # Format-specific focus (or "none")
  - repoUrl: string | null      # GitHub repo URL (tutorials only)
  - confidence: number          # Detection confidence percentage
  - mode: string                # "document" | "chat" — see Q5 (or pre-set by flag)

Q1: Content Type Confirmation

Detection: Run the content-type detector with metadata extracted in Phase 1:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/detect-content-type.ts --url "URL"
# OR pipe metadata JSON
echo '{"title":"...","description":"...","tags":[...]}' | bun run ${CLAUDE_PLUGIN_ROOT}/scripts/detect-content-type.ts --json

If confidence < 60%, present alternatives. See content-types.md for full keyword lists and scoring.

{
  "questions": [{
    "question": "I detected this as {category}/{format} ({X}% confidence). Is that correct?",
    "header": "Content type",
    "options": [
      {"label": "Yes, proceed", "description": "Use {category}/{format} as detected"},
      {"label": "Change category", "description": "Keep {format} format, pick a different category"},
      {"label": "Change format", "description": "Keep {category} category, pick a different format"},
      {"label": "Change both", "description": "Select both category and format manually"}
    ],
    "multiSelect": false
  }]
}

Q2: Output Selection (multiSelect: true)

The available options depend on format:

tutorial / course: Detailed Summary · Production Checklist · Tool/Package Inventory · Key Quotes finance: Strategy Breakdown · Action Items · Risk Analysis · Key Quotes general / interview / lecture: Detailed Summary · Deep Analysis · Key Insights · Key Quotes

Default if user says "all" or doesn't specify: Detailed Summary + Key Quotes.

Q3: Output Depth

A) Quick (~500w) · B) Standard (~1500w, recommended) · C) Deep dive (~3000w+)

Q4: Format-Specific

• Tutorial / Course: "GitHub repo for this tutorial? Paste URL or skip." (stored as repoUrl)
• Finance: "Actionable takeaways or theoretical analysis?"
• General / Interview / Lecture: "Any specific angle to emphasize?"

Q5: Delivery Mode

SKIP this question entirely if `mode` was pre-set by an invocation flag. Otherwise:

{
  "questions": [{
    "question": "How should the analysis be delivered?",
    "header": "Delivery",
    "options": [
      {"label": "Save to disk", "description": "Default — write a permanent markdown file at the resolved output directory. Best when you want to reference this later."},
      {"label": "Discuss in chat", "description": "Run the full analysis but return the rendered markdown inline so we can talk through it. No file is created."}
    ],
    "multiSelect": false
  }]
}

Map: Save to disk → mode = "document"; Discuss in chat → mode = "chat". Default: mode = "document".

Gate 2 checklist (verify ALL):

• [ ] category is a valid category from content-types.md
• [ ] format is one of: tutorial, course, finance, interview, lecture, general
• [ ] outputSelection has ≥1 item
• [ ] depth is set
• [ ] focusArea is set (can be "none")
• [ ] repoUrl is a string or null
• [ ] mode is "document" or "chat"

"Phase 2 complete. {category}/{format} at {confidence}% confidence. Depth: {depth}. Outputs: {outputSelection}. Mode: {mode}. Proceeding to scaling..."

---

PHASE 3: MULTI-AGENT SCALING + REPO EXPLORATION

BLOCKING GATE 3

PRE-CONDITIONS:
  - category, format, outputSelection, depth all set
  - transcriptPath exists
MANDATORY OUTPUTS:
  - partitionStrategy: string         # "single" | "multi"
  - agentCount: number                # 1 for single, 2+ for multi
  - chunkPaths: string[]              # Chunk file paths
  - repoExploreResults: object | null # Mermaid diagrams from repo exploration

Mechanics: Read references/scaling-and-repo-explore.md. It covers token estimation, the scaling decision table (≤30K / 30–100K / >100K), partition execution, and the 3-explorer parallel repo exploration (StructureExplorer, DependencyExplorer, PatternExplorer — all subagent_type: Explore).

Trigger for repo exploration: repoUrl is non-null AND format is tutorial or course. Run in parallel with transcript partitioning.

Gate 3 checklist (verify ALL):

• [ ] partitionStrategy is set
• [ ] agentCount ≥ 1
• [ ] chunkPaths has ≥1 path; each path exists and is readable
• [ ] repoExploreResults is set (object or null)
• [ ] If repoUrl was provided, either repoExploreResults has content OR a skip reason is documented

"Phase 3 complete. {agentCount} agent(s) ready. {repoExploreResults ? 'Repo exploration complete with Mermaid diagrams.' : ''} Dispatching {format} workflow..."

---

PHASE 4: WORKFLOW DISPATCH + SYNTHESIS

BLOCKING GATE 4

PRE-CONDITIONS:
  - All Gate 3 outputs satisfied
  - category, format, outputSelection, depth, focusArea, mode all set
MANDATORY OUTPUTS:
  - workflowLoaded: string                # Workflow file that was loaded
  - outputPath: string | null             # Canonical output path (null when mode == "chat")
  - renderedMarkdown: string | null       # Rendered markdown (populated when mode == "chat")
  - copyPath: string | null               # Optional cwd copy path from Step 4.7 (null if declined or chat mode)

Final-phase reporting (branch on mode):

If mode == "document" AND copyPath is set: "Analysis complete. Saved to {outputPath}. Copy also at {copyPath}."

If mode == "document" AND copyPath is null: "Analysis complete. Saved to {outputPath}."

If mode == "chat": "Analysis complete — rendered below for discussion. No file written." Then print renderedMarkdown inline so it enters the conversation context.

---

Step 4.1: Dispatch

Dispatch table:

Why `general-purpose` on `sonnet`: Workflow agents follow precise file instructions to extract structured data and produce markdown. general-purpose executes workflow instructions directly without loading specialized agent personalities.

Pre-dispatch verification: 1. Format maps to a valid workflow file in the table above 2. Read the workflow file contents 3. Agent prompt includes the full workflow file 4. Agent receives: chunk path + user config + video metadata 5. subagent_type: "general-purpose" and model: "sonnet" set explicitly

Step 4.2: Launch Workflow Agents

Per chunk, launch a Task agent with subagent_type: "general-purpose", model: "sonnet". Each agent receives: 1. Its chunk file path (or full transcript if single agent) 2. User config: { category, format, outputSelection, depth, focusArea } 3. Video metadata: { title, channel, duration, upload_date, video_id } 4. Workflow instructions (full content of the appropriate workflows/*.md) 5. Instruction: "Analyze ONLY your assigned chunk. Do not read beyond your assigned content."

Parallel: if agentCount > 1, launch ALL chunk agents in parallel (single message, multiple Task calls).

Step 4.3: Synthesis

Launch ONE synthesis agent (general-purpose, sonnet) with a fresh context. Pass it references/output-templates.md (YAML frontmatter, Production Checklist section, Ground Truth Architecture section, Package Version table) so it can apply the templates without polluting the orchestrator context.

Synthesis agent receives: 1. Merged chunk analysis results 2. User config (including mode) 3. Video metadata 4. repoExploreResults if non-null (Mermaid diagrams) 5. Target output path — only if mode == "document"; pass null for chat 6. Contents of references/output-templates.md

Synthesis agent does: 1. Merge + deduplicate chunk analyses 2. Apply output template based on format + outputSelection 3. Generate YAML frontmatter 4. If tutorial + repoExploreResults: add Ground Truth Architecture section with Mermaid diagrams 5. Tutorials: extract package list for the package database (always — runs regardless of mode) 6. Branch on mode:

• mode == "document" → write file to output path. Return { outputPath, renderedMarkdown: null, wordCount, packagesFound[] }
• mode == "chat" → skip file write. Return { outputPath: null, renderedMarkdown: <full markdown including frontmatter>, wordCount, packagesFound[] }. Orchestrator prints renderedMarkdown inline.

Step 4.4: Package DB Integration (Tutorials Only)

For each package found:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/package-db.ts add \
  --name "{packageName}" --display-name "{displayName}" \
  --version-mentioned "{version}" --category "{packageCategory}" \
  --source "{videoUrl}"

The package database lives at ~/.config/youtube-analyzer/package-db.json (created on first use).

Version lookup (post-analysis, batches of 5; skip packages checked within 7 days):

• npm: WebFetch on https://registry.npmjs.org/{pkg}/latest
• PyPI: WebFetch on https://pypi.org/pypi/{pkg}/json
• Other: WebSearch

Update the package database with --latest-version. Status thresholds and the Package Version table format live in references/output-templates.md. Schema details: package-database-schema.md.

Step 4.5: Output Path Resolution

Skip this step entirely when `mode == "chat"` — set outputPath = null and continue to cleanup.

For mode == "document": read references/output-paths.md. The skill resolves the output directory from ${CLAUDE_PROJECT_DIR}/.claude/youtube-analyzer.local.md if present, otherwise prompts the user once via AskUserQuestion and persists the answer there for next time.

Step 4.6: Cleanup

rm -rf "{scratchpad}/repo-explore/"

Step 4.7: Optional Copy to Invocation Cwd

Skip when `mode == "chat"` — no file exists to copy. Set copyPath = null.

After the canonical file is written and cleanup is done, ask the user whether to also drop a copy in the cwd captured at skill invocation. Use AskUserQuestion:

{
  "questions": [{
    "question": "Also save a copy to the project you ran this from? Cwd: {invocationCwd}",
    "header": "Copy to repo",
    "options": [
      {"label": "No, just the configured output dir", "description": "File stays at {outputPath} only. No copy created."},
      {"label": "Yes, copy to cwd root", "description": "Drop a copy at {invocationCwd}/{filename}"},
      {"label": "Yes, custom subpath", "description": "I'll specify a subdirectory under {invocationCwd}"}
    ],
    "multiSelect": false
  }]
}

Branch on response:

• No → copyPath = null. Done.
• Yes, copy to cwd root → targetDir = invocationCwd. Proceed to copy.
• Yes, custom subpath → ask one follow-up free-text question: "Subpath under `{invocationCwd}` (e.g., `docs/research`, leave blank for cwd root):". Resolve targetDir = invocationCwd + (subpath || ""). Proceed to copy.

Copy execution:

mkdir -p "{targetDir}"
cp "{outputPath}" "{targetDir}/{filename}"

Set copyPath = "{targetDir}/{filename}".

Safety guards:

• If invocationCwd is unset (rare — only if cwd capture failed), skip the prompt and set copyPath = null.
• If invocationCwd equals the configured output directory, skip the prompt — copying onto itself is a no-op.
• If the destination file already exists, append -2, -3, etc. to the filename rather than overwriting.

---

Example

Input: "Analyze this video: https://youtube.com/watch?v=xyz123"

• Phase 1: Auto-detect URL → yt-dlp metadata → youtube_transcript_api transcript → 12K words.
• Phase 2: Detect finance/finance at 87%. User confirms. Selects: Strategy Breakdown + Action Items. Depth: standard. Focus: actionable takeaways.
• Phase 3: 12K tokens → single agent. No repo exploration.
• Phase 4: 1 FinanceAgent analyzes full transcript. Synthesis writes to {configured-output-dir}/2026-04-27-dividend-portfolio-strategy.md. Step 4.7 then asks whether to copy a duplicate into invocationCwd.

For --chat invocation, Phase 4 returns renderedMarkdown inline, skips Steps 4.5 and 4.7, and never writes a file.

---

Quick Reference

Scripts (in ${CLAUDE_PLUGIN_ROOT}/scripts/): clean-transcript.ts, detect-content-type.ts, partition-transcript.ts, package-db.ts · External: yt-dlp, youtube_transcript_api, bun

Agent types:

• Workflow agents: general-purpose + sonnet, given full workflow file content
• Repo explorers: Explore (Structure / Dependency / Pattern)
• Synthesizer: general-purpose + sonnet, given merged results + references/output-templates.md

Workflow files: workflows/{tutorial,finance,general,repo-exploration}-workflow.md

Sequence: verify external tools → Phase 1 (Gate 1) → Phase 2 (Gate 2) → Phase 3 (Gate 3) → Phase 4 (Gate 4) → report. No phase may be skipped.

YouTube Content Type Detection System

Purpose: Two-dimensional classification system for routing YouTube video analysis to the correct output location and analysis workflow.

CRITICAL CONFIDENCE RULE: If detection confidence is below 60%, you MUST present the top 2-3 alternatives to the user via AskUserQuestion and let them choose. Do NOT auto-classify with low confidence. Ties in top scores also require user confirmation. This is enforced by BLOCKING GATE 2 in SKILL.md.

---

Two-Dimensional Classification

YouTube content is classified along two independent axes:

1. Category Axis - Determines WHERE the output is saved 2. Format Axis - Determines HOW the content is analyzed

Example:

• Video: "React 19 Tutorial - Build a Full Stack App"
• Category: technology (used in YAML frontmatter and as a suggested subdirectory if you organize hierarchically)
• Format: tutorial → uses workflows/tutorial-workflow.md for analysis

Note: in this plugin, the actual output directory is resolved from .claude/youtube-analyzer.local.md (set on first run). Category and format do NOT change the destination directory — they only affect YAML frontmatter and the workflow chosen.

---

Axis 1: Category (Topic Classification)

Category labels the topical area of the video. It's recorded in the analysis YAML frontmatter and can be used as a suggested subdirectory if the user organizes their output directory hierarchically.

---

Axis 2: Format (Analysis Workflow)

Format determines which specialized workflow analyzes the content.

---

Category Detection Keywords

Each category has weighted keywords for classification. Title gets 3x weight, description 2x, tags 1x, channel 2x.

Business

Keywords:

[
  "entrepreneur", "entrepreneurship", "startup", "business", "management",
  "leadership", "strategy", "marketing", "sales", "growth",
  "scale", "scaling", "revenue", "profit", "business model",
  "CEO", "founder", "company", "enterprise", "operations",
  "team building", "hiring", "HR", "culture", "productivity",
  "negotiation", "deal", "partnership", "acquisition", "exit"
]

Known Channels:

• Gary Vaynerchuk
• Simon Sinek
• Y Combinator
• Startup Grind
• How I Built This

---

Education

Keywords:

[
  "learn", "learning", "study", "course", "class",
  "lesson", "education", "teach", "training", "skill",
  "master", "mastery", "beginner", "intermediate", "advanced",
  "tutorial", "guide", "walkthrough", "step by step", "how to",
  "exam", "test", "certification", "degree", "academic",
  "university", "college", "school", "student", "professor"
]

Known Channels:

• Khan Academy
• Crash Course
• TED-Ed
• Coursera
• edX

---

Entertainment

Keywords:

[
  "game", "gaming", "gameplay", "playthrough", "stream",
  "movie", "film", "TV", "show", "series",
  "review", "reaction", "trailer", "cinema", "entertainment",
  "comedy", "funny", "humor", "sketch", "parody",
  "music", "song", "concert", "performance", "artist",
  "pop culture", "celebrity", "viral", "meme", "trending"
]

Known Channels:

• PewDiePie
• IGN
• GameSpot
• Red Letter Media
• Dunkey

---

Finance

Keywords:

[
  "invest", "investing", "investment", "portfolio", "stock",
  "dividend", "dividends", "passive income", "FIRE", "financial independence",
  "margin", "options", "trading", "market", "bull market",
  "bear market", "recession", "inflation", "fed", "interest rate",
  "401k", "IRA", "retirement", "wealth", "money",
  "ETF", "mutual fund", "index fund", "bond", "real estate",
  "crypto", "bitcoin", "ethereum", "DeFi", "blockchain",
  "valuation", "earnings", "balance sheet", "cash flow", "P/E ratio"
]

Known Channels:

• Paycheck to Portfolio
• Ticker Symbol: YOU
• Margin Mindset
• Andrei Jikh
• Graham Stephan
• Meet Kevin
• Everything Money

---

Health

Keywords:

[
  "fitness", "workout", "exercise", "training", "gym",
  "nutrition", "diet", "healthy eating", "meal prep", "calories",
  "weight loss", "muscle gain", "cardio", "strength", "yoga",
  "mental health", "therapy", "anxiety", "depression", "wellness",
  "sleep", "meditation", "mindfulness", "stress", "recovery",
  "supplement", "vitamin", "protein", "health", "medical",
  "doctor", "science-based", "evidence", "study", "research"
]

Known Channels:

• Jeff Nippard
• AthleanX
• Dr. Mike Israetel
• Huberman Lab
• FoundMyFitness

---

Politics

Keywords:

[
  "politics", "political", "election", "campaign", "vote",
  "government", "congress", "senate", "house", "president",
  "policy", "legislation", "law", "bill", "regulation",
  "democrat", "republican", "liberal", "conservative", "progressive",
  "foreign policy", "diplomacy", "war", "military", "defense",
  "immigration", "healthcare", "climate", "economy", "tax",
  "constitution", "supreme court", "justice", "rights", "amendment"
]

Known Channels:

• Vox
• Vice News
• PBS NewsHour
• MSNBC
• Fox News

---

Science

Keywords:

[
  "science", "scientific", "research", "study", "experiment",
  "physics", "chemistry", "biology", "astronomy", "space",
  "quantum", "theory", "hypothesis", "evidence", "data",
  "discovery", "breakthrough", "innovation", "technology", "engineering",
  "lab", "scientist", "professor", "university", "peer review",
  "nature", "evolution", "climate", "energy", "particle",
  "DNA", "genetics", "neuroscience", "brain", "cosmos"
]

Known Channels:

• Veritasium
• Kurzgesagt
• PBS Space Time
• SmarterEveryDay
• MinutePhysics

---

Social Media

Keywords:

[
  "social media", "content creator", "influencer", "creator economy", "monetization",
  "YouTube", "TikTok", "Instagram", "Twitter", "LinkedIn",
  "viral", "algorithm", "engagement", "followers", "subscribers",
  "content strategy", "posting schedule", "thumbnail", "SEO", "analytics",
  "brand deal", "sponsorship", "affiliate", "AdSense", "revenue",
  "growth", "niche", "audience", "community", "platform"
]

Known Channels:

• Think Media
• VidIQ
• Sunny Lenarduzzi
• Roberto Blake
• Ali Abdaal (when discussing content creation)

---

Technology

Keywords:

[
  "programming", "coding", "code", "developer", "software",
  "AI", "artificial intelligence", "machine learning", "ML", "deep learning",
  "neural network", "LLM", "GPT", "ChatGPT", "Claude",
  "React", "JavaScript", "TypeScript", "Python", "Rust",
  "web development", "frontend", "backend", "full stack", "DevOps",
  "database", "SQL", "NoSQL", "API", "REST",
  "cloud", "AWS", "Azure", "GCP", "serverless",
  "Docker", "Kubernetes", "CI/CD", "microservices", "architecture",
  "framework", "library", "open source", "GitHub", "git",
  "tech news", "startup", "Silicon Valley", "venture capital", "IPO"
]

Known Channels:

• Fireship
• Theo - t3.gg
• Primeagen
• Web Dev Simplified
• Traversy Media
• Lex Fridman (tech topics)
• All-In Podcast (tech/VC topics)

---

Religion

Keywords:

[
  "sermon", "church", "pastor", "preacher", "ministry",
  "gospel", "scripture", "bible", "biblical", "God",
  "Jesus", "Christ", "Christian", "Christianity", "faith",
  "worship", "prayer", "spiritual", "salvation", "grace",
  "testimony", "disciple", "apostle", "revelation", "prophecy",
  "Sunday service", "church service", "baptism", "communion", "Holy Spirit"
]

Known Channels:

• First Baptist Church
• Elevation Church
• Life.Church
• Bethel Church
• The Bible Project

Religious content (sermons, biblical exposition) is classified under religion category and analyzed via workflows/general-workflow.md. A specialized sermon workflow may be added in the future or shipped as a separate plugin.

---

Format Detection Keywords

Format keywords help determine the analysis workflow (not output location).

Tutorial Format

Keywords:

[
  "tutorial", "how to", "build", "create", "make",
  "step by step", "walkthrough", "guide", "beginner", "learn",
  "code along", "follow along", "from scratch", "complete guide", "full guide",
  "explained", "course", "lesson", "chapter", "part 1",
  "intro", "introduction", "getting started", "basics", "fundamentals"
]

Signals:

• Timestamps in description for different sections
• Code snippets in description
• "Resources" or "Links" section
• Project files/GitHub links
• Multiple parts/chapters

---

Course Format

Keywords:

[
  "full course", "complete course", "bootcamp", "masterclass", "comprehensive",
  "zero to hero", "beginner to advanced", "crash course", "deep dive", "complete guide",
  "certification", "curriculum", "syllabus", "module", "unit",
  "hours", "hour course", "full tutorial", "everything you need"
]

Signals:

• Duration > 2 hours
• Chapter markers or sections
• "Part 1", "Part 2" in series
• Structured learning path
• Certificate or completion mentioned

---

Finance Format

Keywords:

[
  "portfolio update", "dividend income", "passive income", "investing strategy", "stock analysis",
  "market update", "earnings report", "financial independence", "FIRE", "retirement",
  "covered calls", "options strategy", "margin investing", "leverage", "yield",
  "monthly dividends", "dividend growth", "buy and hold", "dollar cost averaging", "DCA"
]

Signals:

• Finance-specific channels (Paycheck to Portfolio, Ticker Symbol: YOU, etc.)
• Stock tickers in title/description
• Charts/graphs in thumbnail
• Financial data in description

---

Interview/Podcast Format

Keywords:

[
  "interview", "conversation", "talks with", "podcast", "episode",
  "Q&A", "ask me anything", "AMA", "discussion", "chat",
  "guest", "with", "featuring", "speaks to", "in conversation"
]

Signals:

• Two or more speakers
• Podcast format
• Question/answer structure
• Guest name in title
• "Ep" or "Episode" numbering

---

Lecture Format

Keywords:

[
  "lecture", "presentation", "keynote", "talk", "speech",
  "class", "seminar", "workshop", "conference", "summit",
  "explains", "breakdown", "analysis", "deep dive", "overview"
]

Signals:

• Academic or conference setting
• Single expert speaker
• Formal presentation style
• Educational institution channel
• "Professor", "Dr.", "PhD" in speaker name

---

Confidence Scoring System

Weighted Keyword Matching:

// Scoring weights
const weights = {
  title: 3,        // Title keywords count 3x
  description: 2,  // Description keywords count 2x
  tags: 1,         // Tags count 1x
  channel: 2       // Known channel match counts 2x
};

// Example calculation
Video: "How to Build a Dividend Portfolio with Margin - Full Tutorial"
Channel: "Paycheck to Portfolio"

Category Scores:
- finance: title(3) + description(2) + channel(2) = 7 points
- education: title(1) + description(1) = 2 points
- technology: 0 points

Format Scores:
- tutorial: title(3) + description(2) = 5 points
- finance: title(3) + channel(2) = 5 points
- general: 0 points

Total Possible: 8 points (max from all sources)
Finance Confidence: 7/8 = 87.5%
Tutorial/Finance (tie): Both 5 points → ask user

Confidence Threshold:

User Confirmation Prompt (when needed):

Detected content type with 52% confidence:
  Category: finance → knowledge/finance/youtube-summaries/
  Format: tutorial → TutorialWorkflow.md

Alternative options:
  1. technology + tutorial (45% confidence)
  2. business + general (38% confidence)

Proceed with finance/tutorial? [Y/n/1/2]

---

Output Filename Format

Pattern: {primary-topic}-{secondary-detail}-{YYYY-MM-DD}.md

Rules: 1. Use kebab-case (lowercase, hyphens for spaces) 2. Extract primary topic from title (2-4 words) 3. Add secondary detail if needed for clarity (1-3 words) 4. Always include ISO date (YYYY-MM-DD) 5. Be specific but concise (5-8 words total max)

Examples:

Bad Examples (avoid):

---

Special Cases & Edge Cases

Multi-Category Content

Example: "How AI Will Revolutionize Healthcare in 2026"

Solution:

• Primary Category: Determined by main focus (health or technology?)
• Check description for deeper context
• If unclear: Ask user which category is more relevant
• Tie-breaker: Use channel's primary category if known

---

Evolving Content (Live Streams → Edits)

Example: Live stream becomes edited video later

Solution:

• Use metadata from the CURRENT video state
• If originally analyzed as live stream, re-analyze edited version as new content
• File naming includes date to allow version tracking

---

Series/Multi-Part Content

Example: "React Course - Part 1 of 10"

Solution:

• Each part gets its own analysis file
• Filename includes part number: react-course-part-1-fundamentals-2026-01-30.md
• In metadata, note series info: series: React Course, part: 1/10

---

Shorts/Clips (< 5 minutes)

Solution:

• Same classification system applies
• Format likely general unless clearly tutorial/finance
• Filename should still be descriptive
• Consider skipping full workflow for <2min clips (ask user)

---

Language/Non-English Content

Solution:

• If transcript unavailable (non-English), rely on title/description
• Ask user if translation is needed before proceeding
• Category/format detection still works with translated metadata
• Note language in output metadata

---

Classification Decision Tree

START: Receive YouTube URL
    ↓
Extract Metadata (yt-dlp)
    ↓
Check Known Channel List
    ├─ Match Found → Apply channel default category (2x weight)
    └─ No Match → Continue to keyword analysis
    ↓
Keyword Analysis (title 3x, description 2x, tags 1x)
    ↓
Calculate Category Scores
    ↓
Calculate Format Scores
    ↓
Check Confidence Levels
    ├─ Category ≥60% AND Format ≥60% → AUTO-CLASSIFY
    ├─ Category <60% OR Format <60% → PRESENT OPTIONS + ASK USER
    └─ Tie in top scores → ASK USER
    ↓
Confirm Classification with User (if needed)
    ↓
Generate Output Filename
    ↓
Route to Workflow
    ├─ tutorial/course → workflows/tutorial-workflow.md
    ├─ finance → workflows/finance-workflow.md
    └─ interview/lecture/general → workflows/general-workflow.md
    ↓
Return: {category, format, outputPath, filename, workflow}

---

Usage in Analyze.md Workflow

Step 1: Load ContentTypes.md

Read this file to get classification rules

Step 2: Extract and Analyze

# Get metadata
yt-dlp --skip-download --write-info-json <URL>

# Parse JSON for title, description, channel, tags, duration

Step 3: Run Classification

// Pseudo-code for classification logic
const categoryScores = calculateCategoryScores(metadata, weights);
const formatScores = calculateFormatScores(metadata, weights);

const topCategory = getTopScore(categoryScores);
const topFormat = getTopScore(formatScores);

if (topCategory.confidence >= 0.6 && topFormat.confidence >= 0.6) {
  return { category: topCategory.name, format: topFormat.name };
} else {
  return askUserForConfirmation(topCategory, topFormat, alternatives);
}

Step 4: Route to Workflow

Based on format, dispatch to appropriate workflow:
- workflows/tutorial-workflow.md (for tutorial/course)
- workflows/finance-workflow.md (for finance)
- workflows/general-workflow.md (for interview/lecture/general)

---

Maintenance & Updates

Adding New Categories: 1. Add category to Category Mapping table 2. Define output path in filesystem 3. Add keyword array (20+ keywords) 4. Update decision tree logic 5. Test with 5+ example videos

Adding New Formats: 1. Add format to Format Mapping table 2. Create corresponding workflow file (if needed) 3. Add keyword array (15+ keywords) 4. Update routing logic in Analyze.md 5. Test with 5+ example videos

Tuning Detection:

• Track false positives/negatives in a log
• Adjust weights if category consistently misclassifies
• Add channel overrides for known creators
• Refine keyword lists based on user corrections

---

End of ContentTypes.md

This document is the authoritative reference for all content type detection in YouTubeAnalyzer. When in doubt, consult this file. When classification is ambiguous, ask the user.

Package Database Schema

Documentation for the YouTubeAnalyzer tutorial package tracking system.

Overview

The package database tracks software packages, frameworks, and tools mentioned in tutorial videos. It enables version comparison (what the tutorial used vs latest) and cross-video package discovery.

Database Location

~/.config/youtube-analyzer/package-db.json

Schema

Root Object

PackageEntry

Category Enum Values

Example Database

{
  "lastUpdated": "2026-01-30T14:00:00Z",
  "packages": [
    {
      "name": "next",
      "displayName": "Next.js",
      "versionMentioned": "14.2",
      "latestVersion": "15.1.0",
      "latestChecked": "2026-01-30",
      "category": "framework",
      "sourceVideos": [
        "https://youtube.com/watch?v=abc123",
        "https://youtube.com/watch?v=def456"
      ],
      "notes": "Major version behind, App Router changes in 15.x"
    },
    {
      "name": "prisma",
      "displayName": "Prisma",
      "versionMentioned": "5.0",
      "latestVersion": "5.22.0",
      "latestChecked": "2026-01-28",
      "category": "library",
      "sourceVideos": [
        "https://youtube.com/watch?v=abc123"
      ],
      "notes": ""
    }
  ]
}

CLI Operations

Add/Update Package

bun run PackageDb.ts add \
  --name "next" \
  --display-name "Next.js" \
  --version-mentioned "14.2" \
  --category "framework" \
  --source "https://youtube.com/watch?v=abc123" \
  --notes "Tutorial uses Pages Router"

List All Packages

bun run PackageDb.ts list

Query Specific Package

bun run PackageDb.ts query --name "next"

Find Stale Entries

bun run PackageDb.ts refresh --stale-days 7

Version Comparison Logic

When the synthesis agent runs, it should: 1. Run refresh --stale-days 7 to find packages needing version updates 2. For each stale package, dispatch a sub-agent to check the latest version via web search 3. Update with add --name X --latest-version Y 4. Flag packages where versionMentioned is a major version behind latestVersion

Integration Points

• TutorialWorkflow.md — Populates database after analyzing tutorial content
• Synthesis agent — Runs add for each package found across all chunks
• User queries — list and query for browsing tracked packages
• Refresh cycle — refresh identifies stale entries for web search updates

Usage Examples

Adding Packages During Tutorial Analysis

When the synthesis agent processes tutorial chunks:

# Framework detected in video
bun run PackageDb.ts add \
  --name "next" \
  --display-name "Next.js" \
  --version-mentioned "14.2.0" \
  --category "framework" \
  --source "https://youtube.com/watch?v=abc123"

# Library with notes
bun run PackageDb.ts add \
  --name "zod" \
  --display-name "Zod" \
  --version-mentioned "3.22.0" \
  --category "library" \
  --source "https://youtube.com/watch?v=abc123" \
  --notes "Used for form validation"

Updating Latest Versions

After web search agent checks npm/pypi:

bun run PackageDb.ts add \
  --name "next" \
  --latest-version "15.1.0"

Querying Package Info

# Get full details for a package
bun run PackageDb.ts query --name "next"

# Output:
{
  "name": "next",
  "displayName": "Next.js",
  "versionMentioned": "14.2.0",
  "latestVersion": "15.1.0",
  "latestChecked": "2026-01-30",
  "category": "framework",
  "sourceVideos": [
    "https://youtube.com/watch?v=abc123",
    "https://youtube.com/watch?v=def456"
  ],
  "notes": "Major version behind, App Router changes in 15.x"
}

Finding Stale Packages

# Find packages not checked in 7+ days
bun run PackageDb.ts refresh --stale-days 7

# Output:
{
  "stalePackages": [
    {
      "name": "next",
      "displayName": "Next.js",
      "lastChecked": "2026-01-20",
      "daysStale": 10
    },
    {
      "name": "prisma",
      "displayName": "Prisma",
      "lastChecked": "",
      "daysStale": -1
    }
  ],
  "totalStale": 2,
  "totalPackages": 15,
  "staleDaysThreshold": 7
}

Workflow Integration

During Tutorial Analysis

1. Transcript chunks are analyzed for package mentions 2. Each package is added via PackageDb.ts add 3. Multiple videos mentioning the same package append to sourceVideos

Version Staleness Check

1. Periodically run refresh --stale-days 7 2. For each stale package, dispatch web search agent 3. Agent queries npm/pypi/GitHub for latest version 4. Update via add --name X --latest-version Y

User Queries

User asks: "What tutorials use Next.js?"

# Query the package
bun run PackageDb.ts query --name "next"

# Response includes all source videos
{
  "sourceVideos": [
    "https://youtube.com/watch?v=abc123",
    "https://youtube.com/watch?v=def456"
  ]
}

User asks: "Show me all tracked packages"

bun run PackageDb.ts list

# Outputs formatted table + JSON

Error Handling

Missing Database

If package-db.json doesn't exist, commands automatically create an empty database:

{
  "lastUpdated": "2026-01-30T14:00:00Z",
  "packages": []
}

Invalid Arguments

bun run PackageDb.ts add --name "next"

# Output:
{
  "error": "Missing required arguments",
  "required": ["name", "display-name", "version-mentioned", "category", "source"],
  "usage": "bun run PackageDb.ts add --name <name> --display-name <display> ..."
}

Package Not Found

bun run PackageDb.ts query --name "nexxt"

# Output (with fuzzy match suggestion):
{
  "error": "Package 'nexxt' not found",
  "suggestion": "next"
}

Invalid Category

bun run PackageDb.ts add --name "next" --category "invalid" ...

# Output:
{
  "error": "Invalid category: invalid",
  "validCategories": ["framework", "library", "tool", "service", "language", "database", "other"]
}

Version Warning Specification

When the synthesis agent compares versionMentioned to latestVersion, generate warnings using this severity scale:

Warning Levels

Version Comparison Logic

Parse semver: MAJOR.MINOR.PATCH
Compare MAJOR first:
  If different -> HIGH
Compare MINOR:
  If different -> MEDIUM
Compare PATCH:
  If different -> LOW
If identical -> CURRENT

Output Format in Analysis

## Package Version Status

| Package | Tutorial Version | Latest Version | Status | Notes |
|---------|-----------------|----------------|--------|-------|
| Next.js | 14.2 | 15.1.0 | HIGH - Major version behind | App Router breaking changes |
| Prisma | 5.0 | 5.22.0 | LOW - Patch updates only | Compatible |

Production Checklist Integration

For HIGH warnings, add to the Tracker Entries section:

- [ ] `[production]` Upgrade {package} from v{mentioned} to v{latest} -- {migration notes}

Cross-Video Tracking

When the same package appears in multiple video analyses:

sourceVideos Deduplication

The sourceVideos array tracks all YouTube URLs where a package was mentioned. PackageDb.ts add already handles deduplication -- if a source URL is already in the array, it won't be added again.

Version Discrepancy Tracking

If a package is mentioned with different versions across videos, the notes field should capture this:

{
  "name": "next",
  "versionMentioned": "14.2",
  "notes": "Also seen as v13.5 in video xyz123, v15.0 in video abc789"
}

The versionMentioned field always reflects the MOST RECENT video analysis. Previous versions are noted in notes.

Cross-Video Query

To find all tutorials using a specific package:

bun run PackageDb.ts query --name "next"
# Returns sourceVideos array with all video URLs

Staleness Rules

Version Lookup Sources

Future Enhancements

• Automatic version checking: Scheduled cron job to refresh stale packages
• Version comparison alerts: Flag tutorials using deprecated/vulnerable versions
• Package popularity ranking: Track which packages appear most frequently
• Cross-tutorial recommendations: "If you learned X, you might like Y"
• Export to CSV/JSON: Generate package inventory reports

Output Path Resolution

Used by Phase 4 Step 4.5 when mode == "document". Skip this entirely when mode == "chat".

Resolving the output directory

The user picks where document-mode analyses are saved. The skill checks for a configured output directory in this order:

1. Plugin settings file (preferred)

Look for an output directory configured in the project's plugin settings file:

${CLAUDE_PROJECT_DIR}/.claude/youtube-analyzer.local.md

Example contents:

---
output_directory: /Users/me/notes/research
---

If the file exists and output_directory is set, use that value.

2. Ask the user (first run)

If no settings file exists, prompt the user with AskUserQuestion:

{
  "questions": [{
    "question": "Where should saved analyses be written? (You can change this later by editing .claude/youtube-analyzer.local.md.)",
    "header": "Output dir",
    "options": [
      {"label": "Current project directory", "description": "Save to ${CLAUDE_PROJECT_DIR}/youtube-analyses/"},
      {"label": "Subdirectory of cwd", "description": "I'll specify a subdirectory under ${CLAUDE_PROJECT_DIR}/"},
      {"label": "Absolute path", "description": "I'll provide a full absolute path (e.g., /Users/me/notes/research)"}
    ],
    "multiSelect": false
  }]
}

After the user answers, write the resolved absolute path into .claude/youtube-analyzer.local.md so the prompt only fires once per project.

3. Fallback

If both the settings file and the prompt fail (rare — AskUserQuestion declined or unavailable), default to ${CLAUDE_PROJECT_DIR}/youtube-analyses/ and create the directory if missing.

Filename format

• Pattern: {YYYY-MM-DD}-{descriptive-name}.md
• Date: today's date in ISO format
• Descriptive name: kebab-case, 5–8 words max, drawn from video title or topic
• Example: 2026-04-27-dividend-portfolio-strategy.md

Optional: Copy to current working directory

After the canonical file is written, Step 4.7 in SKILL.md prompts the user about copying the same file to the cwd captured at skill invocation. This is purely additive — the resolved output directory above is always the primary location.

Why no hard-coded path?

The personal (PAI) version of this skill wrote every analysis to a single explicit research-vault path under the author's home directory. That path was removed for the public plugin so each user can pick their own destination once and reuse it across runs.

Output Templates (Synthesis Agent)

Pass these templates into the synthesis agent prompt in Phase 4.3. The agent applies them based on format and outputSelection.

YAML Frontmatter

Every analysis document begins with this frontmatter:

---
category: {category}
format: {format}
video_url: "https://youtube.com/watch?v={video_id}"
video_title: "{title}"
channel: "{channel}"
topic: "{repo_topic}"  # only for repo-sourced transcripts
duration: "{duration}"
upload_date: "{upload_date}"
analysis_date: "{YYYY-MM-DD}"
analysis_focus: "{focusArea}"
analysis_depth: "{depth}"
outputs_generated:
  - detailed_summary    # whichever were selected
  - production_checklist
  - tool_inventory
  - key_quotes
word_count: {estimatedWords}
transcript_source: "{repo|yt-dlp|youtube_transcript_api}"
transcript_quality: "{HIGH|MEDIUM|LOW}"
key_topics:
  - topic1
  - topic2
packages_tracked: {count}  # tutorials only
github_repo: "{url}"  # tutorials only, if provided
repo_explored: {true|false}
---

---

Production Checklist

Append at the bottom of output when "Production Checklist" was selected in Phase 2:

---

## Suggested Tracker Entries

> These items are formatted for easy copy into your task tracker. They are NOT auto-created.

### Setup & Configuration
- [ ] `[setup]` Install {package} v{version} -- {brief context from video}
- [ ] `[setup]` Configure {tool} with {settings} -- {brief context}

### Implementation Steps
- [ ] `[implement]` {Step description} -- {timestamp reference if available}

### Production Gaps (Not Covered in Video)
- [ ] `[production]` Add authentication -- not covered in tutorial
- [ ] `[production]` Add error handling for {specific case}
- [ ] `[production]` Add rate limiting to {endpoint}

### Packages to Install
\`\`\`bash
# Core dependencies from video
bun add {package1} {package2}

# Dev dependencies from video
bun add -d {devPackage1} {devPackage2}
\`\`\`

---

Ground Truth Architecture (Tutorial + Repo Exploration)

Append when repoExploreResults is non-null:

---

## Ground Truth Architecture

> These diagrams were generated by analyzing the actual GitHub repository, not the video transcript.
> They represent the real codebase structure and may differ from what was shown in the tutorial.

### Project Structure

\`\`\`mermaid
{structureDiagram}
\`\`\`

### Dependency Tree

\`\`\`mermaid
{dependencyDiagram}
\`\`\`

### Key Patterns

\`\`\`mermaid
{patternDiagram}
\`\`\`

### Discrepancies with Tutorial
- {any differences between repo code and what the video showed}

---

Package Version Comparison Table (Tutorial Only)

If packages were tracked, include:

## Package Version Status

| Package | Tutorial Version | Latest Version | Status | Notes |
|---------|-----------------|----------------|--------|-------|
| Next.js | 14.2 | 15.1.0 | HIGH - Major version behind | App Router breaking changes |
| Prisma | 5.0 | 5.22.0 | LOW - Patch updates only | Compatible |
| React | 18 | 19.0 | HIGH - Major version behind | Server Components changes |

Status thresholds:

• Major version jump (e.g., 14 → 15): HIGH + migration guide link
• Minor gap (e.g., 14.2 → 14.5): MEDIUM
• Patch only: LOW
• Same version: OK

Phase 3 — Scaling + GitHub Repo Exploration

Loaded by the orchestrator at the start of Phase 3.

Token Estimation

Estimate transcript token count:
- wordCount * 1.3 = approximate token count
- OR: lineCount * 15 = approximate token count (cleaned transcripts average ~15 tokens/line)

Scaling Decision

Partition Execution

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/partition-transcript.ts \
  --input "{cleanTranscriptPath}" \
  --max-lines-per-agent 5000

Manual fallback if tool unavailable:

• Count lines in clean transcript
• Divide into chunks of ~1700 lines each (~25K tokens)
• Write each chunk to scratchpad: {scratchpad}/chunk-{N}.txt

---

GitHub Repo Exploration (Tutorial / Course Only)

Trigger: repoUrl is not null AND format is tutorial or course. Run in parallel with transcript partitioning.

Step 1 — Clone repo

git clone --depth 1 "{repoUrl}" "{scratchpad}/repo-explore/"

Edge cases (handle before cloning):

• Private repos: Ask user for token or skip exploration
• Large repos (>10K files): Warn user, offer quick scan or skip
• Monorepos: Ask which workspace to analyze
• Clone failure: Skip gracefully, set repoExploreResults = null, note reason in output

Step 2 — Spawn 3 Explore agents in PARALLEL

Each agent uses subagent_type: Explore. See workflows/repo-exploration.md for the detailed agent prompts.

1. StructureExplorer — file organization, architecture, entry points → Mermaid graph TD of project structure and component relationships 2. DependencyExplorer — package.json deps with exact versions, configs → Mermaid graph LR of dependency tree (core vs dev vs optional) 3. PatternExplorer — data flow, state management, auth, API patterns → Mermaid flowchart and sequenceDiagram of key patterns

Step 3 — Collect results

Merge all 3 agent outputs into repoExploreResults:

{
  "structure": "```mermaid\ngraph TD\n  ...\n```",
  "dependencies": "```mermaid\ngraph LR\n  ...\n```",
  "patterns": "```mermaid\nsequenceDiagram\n  ...\n```",
  "summary": "Brief text summary of findings"
}

Step 4 — Cleanup

IMPORTANT: Don't clean up yet. Cleanup happens AFTER synthesis in Phase 4 Step 4.6, in case agents need to re-read files. The Phase 4 cleanup command:

rm -rf "{scratchpad}/repo-explore/"

Phase 1 — Source Selection (Detailed Mechanics)

Loaded by the orchestrator when starting Phase 1.

Step 1.1: Resolve YouTube URL

If the user already pasted a YouTube URL in their message, skip the prompt and use it. Otherwise, ask:

{
  "questions": [{
    "question": "Paste the YouTube URL you want to analyze.",
    "header": "YouTube URL",
    "options": [
      {"label": "Provide URL", "description": "Paste a public YouTube video URL"}
    ],
    "multiSelect": false
  }]
}

(If your end user inputs a non-URL, free-text response will be captured via the question's "Other" option.)

The personal version of this skill also supported browsing a local transcript library by topic / channel / keyword. That option is dropped from the public plugin because it depends on a user-specific directory layout. If you maintain a local transcript repo, fork the plugin and re-add the browse flow.

---

Step 1.2: Extract Metadata

yt-dlp --dump-json --skip-download "URL"

Extract: title, description, channel, tags, duration, category_id, upload_date, view_count, video_id.

---

Step 1.3: Fetch Transcript (4-tier fallback chain)

Tier 1: youtube_transcript_api (preferred)

• Extract video ID from URL
• Run: youtube_transcript_api {VIDEO_ID} --format json
• Parse JSON: array of { "text", "start", "duration" }
• Reconstruct clean transcript, preserve timestamps
• Set transcriptQuality: "HIGH"

Tier 2: yt-dlp (fallback)

• Run: yt-dlp --skip-download --write-auto-sub --sub-lang en --sub-format vtt "URL"
• If auto-sub fails, try --write-sub for manual subs
• Process .vtt → clean text (strip timestamps, formatting, duplicates) using ${CLAUDE_PLUGIN_ROOT}/scripts/clean-transcript.ts
• Set transcriptQuality: "MEDIUM"

Tier 3: metadata-only (last resort)

• If Step 1.2 succeeded: use title + description + tags as analysis input
• If Step 1.2 also failed: yt-dlp --dump-json --skip-download "URL" 2>/dev/null || echo "METADATA_FAILED"
• Set transcriptQuality: "NONE"
• Warn user: "No transcript available. Analysis will be limited to video metadata."

Tier 4: graceful exit (all tiers failed)

• Set transcriptQuality: "UNAVAILABLE"
• Report: "Transcript and metadata both unavailable. This can happen with private, deleted, age-restricted, or region-locked videos. Try a different video or provide the transcript manually."
• STOP processing. Skill exits here — do not proceed to Phase 2.

---

Step 1.4: Save Transcript to Scratchpad

Save raw and cleaned transcripts to a scratchpad directory. Default scratchpad:

${CLAUDE_PROJECT_DIR}/.youtube-analyzer-scratch/

If CLAUDE_PROJECT_DIR is unset, fall back to ./.youtube-analyzer-scratch/ relative to the current working directory.

Save raw transcript to: {scratchpad}/transcript-{video_id}.txt

---

Step 1.5: Clean Transcript

Run the cleanup script to strip VTT artifacts and produce a normalized text file:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/clean-transcript.ts \
  --input "{rawTranscriptPath}" \
  --output-dir "{scratchpad}"

The script:

1. Strips VTT header lines (Kind: captions, Language: en) 2. Strips inline timestamp lines (<c> tags, <00:00: patterns) 3. Deduplicates consecutive identical lines 4. Collapses 3+ blank lines to single blank 5. Preserves YAML frontmatter (parses for metadata) 6. Writes clean text to scratchpad 7. Returns: { cleanPath, wordCount, lineCount, metadata }

Manual fallback if the script is unavailable: apply rules 1–5 in order, write to {scratchpad}/clean-transcript.txt, count words and lines.

---

Required External Tools

The end user must have these installed:

• `yt-dlp` — pip install yt-dlp or brew install yt-dlp
• `youtube_transcript_api` — pip install youtube-transcript-api
• `bun` — curl -fsSL https://bun.sh/install | bash (used to run the TypeScript scripts in ${CLAUDE_PLUGIN_ROOT}/scripts/)

If any are missing, surface a clear install message before proceeding.

Finance Workflow

Specialized analysis workflow for investment, market, and financial content.

Input

Same as GeneralWorkflow, plus:

• config.focusArea — one of: "strategy-breakdown", "action-items", "risk-analysis", "portfolio-ideas"

Analysis Protocol

1. Read transcript chunk from file path 2. Identify financial strategies, theories, and recommendations 3. Categorize content: macro analysis, individual stocks, portfolio strategy, income/dividends, options, crypto, real estate 4. Extract specific numbers: returns, yields, allocations, price targets 5. Note disclaimers, risk warnings, and qualification statements 6. Identify the speaker's investment philosophy and biases

Output Modes

Strategy Breakdown Mode (config.focusArea = "strategy-breakdown")

• Each strategy named and explained
• Required capital and experience level
• Historical performance if mentioned
• Comparison to conventional approaches
• Risk/reward profile

Action Items Mode (config.focusArea = "action-items")

• Specific actionable steps
• Tools and platforms needed
• Account types and minimums
• Timeline and milestones
• Prerequisites and assumptions

Risk Analysis Mode (config.focusArea = "risk-analysis")

• Risk factors identified per strategy
• Market conditions required
• Worst-case scenarios mentioned
• Hedging strategies discussed
• Regulatory and tax considerations

Portfolio Ideas Mode (config.focusArea = "portfolio-ideas")

• Specific holdings mentioned
• Allocation percentages
• Sector/asset class distribution
• Income projections
• Rebalancing triggers

Output Structure

## Executive Summary
[Core thesis and investment approach]

## Content Category
[Macro | Individual Stock | Portfolio Strategy | Income/Dividend | Options | Crypto | Real Estate | Mixed]

## Investment Strategies

### [Strategy Name]
- **Thesis:** [core argument]
- **Required Capital:** [amount/range]
- **Risk Level:** [Low/Medium/High/Very High]
- **Time Horizon:** [Short/Medium/Long]
- **Key Metrics:** [specific numbers mentioned]

## Actionable Takeaways
1. [Specific action with context]
2. [Specific action with context]

## Risk Assessment
- **Market Risks:** [identified risks]
- **Timing Sensitivity:** [how time-sensitive is this advice]
- **Assumptions:** [what must be true for this to work]

## Numbers & Data Points
| Metric | Value | Context |
|--------|-------|---------|
| [metric] | [value] | [what it means] |

## Speaker Context
- **Investment Philosophy:** [identified approach]
- **Potential Biases:** [conflicts of interest, promotion, etc.]
- **Track Record:** [if mentioned]

## Quality Assessment
- Content depth: [DEEP/SURFACE/MIXED]
- Actionability: [HIGH/MEDIUM/LOW]
- Disclaimer quality: [THOROUGH/ADEQUATE/MISSING]

Chunk-Specific Instructions

Same as GeneralWorkflow — analyze only your assigned chunk. Extract ALL specific numbers, tickers, and strategies mentioned in your chunk.

General Workflow

Default analysis workflow for YouTube content that doesn't match specialized formats (tutorial, finance, sermon). Handles interviews, lectures, educational content, and everything else.

Input

This workflow receives:

• transcriptChunk — file path to transcript text (full or chunk)
• config.focusArea — one of: "key-insights", "summary-only", "deep-analysis", "quotes-wisdom"
• config.depth — one of: "quick" (~500 words), "standard" (~1500 words), "deep" (~3000+ words)
• metadata — video title, channel, duration, upload_date
• chunkInfo — { chunk: N, startLine: X, endLine: Y } if partitioned, null if full

Analysis Protocol

1. Read the transcript chunk from the provided file path 2. Identify main themes, arguments, and narrative structure 3. Extract key insights with supporting evidence 4. Note any timestamps referenced in the transcript 5. Identify speakers if multiple (interviews/podcasts)

Output Modes

Key Insights Mode (config.focusArea = "key-insights")

Focus on extractable wisdom:

• Top 5-10 key insights, each with supporting quote
• Pattern recognition across topics
• Contrarian or surprising viewpoints
• Actionable takeaways

Summary Only Mode (config.focusArea = "summary-only")

Concise executive summary:

• 2-3 paragraph overview
• Bullet list of main points
• Who should watch this and why

Deep Analysis Mode (config.focusArea = "deep-analysis")

Comprehensive breakdown:

• Section-by-section analysis with timestamps
• Argument mapping (claims → evidence → conclusions)
• Critical assessment of claims
• Connections to broader themes
• Gaps or unanswered questions

Quotes + Wisdom Mode (config.focusArea = "quotes-wisdom")

Focus on memorable content:

• Notable quotes with context and timestamps
• Wisdom extracts (timeless principles)
• Frameworks or mental models mentioned
• Metaphors and analogies used

Output Structure

Return structured markdown (adapt sections based on depth):

## Executive Summary
[2-3 paragraphs]

## Key Topics
1. [Topic] — [brief description]
2. [Topic] — [brief description]

## Detailed Analysis
### [Section/Topic]
[Analysis with quotes and timestamps]

## Notable Quotes
> "Quote text" — [Speaker, timestamp]

## Practical Applications
- [Actionable takeaway]

## Quality Assessment
- Transcript quality: [HIGH/MEDIUM/LOW]
- Content density: [HIGH/MEDIUM/LOW]
- Production value: [description]

Chunk-Specific Instructions

If this is a partitioned chunk (chunkInfo is not null):

• Analyze ONLY the content in your assigned chunk
• Note if topics span chunk boundaries (incomplete thoughts at start/end)
• Label all findings with approximate timestamps if available
• Do NOT attempt to read other chunks or the full transcript
• The synthesis agent will merge your analysis with other chunks

Repo Exploration Workflow

Agent prompts for GitHub repository exploration during tutorial analysis. Produces Mermaid diagrams that represent the actual codebase (ground truth) for comparison against tutorial content.

When This Runs

• Phase 3 of YouTubeAnalyzer, PARALLEL with transcript partitioning
• Only for tutorial/course format when user provides a GitHub repo URL
• Repo is cloned to {scratchpad}/repo-explore/ with --depth 1

Edge Case Handling

Before Cloning

After Cloning

# Quick size check
find "{scratchpad}/repo-explore/" -type f | wc -l

If > 10,000 files, warn user before proceeding.

---

Agent 1: StructureExplorer

Agent type: Explore Focus: File organization, architecture, entry points

Prompt

Explore the repository at {scratchpad}/repo-explore/ and produce a Mermaid graph TD diagram showing:

1. Top-level directory structure (max 3 levels deep)
2. Key entry points (index files, main files, app entry)
3. Component relationships (which directories import from which)
4. Configuration files location

Rules:
- Output ONLY a Mermaid graph TD diagram in a code fence
- Max 30 nodes (collapse subdirectories if needed)
- Use descriptive labels: "pages/ (12 routes)" not just "pages/"
- Highlight entry points with a different shape (e.g., [[ ]] for stadium shape)
- Group related directories with subgraph blocks
- Add a brief 2-3 sentence summary AFTER the diagram

Example output format:

graph TD subgraph "Application Layer" A[["app/ (entry)"]] --> B[pages/ - 12 routes] A --> C[components/ - 24 files] end subgraph "Data Layer" D[lib/] --> E[prisma.ts] D --> F[auth.ts] end subgraph "Config" G[next.config.js] H[tailwind.config.ts] end B --> C B --> D C --> D

Summary: Next.js app with 12 routes, 24 components, Prisma ORM for data access. Entry point is app/ directory using App Router.

---

Agent 2: DependencyExplorer

Agent type: Explore Focus: Dependencies with exact versions, configs

Prompt

Explore the repository at {scratchpad}/repo-explore/ and produce a Mermaid graph LR diagram showing the dependency tree.

Steps:
1. Read package.json (or requirements.txt, go.mod, Cargo.toml if not Node)
2. Categorize each dependency:
   - CORE: Framework and essential runtime dependencies
   - DATA: Database, ORM, state management
   - UI: Styling, component libraries, icons
   - AUTH: Authentication and authorization
   - DEV: Testing, linting, build tools
   - OPTIONAL: Nice-to-have, plugins, extras
3. Record EXACT version from lock file if available

Rules:
- Output ONLY a Mermaid graph LR diagram in a code fence
- Include version numbers in labels: "Next.js 14.2.3"
- Group by category using subgraph blocks
- Max 40 nodes (collapse minor deps if needed)
- After the diagram, list ALL dependencies as a simple table:
  | Package | Version | Category | Purpose |

Example output format:

graph LR APP((Project)) subgraph "CORE" APP --> NEXT["Next.js 14.2.3"] APP --> REACT["React 18.3.1"] NEXT --> REACT end subgraph "DATA" APP --> PRISMA["Prisma 5.19.0"] PRISMA --> PG["PostgreSQL"] end subgraph "UI" APP --> TW["Tailwind CSS 3.4"] APP --> SHADCN["shadcn/ui"] SHADCN --> RADIX["Radix UI"] end subgraph "AUTH" APP --> NAUTH["NextAuth 4.24"] NAUTH --> BCRYPT["bcrypt"] end subgraph "DEV" APP --> TS["TypeScript 5.5"] APP --> ESLINT["ESLint 8.x"] end

| Package | Version | Category | Purpose |
|---------|---------|----------|---------|
| next | 14.2.3 | CORE | React framework |
...

---

Agent 3: PatternExplorer

Agent type: Explore Focus: Data flow, state management, auth flow, API patterns

Prompt

Explore the repository at {scratchpad}/repo-explore/ and produce Mermaid diagrams showing key implementation patterns.

Investigate:
1. **Authentication flow** - How users log in, session management, token handling
2. **Data flow** - How data moves from database to UI (API routes, server components, client fetching)
3. **State management** - Client-side state approach (React context, zustand, redux, etc.)
4. **API patterns** - Route structure, middleware, error handling

Rules:
- Output 2-3 Mermaid diagrams (sequence diagrams and/or flowcharts)
- Label each diagram with what pattern it shows
- Include actual file paths in participant names where relevant
- Max 15 steps per sequence diagram
- After diagrams, list key patterns as bullet points with file references

Example output format:

### Authentication Flow

sequenceDiagram participant Client as Client (app/login/page.tsx) participant API as API Route (app/api/auth/[...nextauth]/route.ts) participant Auth as NextAuth (lib/auth.ts) participant DB as Prisma (lib/prisma.ts) participant PG as PostgreSQL

Client->>+API: POST /api/auth/callback/credentials API->>+Auth: authorize(credentials) Auth->>+DB: findUnique({ email }) DB->>+PG: SELECT * FROM users PG-->>-DB: User record DB-->>-Auth: User object Auth->>Auth: bcrypt.compare(password, hash) Auth-->>-API: Session + JWT API-->>-Client: Set cookie, redirect to /dashboard

### Data Flow

flowchart TD A[Server Component] -->|fetch| B[API Route] B -->|query| C[Prisma Client] C -->|SQL| D[(PostgreSQL)] D -->|result| C C -->|typed data| B B -->|JSON| A A -->|props| E[Client Component] E -->|mutation| F[Server Action] F -->|update| C

Key patterns:
- **Server Components for data fetching**: pages use RSC to fetch data without client-side loading states (app/dashboard/page.tsx)
- **Server Actions for mutations**: form submissions use server actions instead of API routes (app/actions/)
- **Prisma singleton**: Single Prisma client instance via lib/prisma.ts to prevent connection exhaustion

---

Output Assembly

The orchestrator collects outputs from all 3 agents and assembles repoExploreResults:

{
  "structure": "<full mermaid diagram + summary from StructureExplorer>",
  "dependencies": "<full mermaid diagram + table from DependencyExplorer>",
  "patterns": "<full mermaid diagrams + bullet points from PatternExplorer>",
  "summary": "Brief 2-3 sentence overview combining all findings"
}

This object is passed to the Phase 4 synthesis agent, which embeds the diagrams in the "Ground Truth Architecture" section of the final output.

---

Cleanup

After Phase 4 synthesis is complete:

rm -rf "{scratchpad}/repo-explore/"

Do NOT clean up before synthesis -- agents may need to re-reference files during the merge.

Tutorial Workflow

Specialized analysis workflow for tutorial and course content. Extends general analysis with package tracking, GitHub integration, and production readiness assessment.

Input

Same as GeneralWorkflow, plus:

• config.repoUrl — optional GitHub repository URL
• config.focusArea — one of: "production-checklist", "tool-inventory", "architecture-patterns", "step-by-step"

Analysis Protocol

Phase 1: Content Analysis

1. Read transcript chunk from file path 2. Identify tutorial structure: what is being built, in what order 3. Map the architecture/stack being taught 4. Note all commands, code snippets, and configurations mentioned

Phase 2: Package & Framework Inventory

For every tool, package, framework, or library mentioned:

• Name (exact package name, e.g., "next" not "Next.js")
• Display name (human-readable, e.g., "Next.js")
• Version mentioned in video (if stated)
• Category: framework | library | tool | service | language | database
• How it's used in the tutorial
• Whether it's a core dependency or optional

Phase 3: Production Readiness Assessment

Evaluate what the tutorial DOESN'T cover but a production app needs:

• Authentication & authorization
• Rate limiting & throttling
• Error handling & logging
• Input validation & sanitization
• Database migrations & seeding
• Environment configuration
• CI/CD pipeline
• Testing (unit, integration, e2e)
• Monitoring & observability
• Security headers & CORS
• Performance optimization
• Accessibility
• SEO (if web app)

Phase 4: GitHub Repo Analysis Integration

If repoExploreResults is provided by the orchestrator (from Phase 3 repo exploration), the synthesis agent integrates these Mermaid diagrams into the final output.

What the synthesis agent receives:

• repoExploreResults.structure - Mermaid graph TD of project file organization
• repoExploreResults.dependencies - Mermaid graph LR of dependency tree with exact versions
• repoExploreResults.patterns - Mermaid sequence/flow diagrams of implementation patterns
• repoExploreResults.summary - Brief text overview

What the synthesis agent does: 1. Adds a "Ground Truth Architecture" section to the output with embedded Mermaid diagrams 2. Cross-references repo structure against tutorial content to identify discrepancies 3. Uses actual package versions from repo's package.json/lock file (more reliable than transcript mentions) 4. Notes any code patterns in the repo that the tutorial didn't cover 5. Lists production features present in repo but not taught in video

Discrepancy examples:

• Tutorial shows Pages Router but repo uses App Router
• Tutorial installs v14 but repo's lock file has v15
• Repo has auth middleware the tutorial never explains
• Repo has tests the tutorial skipped

See workflows/repo-exploration.md for the full agent prompt specifications.

Output Modes

Production Checklist Mode (config.focusArea = "production-checklist")

Focus on what's missing for production:

• Checklist of production requirements
• What the tutorial covers vs what's needed
• Recommended tools/packages for each gap
• Priority order for implementation

Tool Inventory Mode (config.focusArea = "tool-inventory")

Focus on the technology stack:

• Complete package inventory with versions
• Alternative tools for each (with pros/cons)
• Deprecated or outdated packages flagged
• Ecosystem compatibility notes

Architecture Patterns Mode (config.focusArea = "architecture-patterns")

Focus on design decisions:

• Architecture diagrams (described in text)
• Design patterns used
• Data flow mapping
• State management approach
• API design patterns

Step-by-Step Mode (config.focusArea = "step-by-step")

Focus on following along:

• Numbered step sequence with commands
• Configuration files content
• Key decision points explained
• Common errors and fixes
• Checkpoint verification steps

Output Structure

## Executive Summary
[What this tutorial builds and teaches]

## Architecture Overview
[Stack diagram, data flow, key components]

## Package & Tool Inventory

| Package | Version (Video) | Category | Role in Tutorial |
|---------|----------------|----------|------------------|
| next | 14.2 | Framework | Core framework |
| prisma | 5.x | ORM | Database access |

## Step-by-Step Summary
1. [Step with key command]
2. [Step with key command]

## Production Readiness Checklist
- [ ] Authentication system — not covered
- [x] Database setup — covered with Prisma
- [ ] Rate limiting — not covered

## Key Patterns & Techniques
### [Pattern Name]
[Explanation with code reference]

## Tool Comparison
| Tool Used | Alternatives | Trade-offs |
|-----------|-------------|------------|
| Prisma | Drizzle, TypeORM | Type-safety vs flexibility |

## Quality Assessment
- Tutorial quality: [EXCELLENT/GOOD/FAIR]
- Code quality: [assessment]
- Production readiness: [LOW/MEDIUM/HIGH]

Package Database Integration

After analysis, the synthesis agent will call the package database script for each package found:

bun run ${CLAUDE_PLUGIN_ROOT}/scripts/package-db.ts add \
  --name "next" \
  --display-name "Next.js" \
  --version-mentioned "14.2" \
  --category "framework" \
  --source "VIDEO_URL"

Chunk-Specific Instructions

Same as GeneralWorkflow — analyze only your assigned chunk. The synthesis agent merges. For package inventory: list ALL packages mentioned in your chunk, even if you suspect they appear in other chunks too. Deduplication happens at synthesis.