Asciinema Analyzer

asciinema-analyzer

Semantic analysis of converted .txt recordings for Claude Code consumption. Uses tiered analysis: ripgrep (primary, 50-200ms) -> YAKE (secondary, 1-5s) -> TF-IDF (optional).

Platform: macOS, Linux (requires ripgrep, optional YAKE)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Searching for keywords or patterns in converted recordings
• Extracting topics or themes from session transcripts
• Finding specific commands or errors in session history
• Auto-discovering unexpected terms in recordings
• Analyzing session content for documentation or review

---

Analysis Tiers

Decision: Start with Tier 1 (ripgrep + curated keywords). Only use Tier 2 (YAKE) when auto-discovery is explicitly requested.

---

Requirements

---

Workflow Phases (ALL MANDATORY)

IMPORTANT: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.

Phase 0: Preflight Check

Purpose: Verify input file exists and check for .txt (converted) format.

/usr/bin/env bash << 'PREFLIGHT_EOF'
INPUT_FILE="${1:-}"

if [[ -z "$INPUT_FILE" ]]; then
  echo "NO_FILE_PROVIDED"
elif [[ ! -f "$INPUT_FILE" ]]; then
  echo "FILE_NOT_FOUND: $INPUT_FILE"
elif [[ "$INPUT_FILE" == *.cast ]]; then
  echo "WRONG_FORMAT: Convert to .txt first with /asciinema-tools:convert"
elif [[ "$INPUT_FILE" == *.txt ]]; then
  SIZE=$(ls -lh "$INPUT_FILE" | awk '{print $5}')
  LINES=$(wc -l < "$INPUT_FILE" | tr -d ' ')
  echo "READY: $INPUT_FILE ($SIZE, $LINES lines)"
else
  echo "UNKNOWN_FORMAT: Expected .txt file"
fi
PREFLIGHT_EOF

If no .txt file found, suggest running /asciinema-tools:convert first.

---

Phase 1: File Selection (MANDATORY)

Purpose: Discover .txt files and let user select which to analyze.

Step 1.1: Discover .txt Files

/usr/bin/env bash << 'DISCOVER_TXT_EOF'
# Find .txt files that look like converted recordings
for file in $(fd -e txt . --max-depth 3 2>/dev/null | head -10); do
  SIZE=$(ls -lh "$file" 2>/dev/null | awk '{print $5}')
  LINES=$(wc -l < "$file" 2>/dev/null | tr -d ' ')
  BASENAME=$(basename "$file")
  echo "FILE:$file|SIZE:$SIZE|LINES:$LINES|NAME:$BASENAME"
done
DISCOVER_TXT_EOF

Step 1.2: Present File Selection (MANDATORY AskUserQuestion)

Question: "Which file would you like to analyze?"
Header: "File"
Options:
  - Label: "{filename}.txt ({size})"
    Description: "{line_count} lines"
  - Label: "{filename2}.txt ({size2})"
    Description: "{line_count2} lines"
  - Label: "Enter path"
    Description: "Provide a custom path to a .txt file"
  - Label: "Convert first"
    Description: "Run /asciinema-tools:convert before analysis"

---

Phase 2: Analysis Type (MANDATORY)

Purpose: Let user choose analysis depth.

Question: "What type of analysis do you need?"
Header: "Type"
Options:
  - Label: "Curated keywords (Recommended)"
    Description: "Fast search (50-200ms) with domain-specific keyword sets"
  - Label: "Auto-discover keywords"
    Description: "YAKE unsupervised extraction (1-5s) - finds unexpected patterns"
  - Label: "Full analysis"
    Description: "Both curated + auto-discovery for comprehensive results"
  - Label: "Density analysis"
    Description: "Find high-concentration sections (peak activity windows)"

---

Phase 3: Domain Selection (MANDATORY)

Purpose: Let user select which keyword domains to search.

