Summarize

/asciinema-tools:summarize

AI-powered iterative deep-dive analysis for large .txt recordings. Uses guided sampling and AskUserQuestion to progressively explore the content.

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.

Philosophy

Large recordings (1GB+) cannot be read entirely. This command uses:

1. Initial guidance - What are you looking for? 2. Strategic sampling - Head, middle, tail + keyword-targeted sections 3. Iterative refinement - AskUserQuestion to drill deeper into findings 4. Progressive synthesis - Build understanding through multiple passes

Arguments

Workflow

Phase 1: Initial Guidance

AskUserQuestion:
  question: "What are you trying to understand from this recording?"
  header: "Focus"
  options:
    - label: "General overview"
      description: "What happened in this session? Key activities and outcomes"
    - label: "Key findings/decisions"
      description: "Important discoveries, conclusions, or decisions made"
    - label: "Errors and debugging"
      description: "What went wrong? How was it resolved?"
    - label: "Specific topic"
      description: "I'll specify what I'm looking for"

Phase 2: File Statistics

/usr/bin/env bash << 'STATS_EOF'
FILE="$1"

echo "=== File Statistics ==="
SIZE=$(ls -lh "$FILE" | awk '{print $5}')
LINES=$(wc -l < "$FILE")
echo "Size: $SIZE"
echo "Lines: $LINES"

echo ""
echo "=== Content Sampling ==="
echo "First 20 lines:"
head -20 "$FILE"

echo ""
echo "Last 20 lines:"
tail -20 "$FILE"

echo ""
echo "=== Keyword Density ==="
echo "Errors/failures:"
grep -c -i "error\|fail\|exception" "$FILE" || echo "0"
echo "Success indicators:"
grep -c -i "success\|complete\|done\|pass" "$FILE" || echo "0"
echo "Key decisions:"
grep -c -i "decision\|chose\|selected\|using" "$FILE" || echo "0"
STATS_EOF

Phase 3: Strategic Sampling

Based on file size, sample strategically:

For files < 100MB:

# Sample head, middle, tail (1000 lines each)
head -1000 "$FILE" > /tmp/sample_head.txt
tail -1000 "$FILE" > /tmp/sample_tail.txt
TOTAL=$(wc -l < "$FILE")
MIDDLE=$((TOTAL / 2))
sed -n "${MIDDLE},$((MIDDLE + 1000))p" "$FILE" > /tmp/sample_middle.txt

For files > 100MB:

# Keyword-targeted sampling
grep -B5 -A20 -i "$TOPIC_KEYWORDS" "$FILE" | head -5000 > /tmp/sample_targeted.txt

Phase 4: Initial Analysis

Read the samples and provide initial findings. Then ask:

AskUserQuestion:
  question: "Based on initial analysis, what would you like to explore deeper?"
  header: "Drill down"
  multiSelect: true
  options:
    - label: "Specific timeframe"
      description: "Jump to a particular section (e.g., 'around line 50000')"
    - label: "Follow keyword trail"
      description: "Search for specific patterns and expand context"
    - label: "Error investigation"
      description: "Deep dive into errors and their resolution"
    - label: "Success moments"
      description: "What worked? What were the wins?"
    - label: "Generate summary"
      description: "Synthesize findings into a report"

Phase 5: Iterative Deep-Dive

For each selected focus area:

1. Extract relevant sections using grep with context 2. Read and analyze the extracted content 3. Report findings to user 4. Ask for next action via AskUserQuestion

AskUserQuestion:
  question: "Found {N} relevant sections. What next?"
  header: "Continue"
  options:
    - label: "Show me the most significant"
      description: "Display top 3 most relevant excerpts"
    - label: "Search for related patterns"
      description: "Expand search to related keywords"
    - label: "Move on"
      description: "I have enough on this topic"

Phase 6: Synthesis

AskUserQuestion:
  question: "Ready to generate summary. What format?"
  header: "Output"
  options:
    - label: "Concise bullet points"
      description: "Key findings in 10-15 bullets"
    - label: "Detailed markdown report"
      description: "Full report with sections and evidence"
    - label: "Executive summary"
      description: "1-paragraph high-level summary"
    - label: "Save to file"
      description: "Write findings to markdown file"

Keyword Libraries

Trading/ML Domain

sharpe|drawdown|backtest|overfitting|regime|validation
model|training|loss|epoch|gradient|convergence
feature|indicator|signal|position|portfolio

Development Domain

error|exception|fail|bug|fix|debug
commit|push|merge|branch|deploy
test|assert|verify|validate|check

Claude Code Domain

tool|bash|read|write|edit|grep
task|agent|subagent|spawn
permission|approve|reject|block

Example Usage

# Interactive exploration
/asciinema-tools:summarize session.txt

# Focused on ML findings
/asciinema-tools:summarize session.txt --topic "ML training results"

# Quick overview
/asciinema-tools:summarize session.txt --depth quick

# Full analysis with report
/asciinema-tools:summarize session.txt --depth deep --output findings.md

Example Output

# Session Summary: alpha-forge-research_20251226

## Overview

- **Duration**: 4 days (Dec 26-30, 2025)
- **Size**: 12GB recording → 3.2GB text
- **Primary Focus**: ML robustness research

## Key Findings

### 1. Training-Evaluation Mismatch (CRITICAL)

- MSE loss optimizes magnitude, but Sharpe evaluates direction
- Result: 80% Sharpe collapse from 2024 to 2025

### 2. Fishr λ=0.1 Solution (BREAKTHROUGH)

- Gradient variance penalty solves V-REx binary threshold
- Feb'24 Sharpe: -6.14 → +6.14

### 3. Model Rankings

| Model  | Window | Sharpe |
| ------ | ------ | ------ |
| TFT    | 15mo   | 1.02   |
| BiLSTM | 12mo   | 0.50   |

## Evidence Locations

- Line 15234: "Fishr λ=0.1 SOLVES the V-REx binary threshold problem"
- Line 48102: Phase 4 results summary table

## Next Steps Identified

1. TFT 15mo + Fishr training
2. DSR/PBO statistical validation
3. Agent research synthesis

Troubleshooting

Related Commands

• /asciinema-tools:convert - Convert .cast to .txt first
• /asciinema-tools:analyze - Keyword-based analysis (faster, less deep)
• /asciinema-tools:finalize - Process orphaned recordings

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.

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

---