transcript

What this skill does

# MANDATORY: CLI Invocation for Parsing (Phase 1)

> **CRITICAL:** For VTT files, you MUST invoke the Python parser via the `jerry` CLI.
> DO NOT use Task agents for parsing. The CLI provides 1,250x cost reduction and deterministic output.

## Phase 1: Parse Transcript (REQUIRED CLI INVOCATION)

**ARGUMENT PARSING RULES:**
1. The FIRST positional argument from user input is the `<file-path>` (the VTT/SRT file)
2. The `--output-dir` flag specifies the output directory (default: `./transcript-output`)
3. **IMPORTANT:** If user provides `--output`, treat it as `--output-dir` (alias)

**For VTT files, Claude MUST execute this bash command:**

```bash
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:**
```bash
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 summary
- `chunks/chunk-*.json` - Transcript segments in processable chunks
- `canonical-transcript.json` - Full parsed output (for reference only, DO NOT read into context)

### Tool Example: Invoking the Python Parser

**Claude's execution using Bash tool:**

```bash
# Basic invocation
uv run jerry transcript parse "/Users/me/meeting.vtt" --output-dir "/Users/me/output/"
```

**What this does:**
1. Uses `uv run` to execute in managed Python environment
2. Invokes `jerry transcript parse` subcommand
3. Quotes paths to handle spaces/special characters
4. Specifies output directory (creates if doesn't exist)

**Common variations:**

```bash
# 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:**

```bash
# 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
```

---

## Phase 2+: LLM Agent Orchestration

After Phase 1 CLI parsing completes, continue with LLM agents:
1. **ts-extractor** - Read `index.json` + `chunks/*.json`, produce `extraction-report.json`
2. **ts-formatter** - Read `index.json` + `extraction-report.json`, produce packet files
3. **ts-mindmap-*** - Generate mindmaps (if `--no-mindmap` not set)
4. **ps-critic** - Quality review >= 0.90

---

# Transcript Skill

> **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

---

## Document Audience (Triple-Lens)

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](#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:**
- **First Time User:** Start with "Purpose" → "When to Use" → "Invoking the Skill" → "Quick Reference"
- **Integration Developer:** Start with "Agent Pipeline" → "State Passing" → "File Persistence"
- **Quality Assurance:** Start with "Self-Critique Protocol" → "Constitutional Compliance" → "Quality Thresholds"

---

## Purpose

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.

### Key Capabilities

- **Multi-Format Parsing** - VTT, SRT, and plain text transcript formats
- **Semantic Extraction** - Action items, decisions, questions, topics with confidence scores
- **Speaker Identification** - 4-pattern detection chain for reliable attribution
- **Structured Output** - Claude-optimized Markdown packets under 35K tokens
- **Bidirectional Linking** - Every entity linked to its source in the transcript
- **Quality Review** - Integrated ps-critic evaluation (>= 0.90 threshold)

---

## When to Use This Skill

Activate when:

- Processing a meeting transcript from Zoom, Teams, or other platforms
- Extracting action items and decisions from recorded meetings
- Converting VTT/SRT subtitle files to structured notes
- Analyzing plain text meeting notes
- Generating navigable meeting documentation

**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"
```

---

## Domain Selection

The transcript skill supports **9 domain contexts** that customize entity extraction for specific professional contexts. See [DOMAIN-SELECTION-GUIDE.md](./docs/domains/DOMAIN-SELECTION-GUIDE.md) for the complete selection flowchart.

### Available Domains

| 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 |

### Specifying a Domain

```
/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.

---

## Agent Pipeline

```
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)