Question: "Which domain keywords to search?"
Header: "Domain"
multiSelect: true
Options:
  - Label: "Trading/Quantitative"
    Description: "sharpe, sortino, calmar, backtest, drawdown, pnl, cagr, alpha, beta"
  - Label: "ML/AI"
    Description: "epoch, loss, accuracy, sota, training, model, validation, inference"
  - Label: "Development"
    Description: "iteration, refactor, fix, test, deploy, build, commit, merge"
  - Label: "Claude Code"
    Description: "Skill, TodoWrite, Read, Edit, Bash, Grep, iteration complete"

See Domain Keywords Reference for complete keyword lists.

---

Phase 4: Execute Curated Analysis

Purpose: Run Grep searches for selected domain keywords.

Step 4.1: Trading Domain

/usr/bin/env bash << 'TRADING_EOF'
INPUT_FILE="${1:?}"
echo "=== Trading/Quantitative Keywords ==="

KEYWORDS="sharpe sortino calmar backtest drawdown pnl cagr alpha beta roi volatility"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
TRADING_EOF

Step 4.2: ML/AI Domain

/usr/bin/env bash << 'ML_EOF'
INPUT_FILE="${1:?}"
echo "=== ML/AI Keywords ==="

KEYWORDS="epoch loss accuracy sota training model validation inference tensor gradient"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
ML_EOF

Step 4.3: Development Domain

/usr/bin/env bash << 'DEV_EOF'
INPUT_FILE="${1:?}"
echo "=== Development Keywords ==="

KEYWORDS="iteration refactor fix test deploy build commit merge debug error"
for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done
DEV_EOF

Step 4.4: Claude Code Domain

/usr/bin/env bash << 'CLAUDE_EOF'
INPUT_FILE="${1:?}"
echo "=== Claude Code Keywords ==="

