메뉴
Parse, extract, and format transcripts (VTT, SRT, plain text) into structured Markdown packets with action items, decisions, questions, and topics. v2.0 uses hybrid Python+LLM architecture for VTT files. Integrates with ps-critic for quality review.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
On-demand adversarial quality reviews using strategy templates. Selects strategies by criticality level, executes adversarial templates against deliverables, and scores quality using LLM-as-Judge rubric. Integrates with quality-enforcement.md SSOT.
Product management and product marketing decision framework. Invoke when users need product strategy (PRDs, vision, roadmaps), customer insight (personas, journey maps, VOC), business analysis (business cases, market sizing, pricing), competitive intelligence (battle cards, win/loss, competitive analysis), or go-to-market planning (GTM plans, positioning, MRDs, buyer personas). Uses 18 validated industry frameworks organized around Cagan's Value Risk and Business Viability Risk domains. Supports discovery mode (hypothesis-driven) and delivery mode (stakeholder-ready). Trigger keywords - PRD, product requirements, roadmap, prioritize, RICE, persona, journey map, VOC, business case, market sizing, TAM, competitive analysis, battle card, GTM, go-to-market, positioning, messaging, MRD.
Structured prompt construction and quality validation for Jerry Framework. Invoke when building structured prompts, generating NPT-009/NPT-013 constraints, or scoring prompt quality. Guides users through the 5-element prompt anatomy, generates formatted constraints with XML wrapping, and scores prompts against the 7-criterion rubric.
INTERNAL SKILL — auto-loaded for framework output voice quality. Reviews, rewrites, and scores framework output text for persona compliance using the Shane McConkey ethos: joy and excellence as multipliers. Governs quality gate messages, error messages, CLI output, hook text, and framework-generated text. Not user-invocable; loaded automatically when framework output needs voice enforcement.
Work item tracking and task management using the Jerry Framework hierarchy (Initiative, Epic, Feature, Story, Task, Enabler, Bug, Impediment). Manages WORKTRACKER.md manifests, tracks progress, and enforces template usage for consistent work decomposition.
Secure engineering team skill providing methodology guidance for building security-hardened software. Invoked when users request system design, implementation, code review, testing, CI/CD security, or incident response with security considerations. Routes to 10 specialized agents covering architecture through post-deployment. Integrates NIST SSDF governance, Microsoft SDL phases, OWASP ASVS verification, SLSA supply chain integrity, and DevSecOps automation patterns.
SOC 직업 분류 기준
| name | transcript |
| description | Parse, extract, and format transcripts (VTT, SRT, plain text) into structured Markdown packets with action items, decisions, questions, and topics. v2.0 uses hybrid Python+LLM architecture for VTT files. Integrates with ps-critic for quality review. |
| version | 2.5.0 |
| allowed-tools | Read, Write, Glob, Agent, Bash(*), mcp__memory-keeper__context_save, mcp__memory-keeper__context_get |
| argument-hint | <file-path> [--output-dir <dir>] [--no-mindmap] [--mindmap-format <mermaid|ascii|both>] |
| context_injection | {"default_domain":"general","domains":[{"name":"general","description":"Baseline extraction - speakers, topics, questions","file":"contexts/general.yaml","spec":null},{"name":"transcript","description":"Base transcript entities - extends general","file":"contexts/transcript.yaml","spec":null},{"name":"meeting","description":"Generic meetings - action items, decisions, follow-ups","file":"contexts/meeting.yaml","spec":null},{"name":"software-engineering","description":"Standups, sprint planning, code reviews - commitments, blockers, risks","file":"contexts/software-engineering.yaml","spec":"docs/domains/SPEC-software-engineering.md","target_users":["Engineers","Tech Leads","Scrum Masters"]},{"name":"software-architecture","description":"ADR discussions, design sessions - decisions, alternatives, quality attributes","file":"contexts/software-architecture.yaml","spec":"docs/domains/SPEC-software-architecture.md","target_users":["Architects","Principal Engineers"]},{"name":"product-management","description":"Roadmap planning, feature prioritization - requests, user needs, stakeholder feedback","file":"contexts/product-management.yaml","spec":"docs/domains/SPEC-product-management.md","target_users":["PMs","Product Owners","Business Analysts"]},{"name":"user-experience","description":"Research interviews, usability tests - insights, pain points, verbatim quotes","file":"contexts/user-experience.yaml","spec":"docs/domains/SPEC-user-experience.md","target_users":["UX Researchers","UX Designers"],"special_requirements":["verbatim_quote_preservation"]},{"name":"cloud-engineering","description":"Post-mortems, capacity planning - incidents, root causes, action items","file":"contexts/cloud-engineering.yaml","spec":"docs/domains/SPEC-cloud-engineering.md","target_users":["SREs","DevOps Engineers","Platform Engineers"],"special_requirements":["blameless_culture"]},{"name":"security-engineering","description":"Security audits, threat modeling - vulnerabilities, threats (STRIDE), compliance gaps","file":"contexts/security-engineering.yaml","spec":"docs/domains/SPEC-security-engineering.md","target_users":["Security Engineers","AppSec Engineers","Compliance Officers"],"special_requirements":["risk_acceptance_documentation","stride_support","cvss_support"]}],"context_path":"./contexts/","template_variables":[{"name":"domain","source":"invocation.domain","default":"general"},{"name":"entity_definitions","source":"context.entity_definitions","format":"yaml"},{"name":"extraction_rules","source":"context.extraction_rules","format":"list"},{"name":"prompt_guidance","source":"context.prompt_guidance","format":"text"}]} |
| activation-keywords | ["transcript","meeting notes","parse vtt","parse srt","extract action items","extract decisions","analyze meeting","/transcript"] |
CRITICAL: For VTT files, you MUST invoke the Python parser via the
jerryCLI. DO NOT use Task agents for parsing. The CLI provides 1,250x cost reduction and deterministic output.
ARGUMENT PARSING RULES:
<file-path> (the VTT/SRT file)--output-dir flag specifies the output directory (default: ./transcript-output)--output, treat it as --output-dir (alias)For VTT files, Claude MUST execute this bash command:
uv run jerry transcript parse "<FILE_PATH>" --output-dir "<OUTPUT_DIR>"
Where:
<FILE_PATH> = The ACTUAL file path from the user's invocation (first positional arg)<OUTPUT_DIR> = The output directory from --output-dir or --output flag (default: ./transcript-output)Example - user invokes:
/transcript /Users/me/meeting.vtt --output-dir /Users/me/output/
Claude executes:
uv run jerry transcript parse "/Users/me/meeting.vtt" --output-dir "/Users/me/output/"
CRITICAL: Always quote file paths to handle spaces and special characters.
Expected output:
index.json - Chunk metadata and speaker summarychunks/chunk-*.json - Transcript segments in processable chunkscanonical-transcript.json - Full parsed output (for reference only, DO NOT read into context)Claude's execution using Bash tool:
# Basic invocation
uv run jerry transcript parse "/Users/me/meeting.vtt" --output-dir "/Users/me/output/"
What this does:
uv run to execute in managed Python environmentjerry transcript parse subcommandCommon variations:
# With domain context
uv run jerry transcript parse "meeting.vtt" \
--output-dir "./output/" \
--domain software-engineering
# Skip mindmaps for faster processing
uv run jerry transcript parse "meeting.vtt" \
--output-dir "./output/" \
--no-mindmap
# Specify mindmap format
uv run jerry transcript parse "meeting.vtt" \
--output-dir "./output/" \
--mindmap-format mermaid
Error handling example:
# Check exit code
uv run jerry transcript parse "meeting.vtt" --output-dir "./output/"
if [ $? -ne 0 ]; then
echo "Parsing failed - check error output above"
exit 1
fi
Verified Output (2026-01-30):
$ uv run jerry transcript parse "test.vtt" --output-dir "./out/"
✅ Detected format: VTT
✅ Parsed 3071 segments
✅ Created ./out/index.json (7 chunks)
✅ Created ./out/chunks/ (chunk-001 through chunk-007)
✅ Parsing completed in 0.8s
After Phase 1 CLI parsing completes, continue with LLM agents:
index.json + chunks/*.json, produce extraction-report.jsonindex.json + extraction-report.json, produce packet files--no-mindmap not set)Version: 2.4.1 Framework: Jerry Transcript Processing Constitutional Compliance: Jerry Constitution v1.0 (P-001, P-002, P-003, P-004, P-010, P-020, P-022) Architecture: Hybrid Python+LLM (Strategy Pattern) + Mindmap Generation + Token-Based Chunking
This SKILL.md serves multiple audiences:
| Level | Audience | Sections to Focus On | Why This Matters |
|---|---|---|---|
| L0 (ELI5) | New users, stakeholders | Purpose, When to Use, Routing Disambiguation, Quick Reference | Learn what the skill does and how to invoke it |
| L1 (Engineer) | Developers using the skill | Invoking the Skill, Agent Pipeline, File Persistence | Understand the technical workflow and outputs |
| L2 (Architect) | Workflow designers | Architecture, State Management, Self-Critique | Design integrations and ensure quality |
Reading Path Recommendations:
The Transcript Skill transforms raw meeting transcripts into structured, navigable knowledge packets. It addresses the #1 user pain point: manual extraction of action items, decisions, and key information from meetings.
Activate when:
Example Invocations:
"Process this meeting transcript: /path/to/meeting.vtt"
"Extract action items from the quarterly review"
"/transcript analyze-meeting.srt"
"Parse the team standup notes and find all decisions"
"/transcript meeting.vtt --domain software-engineering"
The transcript skill supports 9 domain contexts that customize entity extraction for specific professional contexts. See DOMAIN-SELECTION-GUIDE.md for the complete selection flowchart.
| Domain | Context File | Use For | Key Entities |
|---|---|---|---|
general | general.yaml | Any transcript (default) | speakers, topics, questions |
transcript | transcript.yaml | Extends general | + segments, timestamps |
meeting | meeting.yaml | Generic meetings | + action_items, decisions, follow_ups |
software-engineering | software-engineering.yaml | Standups, sprint planning | + commitments, blockers, risks |
software-architecture | software-architecture.yaml | ADR discussions, design | + architectural_decisions, alternatives |
product-management | product-management.yaml | Roadmap, prioritization | + feature_requests, user_needs |
user-experience | user-experience.yaml | Research, usability tests | + user_insights, pain_points, verbatim quotes |
cloud-engineering | cloud-engineering.yaml | Post-mortems, capacity | + incidents, root_causes (blameless) |
security-engineering | security-engineering.yaml | Audits, threat modeling | + vulnerabilities, threats (STRIDE), compliance_gaps |
/transcript <file> --domain <domain-name>
Examples:
/transcript standup.vtt --domain software-engineering
/transcript postmortem.vtt --domain cloud-engineering
/transcript user-interview.vtt --domain user-experience
If no domain is specified, general is used as the default.
TRANSCRIPT SKILL PIPELINE (v2.1 HYBRID ARCHITECTURE + MINDMAPS)
===============================================================
USER INPUT (VTT/SRT/TXT)
│
│ /transcript file.vtt [--mindmap-format both]
│ /transcript file.vtt --no-mindmap (to disable)
▼
┌───────────────────────────────────────────────────────┐
│ ts-parser v2.0 (ORCHESTRATOR) │
│ Model: haiku (orchestration only) │
└───────────────────────┬───────────────────────────────┘
│
┌────────────────┴────────────────┐
│ FORMAT DETECTION │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ VTT Format │ │ SRT/TXT │
│ (Python) │ │ (LLM) │
└──────┬──────┘ └──────┬──────┘
│ │
▼ │
┌─────────────┐ │
│ Python VTT │ 1,250x cost reduction │
│ Parser │ Sub-second parsing │
└──────┬──────┘ 100% accuracy │
│ │
▼ │
┌─────────────┐ │
│ VALIDATOR │ │
└──────┬──────┘ │
│ │
▼ │
┌─────────────┐ │
│ Chunker │ │
│ (500 segs) │ │
└──────┬──────┘ │
│ │
└────────────────┬────────────────┘
▼
┌───────────────────────────────────────────────────────┐
│ ts-extractor (sonnet) │
│ Processes chunks OR monolithic │
└───────────────────────┬───────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────┐
│ ts-formatter (sonnet) │
│ Generates 8-file packet per ADR-002 │
└───────────────────────┬───────────────────────────────┘
│
│ ts_formatter_output.packet_path
▼
┌───────────────────────────┐
│ --no-mindmap flag set? │
└─────────────┬─────────────┘
│
┌──────────────────┴──────────────────┐
│ NO (default) │ YES
▼ ▼
┌─────────────────────┐ (skip mindmaps)
│ ts-mindmap-* │ │
│ (sonnet) │ │
│ │ │
│ ┌─────────────────┐ │ │
│ │ts-mindmap-mermaid│ │ Output: │
│ └─────────────────┘ │ 08-mindmap/ │
│ ┌─────────────────┐ │ mindmap.mmd │
│ │ ts-mindmap-ascii│ │ mindmap.ascii.txt │
│ └─────────────────┘ │ │
└──────────┬──────────┘ │
│ │
│ ts_mindmap_output │
└──────────────┬──────────────────┘
│
▼
┌───────────────────────────────────────────────────────┐
│ ps-critic (sonnet) │
│ Quality validation >= 0.90 │
│ │
│ • Core validation (00-07 files) │
│ • MM-* criteria (if Mermaid mindmap present) │
│ • AM-* criteria (if ASCII mindmap present) │
└───────────────────────────────────────────────────────┘
COMPLIANCE: Each agent is a WORKER. None spawn subagents.
RATIONALE: DISC-009 - Agent-only architecture caused 99.8% data loss on large files.
MINDMAPS: ADR-006 - Mindmaps ON by default, opt-out via --no-mindmap flag.
Added in EN-030: This section explains the "why" behind the v2.0 architecture shift.
Original Approach: Pure LLM parsing for all formats (VTT, SRT, TXT)
What went wrong:
Critical incident (DISC-009):
Decision: Split deterministic parsing from semantic extraction
Rationale:
Trade-offs accepted:
| Aspect | v1.0 (Pure LLM) | v2.0 (Hybrid) | Decision |
|---|---|---|---|
| Cost | $1.25 | $0.001 (Python) + $0.10 (extraction) = $0.101 | ✅ 92% savings |
| Speed | 15-30s | <1s (parsing) + 10-15s (extraction) = ~15s | ✅ Similar, burst faster |
| Accuracy | 95% | 100% (parsing) + 85% (extraction) | ✅ Better where it matters |
| Complexity | Simple (1 agent) | Higher (orchestration logic) | ❌ Engineering overhead |
One-Way Door Decision:
Why not pure Python for everything?
Validation of approach:
Alternative 1: Pure Python (Rejected)
Alternative 2: WebAssembly Parser (Deferred)
Alternative 3: Streaming LLM Parsing (Rejected)
Problem: Large transcripts (>200K tokens) exceed LLM context windows. Solution: Chunk into ~18K token pieces with overlap.
Claude Sonnet 4.5 limits:
Real-world transcript sizes:
Without chunking (canonical-transcript.json directly):
With chunking (index.json + chunks/):
Calculation:
Why not larger chunks (e.g., 23K tokens)?
Why not smaller chunks (e.g., 10K tokens)?
Overlap strategy (not yet implemented, future enhancement):
v2.0 (segment-based, deprecated):
v2.1 (token-based, current):
Trade-off:
ADR-006: Mindmaps are ON by default (v2.1), use
--no-mindmapto disable.
Original design: Mindmaps were opt-in via --mindmap flag
User feedback:
Metrics (2-week trial, Jan 2026):
Decision: Flip default - mindmaps ON, use --no-mindmap to disable
Rationale:
After ADR-006 deployment:
Trade-offs:
| Aspect | Opt-In (v2.0) | Default-On (v2.1) | Decision |
|---|---|---|---|
| Discovery | Low (12%) | High (73%) | ✅ Major improvement |
| Speed | Faster (no mindmap) | +30-60s | ❌ Acceptable overhead |
| Cost | Lower | +$0.10 per transcript | ❌ But users value it |
| Complexity | Simpler | Needs graceful degradation | ❌ But manageable |
Why not always generate (no opt-out)?
One-Way Door:
Alternative considered: Lazy generation
Why 0.90, not 0.95 or 0.80?
Quality score distribution (500 test transcripts):
| Score Range | Count | Percentage | Interpretation |
|---|---|---|---|
| 0.95-1.00 | 142 | 28% | Excellent |
| 0.90-0.95 | 298 | 60% | Good |
| 0.85-0.90 | 47 | 9% | Acceptable |
| 0.80-0.85 | 11 | 2% | Marginal |
| < 0.80 | 2 | 0.4% | Poor (requires rework) |
If threshold = 0.95:
If threshold = 0.80:
Sweet spot: 0.90
| System | Quality Threshold | Rationale |
|---|---|---|
| Google Docs | N/A (no blocking) | Freemium model, can't block users |
| Otter.ai | ~0.85 (estimated) | Lower threshold, prioritize speed |
| Jerry Transcript | 0.90 | Balance quality and usability |
| Medical transcription | 0.98+ | High-stakes domain |
Why higher than Otter.ai?
Why lower than medical?
Idea: Dynamic threshold based on domain
domain_thresholds:
general: 0.85 # Casual meetings
software-engineering: 0.90 # Current default
security-engineering: 0.95 # High-stakes audits
medical: 0.98 # Future expansion
Not implemented because:
Why both #act-001 AND [00:15:32]?
User needs:
Single citation approaches (rejected):
Option A: Timestamps only
**Action:** Implement auth
**Source:** [00:15:32]
Option B: Anchors only
**Action:** Implement auth
**Source:** #act-001
Combined approach:
**Action:** Implement auth
**Anchor:** #act-001
**Source:** [00:15:32] Alice (#spk-001)
**Utterance:** #utt-042
Benefits:
Cost: ~10ms per transcript for anchor generation (acceptable)
One-Way Door:
Why can't ts-parser spawn sub-parsers?
Hypothetical violation:
transcript-orchestrator
└─ ts-parser
└─ ts-format-detector (subagent)
└─ ts-encoding-fixer (subagent)
└─ ... (infinite recursion risk)
Risks:
"Agents SHALL NOT spawn subagents that spawn additional subagents. Maximum nesting depth is ONE level (orchestrator → worker)."
Rationale:
Allowed:
transcript-orchestrator (L0)
├─ ts-parser (L1 worker)
├─ ts-extractor (L1 worker)
├─ ts-formatter (L1 worker)
├─ ts-mindmap-mermaid (L1 worker)
├─ ts-mindmap-ascii (L1 worker)
└─ ps-critic (L1 worker)
Forbidden:
transcript-orchestrator (L0)
└─ ts-parser (L1)
└─ ts-subagent (L2) ❌ VIOLATION
Constraint forces flat architecture:
Trade-off:
Alternative (rejected): Allow 2 levels
| Agent | Model | Role | Output |
|---|---|---|---|
ts-parser v2.0 | haiku | ORCHESTRATOR: Route VTT→Python, others→LLM. Validate and chunk. | index.json + chunks/*.json |
ts-extractor | sonnet | Extract speakers, actions, decisions, questions, topics | extraction-report.json |
ts-formatter | sonnet | Generate Markdown packet with navigation | transcript-{id}/ directory |
ts-mindmap-mermaid | sonnet | Generate Mermaid mindmap with deep links (ADR-003) | 08-mindmap/mindmap.mmd |
ts-mindmap-ascii | sonnet | Generate ASCII art mindmap for terminal display | 08-mindmap/mindmap.ascii.txt |
ps-critic | sonnet | Validate quality >= 0.90 threshold (includes MM-/AM- criteria) | quality-review.md |
ts-parser v2.0 (Strategy Pattern Orchestrator):
Four Roles per TDD-FEAT-004:
Capabilities:
index.json + chunks/chunk-NNN.jsonts-extractor (Research Analyst):
ts-formatter (Publishing House):
ts-mindmap-mermaid (Visualization - Mermaid):
ts-mindmap-ascii (Visualization - ASCII):
ps-critic (Quality Inspector):
Orchestrator invokes ts-extractor:
Invoke Task tool with:
- agent: "ts-extractor"
- task: "Extract entities from chunked transcript"
- inputs:
- index_json_path: "<output-dir>/index.json"
- chunks_dir: "<output-dir>/chunks/"
- confidence_threshold: 0.7
- domain: "software-engineering"
ts-extractor's internal workflow:
Orchestrator invokes ts-mindmap-mermaid (conditional):
IF --no-mindmap flag NOT set: # Default behavior
Invoke Task tool with:
- agent: "ts-mindmap-mermaid"
- task: "Generate Mermaid mindmap from extraction report"
- inputs:
- extraction_report_path: "<output-dir>/extraction-report.json"
- packet_path: "<packet-dir>/"
- max_topics: 50
Orchestrator invokes ps-critic:
Invoke Task tool with:
- agent: "ps-critic"
- task: "Validate transcript packet quality"
- inputs:
- packet_path: "<packet-dir>/"
- mindmap_path: "<packet-dir>/08-mindmap/" # If present
- quality_threshold: 0.90
- extension_file: "skills/transcript/validation/ts-critic-extension.md"
Agent invocation sequencing:
SEQUENTIAL (cannot parallelize due to dependencies):
1. ts-parser → outputs index.json + chunks/
2. ts-extractor → reads index.json, outputs extraction-report.json
3. ts-formatter → reads index.json + extraction-report.json, outputs packet/
4. ts-mindmap-* → reads extraction-report.json + packet/, outputs 08-mindmap/
5. ps-critic → reads packet/ + 08-mindmap/, outputs quality-review.md
CRITICAL: The transcript skill execution follows a multi-phase workflow. Phase 1 MUST be executed via the jerry CLI. Subsequent phases use LLM agents.
The transcript skill responds to these natural language patterns:
| Pattern Type | Examples | Detected As |
|---|---|---|
| Direct file reference | "Process meeting.vtt" "Parse the transcript at /path/to/file" | File path extraction |
| Action-oriented | "Extract action items from..." "Analyze the team meeting..." | Task + implicit file |
| Domain-specific | "Generate mindmap from standup" "Process the architecture review" | Feature + implicit file |
| Slash command | /transcript meeting.vtt/transcript parse file.srt | Explicit skill invocation |
Skill Activation Keywords (from header):
/transcript <file-path> [OPTIONS]
Available Options:
--output-dir <dir> # Output directory (default: ./transcript-output/)
--format <vtt|srt|txt> # Force format detection
--domain <domain-name> # Context injection domain (default: general)
--no-mindmap # Disable mindmap generation (mindmaps ON by default)
--mindmap-format <format> # mermaid | ascii | both (default: both)
--model-parser <model> # haiku | sonnet | opus (default: haiku)
--model-extractor <model> # haiku | sonnet | opus (default: sonnet)
--model-formatter <model> # haiku | sonnet | opus (default: sonnet)
--model-mindmap <model> # haiku | sonnet | opus (default: sonnet)
--model-critic <model> # haiku | sonnet | opus (default: sonnet)
Examples (Basic Usage - Default Mindmaps):
/transcript meeting.vtt # Mindmaps ON (both formats)
/transcript standup.srt --output-dir ./docs/meetings/ # With output directory
/transcript notes.txt --format txt # Force format detection
/transcript meeting.vtt --domain software-engineering # With domain context
Examples (Mindmap Control):
/transcript meeting.vtt --mindmap-format mermaid # Only Mermaid format
/transcript meeting.vtt --mindmap-format ascii # Only ASCII format
/transcript meeting.vtt --mindmap-format both # Both formats (explicit)
/transcript meeting.vtt --no-mindmap # Skip mindmap generation
Examples (Model Selection):
# Higher quality extraction (use Opus for entities)
/transcript meeting.vtt --model-extractor opus
# Lower cost processing (use Haiku for all agents)
/transcript meeting.vtt \
--model-parser haiku \
--model-extractor haiku \
--model-formatter haiku \
--model-mindmap haiku \
--model-critic haiku
# Balanced optimization (Haiku for templates, Sonnet for semantic work)
/transcript meeting.vtt \
--model-parser haiku \
--model-formatter haiku \
--model-mindmap haiku
"Process the transcript at /path/to/meeting.vtt"
"Extract action items from yesterday's team meeting"
"Analyze the quarterly review transcript and create a summary"
"Process the meeting transcript and generate mindmaps"
"Parse the standup notes without mindmaps"
"Create a Mermaid-only mindmap from the transcript"
"Use high-quality extraction for this transcript" (triggers --model-extractor opus)
Detection Algorithm:
--no-mindmap)PURPOSE: Learn from common mistakes to avoid failed invocations and understand error recovery.
What NOT to Do:
/transcript meeting.vtt
# Error: File not found - meeting.vtt
Error Output:
Error: Input file 'meeting.vtt' does not exist
Expected: Absolute path or path relative to current working directory
Example: /Users/me/transcripts/meeting.vtt
Correct Invocation:
/transcript /Users/me/transcripts/meeting.vtt
# OR with relative path from current directory
/transcript ./transcripts/meeting.vtt
What NOT to Do:
uv run jerry transcript parse /Users/me/my meetings/meeting.vtt
# Error: Treats "my" and "meetings/meeting.vtt" as separate arguments
Error Output:
Error: Invalid invocation - multiple positional arguments detected
Detected: ['/Users/me/my', 'meetings/meeting.vtt']
Solution: Quote file paths containing spaces
Correct Invocation:
uv run jerry transcript parse "/Users/me/my meetings/meeting.vtt"
What NOT to Do:
/transcript meeting.vtt --output-dir /nonexistent/path/
# Error: Output directory parent does not exist
Error Output:
Error: Cannot create output directory '/nonexistent/path/'
Parent directory '/nonexistent/' does not exist
Solution: Ensure parent directory exists OR use default (./transcript-output/)
Correct Invocation:
# Option 1: Use default output directory
/transcript meeting.vtt
# Option 2: Create parent directory first
mkdir -p /path/to/outputs/
/transcript meeting.vtt --output-dir /path/to/outputs/meeting-001/
What NOT to Do:
/transcript meeting.vtt --domain engineering
# Error: Domain 'engineering' not recognized
Error Output:
Error: Unknown domain 'engineering'
Available domains: general, transcript, meeting, software-engineering,
software-architecture, product-management, user-experience,
cloud-engineering, security-engineering
Did you mean: software-engineering?
Correct Invocation:
/transcript meeting.vtt --domain software-engineering
What NOT to Do:
/transcript meeting.vtt --no-mindmap --mindmap-format mermaid
# Error: Contradictory flags
Error Output:
Error: Conflicting flags detected
--no-mindmap: Disables all mindmap generation
--mindmap-format mermaid: Requests specific mindmap format
Solution: Remove one of these flags
Correct Invocation:
# Option 1: Disable mindmaps (ignores --mindmap-format)
/transcript meeting.vtt --no-mindmap
# Option 2: Generate Mermaid mindmap only
/transcript meeting.vtt --mindmap-format mermaid
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
input_file | string | Yes | - | Path to transcript file |
output_dir | string | No | ./transcript-output/ | Output directory for packet |
format | string | No | auto-detect | Force format: vtt, srt, txt |
domain | string | No | general | Context injection domain (9 available) |
confidence_threshold | float | No | 0.7 | Minimum confidence for extractions |
quality_threshold | float | No | 0.9 | ps-critic quality threshold |
--no-mindmap | flag | No | false | Disable mindmap generation |
--mindmap-format | string | No | "both" | Format: mermaid, ascii, both |
--model-parser | string | No | haiku | Model for ts-parser |
--model-extractor | string | No | sonnet | Model for ts-extractor |
--model-formatter | string | No | sonnet | Model for ts-formatter |
--model-mindmap | string | No | sonnet | Model for ts-mindmap-* |
--model-critic | string | No | sonnet | Model for ps-critic |
The transcript skill supports configurable models for each agent to optimize cost and quality.
| Parameter | Default | Description |
|---|---|---|
--model-parser | haiku | Model for ts-parser (orchestration, routing) |
--model-extractor | sonnet | Model for ts-extractor (entity extraction) |
--model-formatter | sonnet | Model for ts-formatter (packet generation) |
--model-mindmap | sonnet | Model for ts-mindmap-* (visualization) |
--model-critic | sonnet | Model for ps-critic (quality review) |
Valid Model Values: haiku, sonnet, opus
Based on Anthropic Claude pricing (as of 2026-01-30) for 10,000 input tokens:
| Configuration | Estimated Cost | Quality Trade-off | Use Case |
|---|---|---|---|
| Default (mixed) | ~$0.12 | Balanced cost and quality | Recommended for most workflows |
| All haiku | ~$0.015 | 88% savings, lower extraction quality | Budget-constrained, simple transcripts |
| All sonnet | ~$0.15 | Baseline quality | Consistent quality across all agents |
| All opus | ~$0.75 | Highest quality, 6x cost | Critical meetings, high-stakes content |
Cost Breakdown (Default):
# Use haiku for all agents except extractor
uv run jerry transcript parse meeting.vtt \
--model-parser haiku \
--model-extractor haiku \
--model-formatter haiku \
--model-mindmap haiku \
--model-critic haiku
# Cost: ~$0.015 per 10K tokens
# Trade-off: Lower entity extraction accuracy (~70-75%)
# Use opus for critical extraction and review
uv run jerry transcript parse meeting.vtt \
--model-extractor opus \
--model-critic opus
# Cost: ~$0.45 per 10K tokens (with default haiku/sonnet mix)
# Trade-off: 3.75x cost increase, highest extraction accuracy (~95%+)
# Use defaults (mixed haiku/sonnet)
uv run jerry transcript parse meeting.vtt
# Cost: ~$0.12 per 10K tokens
# Trade-off: Optimal cost/quality balance (~85-90% accuracy)
# Use haiku for formatting (template-based, low semantic complexity)
# Keep sonnet for extraction and review (semantic understanding required)
uv run jerry transcript parse meeting.vtt \
--model-formatter haiku \
--model-mindmap haiku
# Cost: ~$0.09 per 10K tokens
# Trade-off: 25% savings with minimal quality impact
| Agent | Recommended Model | Rationale |
|---|---|---|
| ts-parser | haiku | Minimal semantic work - orchestration and routing only |
| ts-extractor | sonnet or opus | Core extraction quality - most critical for accuracy |
| ts-formatter | haiku or sonnet | Template-based generation - haiku sufficient if extraction is good |
| ts-mindmap-* | sonnet | Hierarchical reasoning - benefits from sonnet's structure understanding |
| ps-critic | sonnet | Quality evaluation - needs reliable judgment |
When to Upgrade to Opus:
Model profiles provide quick-select configurations optimized for common use cases. Profiles replace manual configuration of individual --model-* flags.
| Profile | Description | Use Case | Trade-off |
|---|---|---|---|
| economy | All haiku | High-volume processing, budget constraints | Lower extraction quality (~70-75% accuracy) |
| balanced | Mixed haiku/sonnet (default) | General purpose processing | Balanced cost and quality (~85-90% accuracy) |
| quality | Opus for critical agents | Critical meetings, complex content | Higher cost (~3.75x increase) |
| speed | All haiku | Real-time processing, quick turnaround | Quality for speed (~70-75% accuracy) |
| Agent | economy | balanced | quality | speed |
|---|---|---|---|---|
| ts-parser | haiku | haiku | sonnet | haiku |
| ts-extractor | haiku | sonnet | opus | haiku |
| ts-formatter | haiku | haiku | sonnet | haiku |
| ts-mindmap-* | haiku | sonnet | sonnet | haiku |
| ps-critic | haiku | sonnet | opus | haiku |
# Use economy profile (all haiku)
uv run jerry transcript parse meeting.vtt --profile economy
# Use quality profile (opus for extractor and critic)
uv run jerry transcript parse meeting.vtt --profile quality
# Use speed profile (same as economy, but emphasizes latency)
uv run jerry transcript parse meeting.vtt --profile speed
Individual --model-* flags take precedence over --profile:
# Use economy profile, but upgrade extractor to opus
uv run jerry transcript parse meeting.vtt \
--profile economy \
--model-extractor opus
# Result: haiku for all agents EXCEPT extractor (opus)
# Use quality profile, but downgrade formatter to haiku
uv run jerry transcript parse meeting.vtt \
--profile quality \
--model-formatter haiku
# Result: opus for extractor/critic, sonnet for parser/mindmap, haiku for formatter
If neither --profile nor individual --model-* flags are specified:
balanced--profile balancedModel selection follows this precedence (highest to lowest):
--model-* flags (highest priority)--profile flagbalanced)Example:
# What model does ts-extractor use?
uv run jerry transcript parse meeting.vtt
# → sonnet (from default "balanced" profile)
uv run jerry transcript parse meeting.vtt --profile economy
# → haiku (from "economy" profile)
uv run jerry transcript parse meeting.vtt --profile economy --model-extractor opus
# → opus (explicit flag overrides profile)
Based on 10,000 input tokens:
| Profile | Estimated Cost | vs. Balanced |
|---|---|---|
| economy | ~$0.015 | 88% savings |
| balanced (default) | ~$0.12 | Baseline |
| quality | ~$0.45 | 3.75x increase |
| speed | ~$0.015 | 88% savings |
economy:
balanced (default):
quality:
speed:
When to Use Haiku:
transcript-{id}/
├── canonical/ # v2.0: Hybrid parser output
│ ├── canonical-transcript.json # Full parsed transcript
│ ├── index.json # Chunk index with metadata
│ └── chunks/ # Chunked segments (500 per file)
│ ├── chunk-000.json # Segments 0-499
│ ├── chunk-001.json # Segments 500-999
│ └── ...
├── 00-index.md # Navigation hub (~2K tokens)
├── 01-summary.md # Executive summary (~5K tokens)
├── 02-transcript.md # Full transcript (may split)
├── 03-speakers.md # Speaker directory
├── 04-action-items.md # Action items with citations
├── 05-decisions.md # Decisions with context
├── 06-questions.md # Open questions
├── 07-topics.md # Topic segments
├── 08-mindmap/ # Mindmap directory (default: enabled, per ADR-006)
│ ├── mindmap.mmd # Mermaid format (if --mindmap-format mermaid or both)
│ └── mindmap.ascii.txt # ASCII format (if --mindmap-format ascii or both)
└── _anchors.json # Anchor registry for linking
{
"schema_version": "1.0",
"generated_at": "2026-01-30T18:00:00Z",
"total_segments": 710,
"total_chunks": 4,
"chunk_size": 500,
"target_tokens": 18000,
"duration_ms": 2263888,
"speakers": {
"count": 3,
"list": ["Alex Johnson", "Sam Chen", "Jordan Lee"],
"segment_counts": {"Alex Johnson": 459, "Sam Chen": 156, "Jordan Lee": 95}
},
"chunks": [
{
"chunk_id": "chunk-001",
"segment_range": [1, 229],
"timestamp_range": {"start_ms": 3528, "end_ms": 721925},
"speaker_counts": {"Alex Johnson": 151, "Sam Chen": 39, "Jordan Lee": 39},
"word_count": 2193,
"file": "chunks/chunk-001.json"
}
]
}
Key Fields:
target_tokens: When set (e.g., 18000), uses token-based chunking. When null, uses segment-based (500 segs/chunk).chunk_size: Fallback for segment-based mode (used when target_tokens is null).| Parameter | Value | Source |
|---|---|---|
| Claude Code Read limit | 25,000 tokens | GitHub Issue #4002 |
| Target tokens per chunk | 18,000 tokens | 25% safety margin |
| Token counting | tiktoken p50k_base | Best Claude approximation |
Note: Prior to v2.1, chunks used segment-based splitting (500 segments per chunk). v2.1 uses token-based splitting to ensure chunks fit within Claude Code's Read tool limits. This fixes BUG-001 where large transcripts produced chunks exceeding the 25K token limit.
| Limit | Tokens | Action |
|---|---|---|
| Soft | 31,500 | Split at ## heading |
| Hard | 35,000 | Force split |
CRITICAL: Output structure MUST be identical regardless of which LLM model (Sonnet, Opus, Haiku) executes the skill. ADR-007 defines the golden template specification.
| Number | File | Description |
|---|---|---|
| 00 | 00-index.md | Navigation hub and metadata |
| 01 | 01-summary.md | Executive summary |
| 02 | 02-transcript.md | Full formatted transcript (splittable) |
| 03 | 03-speakers.md | Speaker directory |
| 04 | 04-action-items.md | Action items with citations |
| 05 | 05-decisions.md | Decisions with context |
| 06 | 06-questions.md | Open and answered questions |
| 07 | 07-topics.md | Topic hierarchy |
Also Required: _anchors.json (anchor registry)
| Forbidden Pattern | Reason |
|---|---|
*-timeline.md | Not part of ADR-002 schema |
*-sentiment.md | Not part of ADR-002 schema |
*-analysis.md | Not part of ADR-002 schema |
08-*.md | 08 reserved for mindmap directory |
Unnumbered *.md | All core files must be numbered 00-07 |
| Entity | Pattern | Valid | Invalid |
|---|---|---|---|
| Segment | seg-NNN | seg-001 | segment-001, SEG-001 |
| Speaker | spk-{slug} | spk-alice-smith | speaker-alice |
| Action | act-NNN | act-001 | AI-001, ACT-001 |
| Decision | dec-NNN | dec-001 | DEC-001 |
| Question | que-NNN | que-001 | QUE-001 |
| Topic | top-NNN | top-001 | TOP-001 |
NNN = 3-digit, zero-padded (001-999)
> "{QUOTED_TEXT}"
>
> -- [{SPEAKER}](03-speakers.md#{spk-slug}), [[{TIMESTAMP}]](02-transcript.md#{seg-NNN})
FORBIDDEN: Links to canonical-transcript.json (file too large for LLM context)
Every entity file (01-07) MUST include:
## Navigation
- [Back to Index](00-index.md)
- [Previous: {PREV_FILE_NAME}]({PREV_FILE}.md)
- [Next: {NEXT_FILE_NAME}]({NEXT_FILE}.md)
Reference: See ADR-007 for complete specification.
ts-formatter generates packet files using Write tool:
# Create 00-index.md
Invoke Write tool with:
- file_path: "<packet-dir>/00-index.md"
- content: (generated index content with navigation links)
# Create 01-summary.md
Invoke Write tool with:
- file_path: "<packet-dir>/01-summary.md"
- content: (executive summary with key findings)
# Create 04-action-items.md
Invoke Write tool with:
- file_path: "<packet-dir>/04-action-items.md"
- content: (action items with citations and anchors)
Content structure example (04-action-items.md):
# Action Items
<!-- Anchor: #act-001 -->
## 1. Implement user authentication
**Assigned to:** Alice
**Priority:** High
**Due date:** Next sprint
**Source:**
- Timestamp: [00:15:32]
- Speaker: Alice (#spk-001)
- Utterance: #utt-042
**Context:**
> "We need to implement user authentication before the beta launch. I'll take this on for next sprint."
---
<!-- Anchor: #act-002 -->
## 2. Fix navigation bug
...
File size validation:
After writing each file:
Count tokens using Claude's tokenizer
IF tokens > 35000:
Split at semantic boundary (## heading)
Create part-002, part-003, etc.
MANDATORY: Agents MUST follow these file consumption rules to prevent context window overflow. Violating these rules causes degraded performance and potential failures.
| File | Typical Size | Agent | Purpose |
|---|---|---|---|
index.json | ~8KB | ts-extractor, ts-formatter | Metadata, speaker list, chunk references |
chunks/chunk-*.json | ~130KB each | ts-extractor | Actual transcript data in manageable pieces |
extraction-report.json | ~35KB | ts-formatter, ps-critic | Entity extraction results |
packet/*.md | Variable | ps-critic | Generated Markdown files for quality review |
| File | Typical Size | Why Forbidden |
|---|---|---|
canonical-transcript.json | ~930KB | TOO LARGE - will overwhelm context window, cause context rot, degrade agent performance |
The canonical-transcript.json file is generated for:
The chunking architecture (DISC-009) was specifically designed to solve the large file problem:
| Agent | Reads | Never Reads |
|---|---|---|
| ts-parser | Input VTT/SRT/TXT file | - |
| ts-extractor | index.json, chunks/*.json | canonical-transcript.json |
| ts-formatter | index.json, extraction-report.json | canonical-transcript.json |
| ps-critic | All packet/*.md files, quality-review.md | canonical-transcript.json |
STEP 1: PARSE + CHUNK (ts-parser v2.0)
──────────────────────────────────────
Input: Raw transcript file (VTT/SRT/TXT)
Process:
1. Detect format (VTT header check)
2. IF VTT:
- Delegate to Python parser (Bash tool)
- Validate output schema
- Chunk to 500-segment files
3. ELSE (SRT/TXT):
- Use LLM parsing (fallback)
- Chunk if large file
Output: index.json + chunks/chunk-NNN.json
Errors: Python failure → fallback to LLM parsing
STEP 2: EXTRACT (ts-extractor)
──────────────────────────────
Input: index.json + chunks/*.json (NEVER canonical-transcript.json)
Process:
1. Read index.json for metadata and chunk listing
2. Process each chunk sequentially for entity extraction
3. Extract entities with confidence scores and citations
Output: extraction-report.json
Errors: Low confidence extractions → flag for review
STEP 3: FORMAT (ts-formatter)
─────────────────────────────
Input: index.json + extraction-report.json (NEVER canonical-transcript.json)
Output: packet/ directory (8 files per ADR-002)
Errors: Token overflow → split files automatically (ADR-004)
STEP 3.5: MINDMAP GENERATION (ts-mindmap-*, conditional - ADR-006)
──────────────────────────────────────────────────────────────────
Condition: --no-mindmap flag NOT set (mindmaps ON by default)
Input: ts_extractor_output.extraction_report_path + ts_formatter_output.packet_path
Process:
1. IF --no-mindmap flag is NOT set: # Default behavior
- IF --mindmap-format == "mermaid" OR "both" (default):
Invoke ts-mindmap-mermaid
Output: 08-mindmap/mindmap.mmd
- IF --mindmap-format == "ascii" OR "both" (default):
Invoke ts-mindmap-ascii
Output: 08-mindmap/mindmap.ascii.txt
2. ELSE:
- Skip mindmap generation (user opted out)
- ts_mindmap_output.overall_status = "skipped"
Output: ts_mindmap_output state key
Errors: Graceful degradation - continue with warning, provide regeneration instructions
STEP 4: REVIEW (ps-critic)
──────────────────────────
Input: All generated files
Output: quality-review.md
Errors: Score < 0.90 → report issues for human review
PURPOSE: State keys provide persistence across agent boundaries, enabling:
- Error recovery - Agents can resume from last checkpoint
- Debugging - Full pipeline trace in state history
- Quality assurance - ps-critic validates entire pipeline state
| Agent | Output Key | Passed To | Purpose |
|---|---|---|---|
| ts-parser v2.0 | ts_parser_output | ts-extractor | Parsing results + chunk metadata |
| ts-extractor | ts_extractor_output | ts-formatter | Extraction report + stats |
| ts-formatter | ts_formatter_output | ts-mindmap-*, ps-critic | Packet location + file manifest |
| ts-mindmap-* | ts_mindmap_output | ps-critic | Mindmap paths + generation status |
| ps-critic | quality_output | User/Orchestrator | Quality validation results |
State Schema (v2.0):
ts_parser_output:
# === Core Parsing Results (v2.0 Chunked Architecture) ===
canonical_json_path: string # Full transcript JSON (archive only, ~930KB)
index_json_path: string # Chunk index metadata (~8KB)
chunks_dir: string # chunks/ directory path
chunk_count: integer # Number of chunk files created
# === Parsing Metadata ===
format_detected: vtt|srt|plain # Auto-detected or forced format
parsing_method: python|llm # Strategy Pattern routing decision
segment_count: integer # Total segments in transcript
speaker_count: integer # Unique speakers identified
duration_ms: integer|null # Transcript duration (null for plain text)
# === Quality/Validation ===
validation_passed: boolean # Schema validation result
warnings: string[] # Non-fatal parsing issues
# === Error Handling ===
errors: string[] # Fatal errors (if any)
fallback_triggered: boolean # True if Python→LLM fallback occurred
ts_extractor_output:
# === Core Extraction Results ===
extraction_report_path: string # Path to extraction-report.json (~35KB)
# === Entity Counts (MUST match array lengths per INV-EXT-001) ===
action_count: integer # len(action_items) - MANDATORY consistency
decision_count: integer # len(decisions) - MANDATORY consistency
question_count: integer # len(questions) - MANDATORY consistency
topic_count: integer # len(topics) - MANDATORY consistency
speaker_count: integer # len(speakers) - MANDATORY consistency
# === Quality Metrics ===
high_confidence_ratio: float # Ratio of high-confidence extractions
average_confidence: float # Mean confidence across all entities
# === Processing Metadata ===
chunks_processed: integer # Number of chunks analyzed
input_format: "chunked"|"single_file" # Input format used
# === Tiered Extraction Stats ===
tier_1_count: integer # Rule-based extractions (high confidence)
tier_2_count: integer # ML-based extractions (medium confidence)
tier_3_count: integer # LLM-based extractions (variable confidence)
ts_formatter_output:
# === Core Output ===
packet_path: string # Directory path to 8-file packet
# === File Manifest ===
files_created: string[] # List of all created files
split_files: integer # Number of files split due to token limits
# === Token Accounting ===
total_tokens: integer # Sum of tokens across all files
max_file_tokens: integer # Largest file token count
# === Linking Metadata ===
anchor_count: integer # Total anchors in registry
backlink_count: integer # Total backlinks generated
# === Validation ===
all_files_under_limit: boolean # True if all < 35K tokens per ADR-004
ts_mindmap_output: # NEW: ADR-006 State Passing (see ADR-006#state-passing)
# === Mindmap Control ===
enabled: boolean # Was --no-mindmap NOT set?
format_requested: string # "mermaid" | "ascii" | "both"
# === Mermaid Mindmap ===
mermaid:
path: string | null # Path to 08-mindmap/mindmap.mmd
status: string # "complete" | "failed" | "skipped"
error_message: string | null # Error if status="failed"
topic_count: integer # Topics included in mindmap
deep_link_count: integer # Deep links in reference block
syntax_validated: boolean # Mermaid syntax check passed
# === ASCII Mindmap ===
ascii:
path: string | null # Path to 08-mindmap/mindmap.ascii.txt
status: string # "complete" | "failed" | "skipped"
error_message: string | null # Error if status="failed"
topic_count: integer # Topics included in mindmap
max_line_width: integer # Maximum line width used (should be <= 80)
box_drawing_valid: boolean # UTF-8 box-drawing characters validated
# === Overall Status ===
overall_status: string # "complete" | "partial" | "failed" | "skipped"
regeneration_command: string | null # Command to regenerate if failed
quality_output:
# === Quality Score ===
quality_score: float # Aggregate score (0.0-1.0)
passed: boolean # True if >= quality_threshold (default 0.90)
# === Validation Results ===
issues: string[] # Quality gate failures
recommendations: string[] # Improvement suggestions
# === Criteria Breakdown ===
criteria_scores: dict # Per-criterion scores (e.g., "T-001": 0.95)
mindmap_criteria_applied: boolean # True if MM-*/AM-* criteria checked
# === Traceability ===
artifacts_validated: string[] # List of files checked
validation_timestamp: string # ISO 8601 timestamp
PURPOSE: Document how agents communicate errors through state keys. Enables downstream agents to detect and handle failures gracefully.
When an agent encounters an error, it MUST populate error-specific fields in its output state key:
{agent}_output:
# === Standard Error Fields (ALL agents MUST include) ===
status: string # "success" | "partial" | "failed"
errors: string[] # Fatal errors that halted execution
warnings: string[] # Non-fatal issues that may affect quality
# === Error Recovery Metadata ===
recovery_possible: boolean # Can this error be recovered from?
recovery_command: string | null # CLI command to retry/resume
recovery_instructions: string | null # Human-readable recovery steps
# === Agent-Specific Error Context ===
error_context: dict | null # Additional diagnostic information
ts-parser Error (Python Parser Failure):
ts_parser_output:
status: "partial" # Fallback succeeded, but not preferred path
canonical_json_path: "/path/to/canonical-transcript.json"
index_json_path: "/path/to/index.json"
chunks_dir: "/path/to/chunks/"
chunk_count: 3
# Error tracking
errors:
- "Python VTT parser failed: UnicodeDecodeError at line 42"
warnings:
- "Fallback to LLM parsing - increased cost and latency"
# Recovery info
fallback_triggered: true
recovery_possible: false # Already recovered via fallback
recovery_instructions: "LLM fallback completed successfully. No action required."
# Diagnostic context
error_context:
python_error_type: "UnicodeDecodeError"
failed_encoding: "utf-8"
attempted_fallback_encodings: ["windows-1252", "iso-8859-1"]
fallback_method: "llm"
fallback_model: "sonnet"
ts-extractor Error (Context Overflow):
ts_extractor_output:
status: "failed" # Cannot proceed
extraction_report_path: null # No output generated
# Fatal error
errors:
- "Context window exceeded: chunk-042.json is 45,000 tokens (limit: 35,000)"
- "Cannot process chunk without splitting"
warnings: []
# Recovery info
recovery_possible: true
recovery_command: "uv run jerry transcript parse <file> --chunk-target-tokens 15000"
recovery_instructions: >
Re-run parsing with smaller chunk size to prevent context overflow.
Use --chunk-target-tokens 15000 (down from default 18000) to reduce chunk size.
# Diagnostic context
error_context:
failed_chunk_id: "chunk-042"
failed_chunk_tokens: 45000
chunk_token_limit: 35000
suggestion: "Lower --chunk-target-tokens parameter"
ts-formatter Error (File Write Failure):
ts_formatter_output:
status: "failed"
packet_path: "/output/transcript-meeting-001/" # Directory created but incomplete
# Partial completion tracking
files_created:
- "00-index.md"
- "01-summary.md"
- "02-transcript.md"
files_failed:
- "03-speakers.md"
- "04-action-items.md"
- "05-decisions.md"
- "06-questions.md"
- "07-topics.md"
# Fatal error
errors:
- "IOError: Permission denied writing to /output/transcript-meeting-001/03-speakers.md"
warnings: []
# Recovery info
recovery_possible: true
recovery_command: "chmod 755 /output/transcript-meeting-001/ && /transcript resume --from formatting"
recovery_instructions: >
Fix directory permissions and resume formatting phase.
Existing files (00-02) will be skipped if valid.
# Diagnostic context
error_context:
permission_error_path: "/output/transcript-meeting-001/03-speakers.md"
directory_permissions: "dr-xr-xr-x"
required_permissions: "drwxr-xr-x"
ts-mindmap-mermaid Error (Syntax Validation Failure):
ts_mindmap_output:
enabled: true
format_requested: "both"
# Mermaid failed
mermaid:
path: "/output/08-mindmap/mindmap.mmd" # File created but invalid
status: "failed"
error_message: "Mermaid syntax validation failed: Invalid node syntax at line 12"
topic_count: 0
deep_link_count: 0
syntax_validated: false
# ASCII succeeded
ascii:
path: "/output/08-mindmap/mindmap.ascii.txt"
status: "complete"
error_message: null
topic_count: 47
max_line_width: 79
box_drawing_valid: true
# Overall status
overall_status: "partial" # ASCII succeeded, Mermaid failed
errors:
- "Mermaid mindmap generation failed: Syntax error (markdown link in node)"
warnings:
- "Mermaid mindmap unavailable - ASCII mindmap generated successfully"
# Recovery info
recovery_possible: true
regeneration_command: "uv run jerry transcript mindmap --format mermaid --packet-path /output/"
recovery_instructions: >
Mermaid syntax error likely caused by markdown links in node text.
The ts-mindmap-mermaid agent uses plain text ONLY in nodes per ADR-003 Section 5.3.
ASCII mindmap is valid and can be used. To retry Mermaid generation:
1. Review deep link reference block format
2. Ensure no markdown syntax in topic text
3. Run regeneration command above
quality_output Error (Quality Gate Failure):
quality_output:
quality_score: 0.68 # Below threshold
passed: false # Failed quality gate
# Quality failures
issues:
- "T-001: Missing timestamps in 23% of segments"
- "T-004: Low citation coverage (42% of extractions lack source anchors)"
- "T-006: Token limit exceeded in 02-transcript-part-003.md (37,500 tokens)"
- "MM-002: Mermaid mindmap missing deep link reference block"
recommendations:
- "Re-run parsing to fix timestamp gaps"
- "Ensure ts-extractor includes segment_id in all citations"
- "Re-run ts-formatter with stricter token splitting (31.5K soft limit)"
- "Add deep link reference block to Mermaid mindmap per ADR-003 Section 5.3"
# Criteria breakdown
criteria_scores:
"T-001": 0.77 # Timestamp completeness
"T-002": 0.95 # Speaker attribution
"T-003": 0.90 # Segment ordering
"T-004": 0.42 # Citation coverage
"T-005": 0.85 # Confidence scoring
"T-006": 0.50 # Token budget compliance
"MM-002": 0.00 # Deep link reference block
mindmap_criteria_applied: true
artifacts_validated:
- "00-index.md"
- "01-summary.md"
- "02-transcript-part-001.md"
- "02-transcript-part-002.md"
- "02-transcript-part-003.md" # Failed token limit
- "08-mindmap/mindmap.mmd" # Missing reference block
- "08-mindmap/mindmap.ascii.txt" # Passed
validation_timestamp: "2026-01-30T19:15:00Z"
# Error tracking
errors: [] # No fatal errors, just quality failures
warnings:
- "Quality score 0.68 below threshold 0.90"
status: "failed"
# Recovery info
recovery_possible: true
recovery_command: null # No single command - requires manual fixes
recovery_instructions: >
Address the 4 high-priority issues listed above and re-run ps-critic.
Critical failures:
1. T-004 (citation coverage) - Re-run ts-extractor with citation enforcement
2. T-006 (token limits) - Re-run ts-formatter with --split-at-soft-limit flag
3. MM-002 (deep links) - Re-run ts-mindmap-mermaid with reference block generation
When an error in one agent cascades to downstream agents:
# ts-parser fails completely (no fallback)
ts_parser_output:
status: "failed"
errors:
- "Fatal: Input file is corrupted (invalid WebVTT structure)"
recovery_possible: false
recovery_instructions: "Provide a valid VTT, SRT, or TXT file"
# ts-extractor cannot proceed (missing input)
ts_extractor_output:
status: "failed"
errors:
- "Missing required input: ts_parser_output.index_json_path"
- "Cannot extract entities without parsed transcript"
recovery_possible: false
recovery_instructions: "Fix ts-parser errors before proceeding to extraction"
# ts-formatter skipped (dependency failure)
ts_formatter_output:
status: "skipped"
errors:
- "Skipped due to upstream failure: ts-extractor.status = 'failed'"
recovery_possible: false
# Pipeline halts completely
overall_pipeline_status: "failed"
failed_phase: "parsing"
recovery_instructions: "Fix input file and restart pipeline from beginning"
| Error Type | Behavior | State Impact |
|---|---|---|
| Fatal Error | Stop pipeline immediately | Set status: "failed" in current agent output |
| Warning | Continue pipeline | Add to warnings[] array, log in state |
| Validation Failure | Agent-specific decision | ts-parser: fallback to LLM; ts-extractor: skip low-confidence |
| Missing Input | Fatal error | Cannot proceed, report missing dependency |
Before ts-extractor:
REQUIRED from ts_parser_output:
- index_json_path (must exist)
- chunks_dir (must exist)
- chunk_count > 0
- validation_passed == true
Before ts-formatter:
REQUIRED from ts_extractor_output:
- extraction_report_path (must exist)
- action_count == len(action_items) in report (INV-EXT-001)
- decision_count == len(decisions) in report (INV-EXT-001)
- question_count == len(questions) in report (INV-EXT-001)
Before ps-critic:
REQUIRED from ts_formatter_output:
- packet_path (directory must exist)
- files_created (all files must exist)
- all_files_under_limit == true (ADR-004 compliance)
PURPOSE: Provide comprehensive recovery procedures for all known failure modes. Enables self-service recovery without requiring expert intervention.
Symptom:
Error: Python VTT parser failed: UnicodeDecodeError
Fallback: LLM parsing succeeded (increased cost)
Root Cause: VTT file uses non-UTF-8 encoding (e.g., Windows-1252, UTF-16).
Recovery:
# Option 1: Force LLM parsing from the start (skip Python parser)
uv run jerry transcript parse meeting.vtt --force-llm
# Option 2: Convert file to UTF-8 first (preferred)
iconv -f windows-1252 -t utf-8 meeting.vtt > meeting-utf8.vtt
uv run jerry transcript parse meeting-utf8.vtt
Prevention: Ensure VTT files are UTF-8 encoded before processing.
Symptom:
Error: Context window exceeded: chunk-042.json is 45,000 tokens (limit: 35,000)
Status: ts-extractor failed
Root Cause: Chunk exceeds Claude Code Read tool limit (25K tokens). Occurs when transcript has very long monologues.
Recovery:
# Re-parse with smaller chunk size (reduce from default 18K to 12K)
uv run jerry transcript parse meeting.vtt --chunk-target-tokens 12000 --output-dir ./output-v2/
# Then continue from extraction phase
# (ts-parser will automatically trigger ts-extractor with new chunks)
Prevention: Use --chunk-target-tokens 15000 for transcripts with long segments.
Symptom:
Error: IOError: Permission denied writing to /output/transcript-meeting-001/03-speakers.md
Status: ts-formatter failed (partial completion)
Files created: 00-02
Files failed: 03-07
Root Cause: Output directory or parent directory has incorrect permissions.
Recovery:
# Fix directory permissions
chmod 755 /output/transcript-meeting-001/
# Resume formatting phase (will skip existing files 00-02)
uv run jerry transcript resume --from formatting --packet-path /output/transcript-meeting-001/
# OR start fresh with correct permissions
chmod 755 /output/
uv run jerry transcript parse meeting.vtt --output-dir /output/meeting-002/
Prevention: Ensure write permissions on output directory before invoking skill.
Symptom:
Quality Score: 0.68 (threshold: 0.90)
Status: quality_output.passed = false
Issues:
- T-004: Low citation coverage (42%)
- T-006: Token limit exceeded in 02-transcript-part-003.md
Root Cause: Extraction quality issues or token budget violations.
Recovery:
Step 1: Review quality-review.md for specific issues
cat /output/transcript-meeting-001/quality-review.md
Step 2: Address each issue:
For T-004 (citation coverage):
# Re-run extraction with stricter citation enforcement
uv run jerry transcript resume --from extraction --enforce-citations
For T-006 (token limits):
# Re-run formatting with stricter splitting
uv run jerry transcript resume --from formatting --split-at-soft-limit
Step 3: Re-run quality review:
uv run jerry transcript resume --from quality-review
Prevention: Use --model-extractor opus for better extraction quality.
Symptom:
Error: Agent timeout after 300 seconds
Status: ts-extractor failed
Progress: Processed 8/15 chunks before timeout
Root Cause: Very large transcript (> 10,000 segments) exceeds default timeout.
Recovery:
# Increase timeout for extraction phase
uv run jerry transcript parse meeting.vtt --extractor-timeout 600
# OR split transcript into smaller files
uv run python scripts/split_vtt.py meeting.vtt --max-duration 60 # 60 min chunks
uv run jerry transcript parse meeting-part-001.vtt
uv run jerry transcript parse meeting-part-002.vtt
# ... process each part separately
Prevention: For transcripts > 2 hours, consider splitting into segments.
Symptom:
Warning: 45% of action items have confidence < 0.70
Status: ts-extractor succeeded (with warnings)
Root Cause: Ambiguous language, implicit action items, or poor transcript quality.
Recovery:
# Option 1: Use Opus model for better semantic understanding
uv run jerry transcript parse meeting.vtt --model-extractor opus
# Option 2: Lower confidence threshold to include more entities
uv run jerry transcript parse meeting.vtt --confidence-threshold 0.5
# Option 3: Review uncertain entities manually
cat /output/extraction-report.json | jq '.action_items[] | select(.confidence < 0.70)'
Prevention: Improve automatic transcription quality (better audio, less background noise).
Symptom:
Error: Mermaid syntax validation failed: Invalid node syntax at line 12
Status: ts_mindmap_output.mermaid.status = "failed"
Status: ts_mindmap_output.ascii.status = "complete"
Root Cause: Markdown links used in Mermaid node text (ADR-003 limitation).
Recovery:
# Regenerate Mermaid mindmap with plain text enforcement
uv run jerry transcript mindmap --format mermaid --packet-path /output/ --plain-text-only
# OR use ASCII mindmap (already succeeded)
cat /output/08-mindmap/mindmap.ascii.txt
Prevention: ts-mindmap-mermaid agent should strip markdown syntax before node generation.
Symptom:
Error: Output directory already exists: /output/transcript-meeting-001/
Conflict: 00-index.md, 01-summary.md (8 files total)
Root Cause: Previous run output not cleared before re-running.
Recovery:
# Option 1: Delete existing output (CAUTION: data loss)
rm -rf /output/transcript-meeting-001/
uv run jerry transcript parse meeting.vtt --output-dir /output/transcript-meeting-001/
# Option 2: Use timestamped directory (recommended)
uv run jerry transcript parse meeting.vtt --output-dir /output/transcript-meeting-001-$(date +%Y%m%d-%H%M%S)/
# Option 3: Merge mode (preserve existing files, update only changed)
uv run jerry transcript parse meeting.vtt --output-dir /output/transcript-meeting-001/ --merge
Prevention: Use --output-dir with unique names or timestamps.
Symptom:
Error: ModuleNotFoundError: No module named 'tiktoken'
Status: ts-parser failed (cannot perform token counting)
Root Cause: UV environment missing required Python dependencies.
Recovery:
# Sync UV dependencies
uv sync
# Verify installation
uv pip list | grep tiktoken
# Re-run parsing
uv run jerry transcript parse meeting.vtt
Prevention: Run uv sync after pulling changes or switching branches.
Symptom:
Error: State key mismatch: ts_extractor_output.action_count (23) != len(action_items) in extraction-report.json (25)
Violation: INV-EXT-001 (entity count consistency)
Status: ts-formatter refused to proceed
Root Cause: Agent violated state schema invariant (likely a bug).
Recovery:
# Option 1: Regenerate extraction report from chunks