Análisis de Transcripciones (Jamie-BitFlight/transcript-analysi…

Análisis de Transcripciones

Analiza transcripciones de sesiones de Claude Code en formato JSONL para detectar antipatrones, ineficiencias y oportunidades de mejora en el flujo de trabajo.

Ubicación de los Datos

Encuentra las transcripciones en ~/.claude/projects/ dentro de directorios específicos del proyecto nombrados según la ruta del proyecto (con guiones reemplazando las barras).

Rol de DuckDB: Carga la referencia completa de campos/rutas desde kaizen-analysis mediante get_transcript_jsonl_schema o MCP resources/read kaizen://session-log/schema, luego usa kaizen-duckdb execute_query para ejecutar cualquier consulta SQL de DuckDB sobre esos archivos (consulta Patrones de Consulta DuckDB para ejemplos y el flujo de trabajo de consultas arbitrarias). El historial de sesiones permanece en JSONL en disco. Reglas de rutas para el MCP DuckDB (rutas absolutas, sin ~ en SQL).

~/.claude/projects/{project-key}/
├── {uuid}.jsonl              # Transcripciones principales de la sesión
├── agent-{id}.jsonl          # Transcripciones de agentes huérfanos
└── {uuid}/
    ├── subagents/
    │   └── agent-{id}.jsonl  # Transcripciones de subagentes
    └── tool-results/
        └── {tool-use-id}.txt # Salidas de tareas asíncronas

Tipos de Registros JSONL

Cada línea JSONL es un objeto JSON discriminado por el campo type.

Tipos de registro principales para el análisis:

• assistant — Turnos de respuesta del LLM que contienen llamadas a herramientas y texto
• user — Entrada humana y resultados de herramientas
• system — Eventos de metadatos (stop_hook_summary, turn_duration, compact_boundary, api_error, local_command)
• progress — Ejecución de hooks y transmisión de subagentes
• file-history-snapshot — Seguimiento de ediciones de archivos
• summary — Título/resumen de la sesión

Para detalles completos del esquema, incluyendo estructuras JSON para cada tipo de registro, consulta Referencia del Esquema JSONL.

Catálogo de Señales

Cada dimensión de análisis a continuación tiene su propia metodología de extracción.

1. Detección de Mal Uso de Herramientas

Extrae de assistant.message.content[] donde name == "Bash". Analiza input.command en busca de patrones de operaciones con archivos que deberían usar herramientas integradas. Para consultas de extracción SQL, consulta Patrones de Consulta DuckDB.

Analiza bloques tool_use en busca de comandos Bash que coincidan con:

• grep → debería usar la herramienta Grep
• find -name → debería usar la herramienta Glob
• cat, head, tail → debería usar la herramienta Read
• ls → debería usar Glob o Bash(ls) con descripción
• sed, awk → debería usar la herramienta Edit

Excluye usos legítimos en pipelines (git ... | grep, uv run ... | head).

2. Errores Repetidos

Extrae de los resultados de herramientas donde is_error: true. Clasifica los tipos de error:

• "El archivo aún no se ha leído" — Antipatrón de Editar-antes-de-Leer
• "La cadena a reemplazar no se encontró" — Objetivo de edición obsoleto
• "El usuario denegó el uso de la herramienta" — Problema de permiso/confianza
• Fallos del hook pre-commit (código de salida 1)
• Binario faltante / comando no encontrado

3. Oportunidades de Herramientas Faltantes

Identifica flujos de trabajo manuales repetitivos de varios pasos en todas las sesiones mediante análisis de trigramas de secuencias de herramientas. Trigramas de alta frecuencia como Bash → Bash → Bash o Read → Read → Read sugieren que faltan scripts o habilidades.

4. Patrones de Delegación a Subagentes

Extrae de los bloques tool_use de Task. Rastrea subagent_type, description, model. Señala cuando se usa general-purpose donde existe un agente especializado.

5. Análisis del Camino Más Corto

Compara intentos exitosos vs fallidos para el mismo objetivo. Mide el recuento de llamadas a herramientas entre la declaración del objetivo (turno del usuario) y el resultado exitoso (turno final del asistente). La alta variación entre sesiones para objetivos similares indica pasos desperdiciados.

6. Detección de Pistas Falsas

Rastrea ramas de investigación que se abandonan. Señal: una secuencia de llamadas Read/Grep/Bash sobre un tema seguida de compact_boundary o un cambio de dirección sin resolución. La frecuencia entre sesiones de las mismas rutas abandonadas revela pistas falsas sistemáticas.

7. Interrupciones del Proceso del Sistema

Extrae eventos system.compact_boundary, system.api_error y eventos progress relacionados con hooks. Mapea su posición en relación con el trabajo activo para identificar cuándo los procesos del sistema descarrilaron las rutas de ejecución correctas.

8. Hooks Faltantes

Identifica correcciones manuales que se repiten en todas las sesiones. Cuando la misma corrección aparece 3+ veces, es candidata para una prevención automatizada mediante un hook PreToolUse (denegar + redirigir) o un hook SubagentStart (inyectar contexto).

9. Consultas SQL con DuckDB

Usa kaizen-analysis get_transcript_jsonl_schema o el recurso kaizen://session-log/schema para la referencia completa de rutas, luego kaizen-duckdb execute_query para cualquier SQL sobre JSONL (read_ndjson_auto con rutas absolutas). No estás limitado a las consultas del recetario.

Para el flujo de trabajo de consultas arbitrarias y ejemplos, consulta Patrones de Consulta DuckDB.

Metodología de Minería de Procesos

Usa las herramientas del servidor MCP kaizen-analysis para análisis que SQL no puede expresar:

• extract_tool_sequences — Convierte JSONL → matrices ordenadas de llamadas a herramientas por sesión
• discover_process_model — Modelo de transición ligero sobre secuencias de llamadas a herramientas
• check_conformance — Compara sesiones contra un modelo de proceso de referencia
• find_frequent_patterns — Minería de patrones secuenciales PrefixSpan
• cluster_sessions — Agrupamiento de trazas por similitud de comportamiento

Flujo de Trabajo de Análisis

flowchart TD
    Start([Recibir tarea de análisis]) --> Scope{¿Ámbito definido?}
    Scope -->|--project flag| Project[Filtrar a transcripciones del proyecto]
    Scope -->|Sin flag| Default[Usar proyecto actual]
    Project --> Discover[SQL — contar sesiones, rango de fechas, tipos de registro]
    Default --> Discover
    Discover --> Dimensions{¿Qué dimensiones?}
    Dimensions -->|Todas| RunAll[Ejecutar todas las dimensiones]
    Dimensions -->|Especificadas| RunSelected[Ejecutar dimensiones seleccionadas]
    RunAll --> Aggregate[Aggregate hallazgos]
    RunSelected --> Aggregate
    Aggregate --> Write[Escribir en .planning/kaizen/analysis-FECHA.md]

Formato de Salida

Escribe los hallazgos del análisis en .planning/kaizen/ como markdown estructurado con:

• ID de sesión y fecha para cada hallazgo
• Severidad (crítico / advertencia / informativo)
• Evidencia — rutas de campo JSON exactas y valores
• Frecuencia — cuántas sesiones exhiben el patrón
• Tipo de recomendación — hook, parche de habilidad, corrección de prompt del agente, actualización de CLAUDE.md