KEYWORDS="Skill TodoWrite Read Edit Bash Grep Write"
for kw in $KEYWORDS; do
  COUNT=$(rg -c "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  if [[ "$COUNT" -gt 0 ]]; then
    echo "  $kw: $COUNT"
  fi
done

# Special patterns
ITERATION=$(rg -c "iteration complete" "$INPUT_FILE" 2>/dev/null || echo "0")
echo "  'iteration complete': $ITERATION"
CLAUDE_EOF

---

Phase 5: YAKE Auto-Discovery (if selected)

Purpose: Run unsupervised keyword extraction.

/usr/bin/env bash << 'YAKE_EOF'
INPUT_FILE="${1:?}"
echo "=== Auto-discovered Keywords (YAKE) ==="

uv run --with yake python3 -c "
import yake

kw = yake.KeywordExtractor(
    lan='en',
    n=2,           # bi-grams
    dedupLim=0.9,  # dedup threshold
    top=20         # top keywords
)

with open('$INPUT_FILE') as f:
    text = f.read()

keywords = kw.extract_keywords(text)
for score, keyword in keywords:
    print(f'{score:.4f}  {keyword}')
"
YAKE_EOF

---

Phase 6: Density Analysis (if selected)

Purpose: Find sections with highest keyword concentration.

/usr/bin/env bash << 'DENSITY_EOF'
INPUT_FILE="${1:?}"
KEYWORD="${2:-sharpe}"
WINDOW_SIZE=100  # lines

echo "=== Density Analysis: '$KEYWORD' ==="
echo "Window size: $WINDOW_SIZE lines"
echo ""

TOTAL_LINES=$(wc -l < "$INPUT_FILE" | tr -d ' ')
TOTAL_MATCHES=$(rg -c -i "$KEYWORD" "$INPUT_FILE" 2>/dev/null || echo "0")

echo "Total matches: $TOTAL_MATCHES in $TOTAL_LINES lines"
echo "Overall density: $(echo "scale=4; $TOTAL_MATCHES / $TOTAL_LINES * 1000" | bc) per 1000 lines"
echo ""

# Find peak windows
echo "Top 5 densest windows:"
awk -v ws="$WINDOW_SIZE" -v kw="$KEYWORD" '
BEGIN { IGNORECASE=1 }
{
  lines[NR] = $0
  if (tolower($0) ~ tolower(kw)) matches[NR] = 1
}
END {
  for (start = 1; start <= NR - ws; start += ws/2) {
    count = 0
    for (i = start; i < start + ws && i <= NR; i++) {
      if (matches[i]) count++
    }
    if (count > 0) {
      printf "Lines %d-%d: %d matches (%.1f per 100)\n", start, start+ws-1, count, count*100/ws
    }
  }
}
' "$INPUT_FILE" | sort -t: -k2 -rn | head -5
DENSITY_EOF

---

Phase 7: Report Format (MANDATORY)

Purpose: Let user choose output format.

Question: "How should results be presented?"
Header: "Output"
Options:
  - Label: "Summary table (Recommended)"
    Description: "Keyword counts + top 5 peak sections"
  - Label: "Detailed report"
    Description: "Full analysis with timestamps and surrounding context"
  - Label: "JSON export"
    Description: "Machine-readable output for further processing"
  - Label: "Markdown report"
    Description: "Save formatted report to file"

---

Phase 8: Follow-up Actions (MANDATORY)

Purpose: Guide user to next action.

Question: "Analysis complete. What's next?"
Header: "Next"
Options:
  - Label: "Jump to peak section"
    Description: "Read the highest-density section in the file"
  - Label: "Search for specific keyword"
    Description: "Grep for a custom term with context"
  - Label: "Cross-reference with .cast"
    Description: "Map findings back to original timestamps"
  - Label: "Done"
    Description: "Exit - no further action needed"

---

TodoWrite Task Template

1. [Preflight] Check input file exists and is .txt format
2. [Preflight] Suggest /convert if .cast file provided
3. [Discovery] Find .txt files with line counts
4. [Selection] AskUserQuestion: file to analyze
5. [Type] AskUserQuestion: analysis type (curated/auto/full/density)
6. [Domain] AskUserQuestion: keyword domains (multi-select)
7. [Curated] Run Grep searches for selected domains
8. [Auto] Run YAKE if auto-discovery selected
9. [Density] Calculate density windows if requested
10. [Format] AskUserQuestion: report format
11. [Next] AskUserQuestion: follow-up actions

---

Post-Change Checklist

After modifying this skill:

1. [ ] All bash blocks use heredoc wrapper 2. [ ] Curated keywords match references/domain-keywords.md 3. [ ] Analysis tiers match references/analysis-tiers.md 4. [ ] YAKE invocation uses uv run --with yake 5. [ ] All AskUserQuestion phases are present 6. [ ] TodoWrite template matches actual workflow

---

Reference Documentation

• Domain Keywords Reference
• Analysis Tiers Reference
• ripgrep Manual
• YAKE Documentation

---

Troubleshooting

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing. 1. What failed? — Fix the instruction that caused it. 2. What worked better than expected? — Promote to recommended practice. 3. What drifted? — Fix any script, reference, or dependency that no longer matches reality. 4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

Analysis Tiers Reference

Tiered approach to semantic analysis of terminal recordings.

---

Tier Overview

---

Tier 1: ripgrep + Curated Keywords (Primary)

Always start here. Fastest and most reliable for known domains.

Characteristics

• Speed: 50-200ms for 4MB file
• Accuracy: High (exact matches)
• Dependencies: System ripgrep only
• Best for: Known keyword domains, quick scans

Implementation

/usr/bin/env bash << 'TIER1_EOF'
INPUT_FILE="${1:?}"
KEYWORDS="${2:-sharpe sortino backtest}"

echo "=== Tier 1: Curated Keywords ==="
start=$(date +%s.%N)

for kw in $KEYWORDS; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  [[ "$COUNT" -gt 0 ]] && echo "$kw: $COUNT"
done

end=$(date +%s.%N)
echo ""
echo "Time: $(echo "$end - $start" | bc)s"
TIER1_EOF

When to Use

• First pass on any recording
• Known domain analysis (trading, ML, dev)
• Quick verification of session content
• Performance-critical workflows

---

Tier 2: YAKE Unsupervised Extraction (Secondary)

Use for auto-discovery. Finds unexpected patterns without predefined keywords.

Characteristics

• Speed: 1-5s for 4MB file
• Accuracy: Medium (statistical, may include noise)
• Dependencies: uv run --with yake
• Best for: Discovering new patterns, exploratory analysis

Why YAKE

Implementation

/usr/bin/env bash << 'TIER2_EOF'
INPUT_FILE="${1:?}"

echo "=== Tier 2: YAKE Auto-Discovery ==="
start=$(date +%s.%N)

uv run --with yake python3 -c "
import yake

kw_extractor = yake.KeywordExtractor(
    lan='en',
    n=2,              # bi-grams
    dedupLim=0.9,     # deduplication threshold
    dedupFunc='seqm', # sequence matcher
    windowsSize=1,
    top=20
)

with open('$INPUT_FILE') as f:
    text = f.read()

keywords = kw_extractor.extract_keywords(text)
print('Top 20 keywords (lower score = more relevant):')
for score, keyword in keywords:
    print(f'  {score:.4f}  {keyword}')
"

end=$(date +%s.%N)
echo ""
echo "Time: $(echo "$end - $start" | bc)s"
TIER2_EOF

When to Use

• After Tier 1 when looking for unexpected patterns
• New domain exploration
• Comprehensive analysis requests
• When curated keywords miss important content

---

Tier 3: TF-IDF Topic Modeling (Optional)

Use for document comparison. Identifies distinguishing terms across segments.

Characteristics

• Speed: 5-30s for 4MB file
• Accuracy: Variable (depends on segmentation)
• Dependencies: uv run --with scikit-learn
• Best for: Comparing recording segments, finding unique terms

Implementation

/usr/bin/env bash << 'TIER3_EOF'
INPUT_FILE="${1:?}"
CHUNK_SIZE=1000  # lines per chunk

echo "=== Tier 3: TF-IDF Topic Modeling ==="

uv run --with scikit-learn python3 -c "
from sklearn.feature_extraction.text import TfidfVectorizer
import numpy as np

# Read and chunk file
with open('$INPUT_FILE') as f:
    lines = f.readlines()

chunk_size = $CHUNK_SIZE
chunks = []
for i in range(0, len(lines), chunk_size):
    chunk = ' '.join(lines[i:i+chunk_size])
    chunks.append(chunk)

print(f'Analyzing {len(chunks)} chunks of {chunk_size} lines each')

# TF-IDF vectorization
vectorizer = TfidfVectorizer(
    max_features=50,
    stop_words='english',
    ngram_range=(1, 2)
)
tfidf_matrix = vectorizer.fit_transform(chunks)
feature_names = vectorizer.get_feature_names_out()

# Top terms per chunk
print('')
for i, chunk in enumerate(chunks[:5]):  # First 5 chunks
    scores = tfidf_matrix[i].toarray().flatten()
    top_indices = scores.argsort()[-5:][::-1]
    terms = [feature_names[idx] for idx in top_indices]
    print(f'Chunk {i+1}: {terms}')
"
TIER3_EOF

When to Use

• Comparing different sessions
• Finding distinguishing characteristics
• Long recordings with distinct phases
• Research and exploratory analysis

---

Tier 4: keyBERT (Rejected)

Not recommended for terminal recordings.

Why Rejected

Alternative

Use YAKE (Tier 2) for unsupervised extraction. It provides 80% of keyBERT's value at 10% of the cost.

---

Tier Selection Guide

START
  │
  ├─> Known keywords? ─── YES ──> Tier 1 (ripgrep)
  │                                    │
  │                                    v
  │                              Found enough? ── YES ──> DONE
  │                                    │
  │                                    NO
  │                                    │
  │                                    v
  └─> Explore unknown? ─── YES ──> Tier 2 (YAKE)
                                       │
                                       v
                                 Compare segments? ── YES ──> Tier 3 (TF-IDF)
                                       │
                                       NO
                                       │
                                       v
                                     DONE

---

Performance Benchmarks

Based on 4MB converted .txt file (from 3.8GB .cast):

---

Combined Workflow

For comprehensive analysis:

/usr/bin/env bash << 'COMBINED_EOF'
INPUT_FILE="${1:?}"

echo "=== Combined Analysis ==="
echo ""

# Tier 1: Quick scan
echo "--- Tier 1: Curated Keywords ---"
for kw in sharpe backtest epoch training iteration commit; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  [[ "$COUNT" -gt 0 ]] && echo "$kw: $COUNT"
done

echo ""
echo "--- Tier 2: YAKE Discovery ---"
uv run --with yake python3 -c "
import yake
kw = yake.KeywordExtractor(lan='en', n=2, top=10)
with open('$INPUT_FILE') as f:
    for keyword, score in kw.extract_keywords(f.read()):
        print(f'{score:.4f}  {keyword}')
"

echo ""
echo "=== Analysis Complete ==="
COMBINED_EOF

Domain Keywords Reference

Curated keyword sets for semantic analysis of terminal recordings.

---

Trading/Quantitative

Keywords for trading systems, backtesting, and quantitative analysis.

Performance Metrics

Risk & Execution

Search Pattern

/usr/bin/env bash << 'TRADING_SEARCH_EOF'
KEYWORDS="sharpe sortino calmar backtest drawdown pnl cagr alpha beta roi volatility leverage slippage"
for kw in $KEYWORDS; do
  rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0"
done | paste - - | column -t
TRADING_SEARCH_EOF

---

ML/AI

Keywords for machine learning, deep learning, and AI development.

Training & Evaluation

Architecture & Optimization

Search Pattern

/usr/bin/env bash << 'ML_SEARCH_EOF'
KEYWORDS="epoch loss accuracy sota training model validation inference tensor gradient layer batch"
for kw in $KEYWORDS; do
  rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0"
done | paste - - | column -t
ML_SEARCH_EOF

---

Development

Keywords for software development workflows and practices.

Workflow

Quality

Search Pattern

/usr/bin/env bash << 'DEV_SEARCH_EOF'
KEYWORDS="iteration refactor fix test deploy build commit merge debug error lint review"
for kw in $KEYWORDS; do
  rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0"
done | paste - - | column -t
DEV_SEARCH_EOF

---

Claude Code

Keywords specific to Claude Code sessions.

Tools

Session Markers

Search Pattern

/usr/bin/env bash << 'CLAUDE_SEARCH_EOF'
# Case-sensitive for tool names
TOOLS="Skill TodoWrite Read Edit Bash Grep Write Glob"
for tool in $TOOLS; do
  COUNT=$(rg -c "$tool" "$INPUT_FILE" 2>/dev/null || echo "0")
  echo "$tool: $COUNT"
done

# Pattern matching
echo ""
echo "Patterns:"
rg -c "iteration complete" "$INPUT_FILE" 2>/dev/null || echo "0"
rg -c "AskUserQuestion" "$INPUT_FILE" 2>/dev/null || echo "0"
CLAUDE_SEARCH_EOF

---

Custom Keywords

Add project-specific keywords by extending these patterns:

/usr/bin/env bash << 'CUSTOM_SEARCH_EOF'
# Define custom keywords
CUSTOM="myproject myfunction myclass"

for kw in $CUSTOM; do
  COUNT=$(rg -c -i "$kw" "$INPUT_FILE" 2>/dev/null || echo "0")
  echo "$kw: $COUNT"
done
CUSTOM_SEARCH_EOF

---

Combining Domains

For comprehensive analysis, search multiple domains:

/usr/bin/env bash << 'COMBINED_SEARCH_EOF'
# All domains
echo "=== Trading ===" && rg -c -i "sharpe\|sortino\|backtest" "$INPUT_FILE"
echo "=== ML/AI ===" && rg -c -i "epoch\|loss\|training" "$INPUT_FILE"
echo "=== Dev ===" && rg -c -i "iteration\|commit\|deploy" "$INPUT_FILE"
echo "=== Claude ===" && rg -c "TodoWrite\|Skill\|Edit" "$INPUT_FILE"
COMBINED_SEARCH_EOF

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---