Last Updated: 2026-02-15
This directory contains systematic root-cause analyses and deep-fix documentation for bugs discovered during content-machine development.
Each bug document follows this structure:
- Problem Statement - What the user saw
- Root Cause Analysis - Multi-layer investigation
- Fix Implementation - Code changes with examples
- Test Coverage - Unit tests added
- Verification - Before/after comparison
- Lessons Learned - Patterns for future prevention
| ID | Title | Status | Severity | Related Commits |
|---|---|---|---|---|
| BUG-001 | TTS Markers in Video Captions | FIXED | High | 96eedc2, 1462eae |
| BUG-002 | Hook Text Duplication in Audio | FIXED | Medium | 7020b15 |
| BUG-003 | ASR Artifacts as Caption Words | FIXED | Medium | 1462eae |
All caption-related bugs were fixed with a defense-in-depth approach:
┌─────────────────┐
│ ASR Layer │ ← isWhisperArtifact() filters during transcription
├─────────────────┤
│ Caption Layer │ ← sanitizeTimedWords() filters before paging
├─────────────────┤
│ Render Layer │ ← buildRenderProps() final safety filter
└─────────────────┘
Script assembly bugs (hook duplication) were fixed by:
- Detecting content overlap between sections
- Case-insensitive text matching
- Conditional section inclusion
ASR artifacts were addressed by:
- Using Whisper confidence scores
- Empirically tuned thresholds (0.15 for ASR, 0.10 for captions)
- Preserving words without confidence scores
- Always filter ASR output - Never trust raw transcription
- Use confidence scores - Low confidence = likely artifact
- Test with real TTS audio - Synthetic audio has unique artifacts
- Defense in depth - Multiple filtering layers catch different issues
- Pattern evolution - Keep regex patterns updated for new TTS engines
- V&V Framework - Validation approach
- Render Stage (Captions) - Caption rendering architecture
- Audio Pipeline - TTS/ASR design