px-summarize-transcript

¿Qué hace px-summarize-transcript?

Convierte una transcripción de reunión en un registro con respaldo probatorio de lo que se decidió, qué hechos importantes se declararon y quién es responsable de cada tarea. Cada elemento cita al hablante, la marca de tiempo (cuando la transcripción la tiene) y una cita textual. Los scripts de Python hacen el trabajo mecánico: analizar, nombrar archivos, metadatos y verificación de citas. Tú realizas el razonamiento.

Cuándo usarlo

• Un .vtt, una transcripción de Teams copiada a .txt o .md, una transcripción en Markdown con formato [Speaker] AAAA-MM-DD HH:MM:SS, o líneas con Nombre: texto necesitan que se extraigan decisiones y elementos de acción.
• Alguien pregunta quién dijo algo, qué se acordó o quién se encarga de un seguimiento.
• Alguien pregunta qué quedó pendiente de la reunión anterior en una serie recurrente.
• Los resultados de la reunión deben conciliarse con documentos del proyecto.

Disposición del paquete (fija)

Todos los archivos residen en la propia carpeta de la transcripción y comparten su nombre. Solo cambia el sufijo. No se pueden escribir en otro lugar. Si el usuario pide otra carpeta, explícale que el paquete permanece con su transcripción. file_transcript.py puede mover un paquete entero a una carpeta de serie, y sus miembros siempre se mueven juntos.

Archivo	Rol
<stem>.vtt / .txt / .md	Transcripción fuente. .md y .txt reciben metadatos fusionados; las claves existentes nunca se modifican.
<stem>.source.md	Solo para .vtt: un pequeño archivo Markdown "sidecar" que contiene los metadatos del .vtt, porque un archivo .vtt debe comenzar con WEBVTT y no puede contener metadatos.
<stem>.turns.md	Índice de turnos. Se crea una vez; nunca se reescribe a menos que pases --rebuild.
<stem>.summary.md	Informe. Las re-ejecuciones escriben <stem>.summary.v2.md, .v3, etc.

Formatos y claves: formatos de entrada, especificación de metadatos.

Procedimiento

Los scripts se encuentran en ./scripts/ junto a este SKILL.md. La terminal se inicia en el espacio de trabajo del usuario, así que primero resuelve la ruta absoluta de la carpeta de la habilidad (las instalaciones personales suelen ser ~/.claude/skills/px-summarize-transcript o ~/.agents/skills/px-summarize-transcript) y establécela una vez por terminal:

$S = "<ruta absoluta de esta habilidad>\scripts"      # PowerShell

S="<ruta absoluta de esta habilidad>/scripts"          # bash / zsh

Los comandos siguientes usan PowerShell ("$S\build_turns.py"). En bash, escribe "$S/build_turns.py". Los scripts usan solo la biblioteca estándar (Python 3.10+). Pon las rutas entre comillas, porque los nombres de archivo suelen contener espacios.

Trabaja con una transcripción a la vez. Para una carpeta o "todo lo pendiente", consulta Varias transcripciones.

1. Archivar la transcripción (opcional). Hazlo cuando el usuario lo pida, o cuando el espacio de trabajo mantenga las transcripciones en carpetas de serie (por ejemplo transcripts/<serie>/) y esta aún no esté en una. --root por defecto es ./transcripts.

   python "$S\file_transcript.py" --list --root "<raíz>"
   python "$S\file_transcript.py" "<transcripción>" --series "<serie>" --root "<raíz>"
   

   Reutiliza una serie existente que se ajuste a la reunión. Si ninguna encaja, propón un nombre corto en kebab-case y confírmalo con el usuario antes de crearla. Luego actúa según status:

   • moved: continúa con la nueva ruta source.
   • already-filed: la transcripción ya está dentro de una carpeta bajo la raíz, o en una carpeta con el nombre de la serie. No se movió nada, así que continúa.
   • duplicate: la misma transcripción ya existe en duplicate_of. Detente y pregunta al usuario qué copia procesar. No elimines ninguno de los archivos.
   • conflict (código de salida 2): un archivo diferente con el mismo nombre ya está en la carpeta de la serie. Detente y pregunta.

2. Construir el índice de turnos.

   python "$S\build_turns.py" "<transcripción>"
   

   Detecta el formato, escribe <stem>.turns.md si aún no existe, sella la fuente (o sidecar), e imprime JSON. Conserva turns_path, turns_status, summary_path, has_timestamps, speakers, meeting_date, meeting_date_source, gaps, previous_meeting_summary y transcription.

   • turns_status: created o kept: continúa. kept significa que el índice de turnos existente ya coincide con la transcripción, por lo que no se reescribió nada.
   • turns_status: source-changed (código de salida 3): la transcripción se editó después de construir el índice de turnos, y los informes existentes citan los IDs de turno antiguos. Detente y pregunta al usuario antes de volver a ejecutar con --rebuild.
   • Error de formato no soportado (código de salida 2): informa al usuario qué formatos están soportados y detente.
   • meeting_date es null: escribe "No indicada" a menos que el usuario te dé la fecha.

3. Leer el índice de turnos completo en fragmentos grandes hasta el final. Nunca extraigas de una lectura parcial.

4. Mapear los hablantes. Haz una fila por cada etiqueta de hablante para la tabla de Hablantes del informe: la etiqueta, el nombre a mostrar y cómo lo identificaste.

   • Muestra un nombre diferente solo con evidencia: la persona es llamada por su nombre, se presenta, o la etiqueta es un error ortográfico evidente. Registra la evidencia.
   • Una etiqueta de dispositivo de sala de conferencias se mantiene como la sala. Enumera quién fue escuchado o nombrado allí, y no atribuyas sus líneas a una sola persona a menos que la transcripción lo haga inequívoco.
   • Las personas mencionadas solo en la línea de encabezado Transcription: asistieron pero no necesariamente hablaron.
   • Enumera a las personas que son mencionadas pero no hablan, indicando dónde se mencionaron.
   • Resuelve nombres de pila a nombres completos solo cuando sea inequívoco.

5. Extraer elementos usando estas pruebas:

   • Decisión: se tomó o aceptó una elección entre opciones ("vamos con", "acordado", "haremos", o una propuesta sin objeción). Estado: Acordada, Tentativa o Propuesta.
   • Declaración material: algo que cambiaría el alcance, diseño, cronograma, costo o riesgo si fuera incorrecto: hechos sobre sistemas, restricciones, dependencias, números, fechas, compromisos, riesgos declarados. No charla trivial o reformulaciones. Apunta a 12 o menos fusionando declaraciones relacionadas.
   • Elemento de acción: una tarea futura con un verbo, solicitada u ofrecida ("yo haré", "puedes", "necesitamos").
   • Pregunta abierta: planteada y no resuelta antes de que la reunión avanzara.

6. Asignar responsables a cada elemento de acción. Los responsables pueden ser cualquier persona nombrada, incluidos los ausentes.

   • Explícito: nombrado y se le pidió, no declinó.
   • Ofrecido: el hablante dijo "Yo haré...".
   • Delegado: asignado a alguien ausente o en silencio. Marca (no presente) y anota quién lo asignó.
   • Inferido: se desprende del rol o la propiedad declarada. Escribe el razonamiento.
   • Sin asignar: ninguno de los anteriores. Nunca inventes un responsable.

   Registra las fechas de vencimiento solo si se dijeron.

7. Adjuntar evidencia a cada elemento:

   • Con marcas de tiempo: [T042 00:12:31 Speaker] "cita textual".
   • Sin marcas de tiempo (has_timestamps: false): [T042 Speaker] "cita textual".
   • Speaker es la etiqueta exacta como aparece en el índice de turnos, incluso si la tabla de Hablantes muestra un nombre diferente. Usa los nombres a mostrar en cualquier otro lugar.
   • Las citas tienen 25 palabras o menos, copiadas exactamente incluyendo errores de ASR. Usa ... para omisiones. Cita varios turnos cuando una decisión se forma a lo largo de varios turnos.

8. Verificar lo que se trasladó (solo cuando previous_meeting_summary está definido). Lee solo las tablas de Elementos de acción y Preguntas abiertas de ese informe. Para cada elemento, decide a partir de esta transcripción si está Hecho, En progreso, Aún abierto, Abandonado o No mencionado, y cita el turno que lo muestra. Nunca marques un elemento como Hecho sin que alguien lo diga.

9. Escribir el informe en summary_path usando la plantilla. Escribe solo el cuerpo; no añadas metadatos. Siempre completa "De un vistazo". Añade "Para " solo cuando el usuario nombre al lector, por ejemplo "para mí, soy Dana Ruiz". Nunca asumas quién es el lector.

10. Señalar advertencias de transcripción: probables errores de ASR, nombres de hablantes que mapeaste por inferencia y cada entrada en gaps (el contenido puede faltar). Nunca corrijas citas en silencio.

11. Verificar citas y corregir o eliminar cada fila que falle hasta que pase:

    python "$S\verify_quotes.py" "<ruta_del_informe>"
    

12. Finalizar el paquete. Deriva un título corto del contenido de la reunión y de 3 a 6 etiquetas de tema (minúsculas, kebab-case). transcript y meeting-notes se añaden automáticamente.

    python "$S\finalize_bundle.py" "<transcripción>" --summary "<ruta_del_informe>" --title "<título>" --tags "etiqueta-uno,etiqueta-dos" --alias "Etiqueta en transcripción=Nombre a mostrar" --mentioned "Nombre (contexto)" --meeting-date AAAA-MM-DD
    

    • --alias se repite una vez por cada etiqueta de hablante que mapeaste en el paso 4. Los asistentes entonces usan por defecto los nombres a mostrar.
    • --mentioned se repite una vez por persona.
    • --attendee "Nombre" se repite una vez por persona cuando necesitas sobrescribir la lista de asistentes. --attendees "A, B (sala: C, D)" también funciona, porque las comas dentro de () o [] no dividen.
    • Pasa --meeting-date solo cuando meeting_date era null y el usuario te dio la fecha.

13. Informar de vuelta en el chat brevemente. No pegues las tablas.

    • Conteos: decisiones, declaraciones, elementos de acción, preguntas abiertas y elementos trasladados.
    • Los puntos de "De un vistazo".
    • Cualquier cosa que necesite verificación humana: nombres de hablante inferidos, responsables inferidos o sin asignar, lagunas y advertencias de ASR.
    • Enlaces al informe y al índice de turnos.

Varias transcripciones

python "$S\scan.py" "<carpeta>" --recursive

Enumera cada transcripción como new, turns-only, summarized o not-a-transcript. Muestra al usuario las pendientes (new y turns-only) y confirma antes de comenzar. Procesa una a la vez, la reunión más antigua primero, para que cada una pueda encontrar la reunión anterior en su serie. Ejecuta el procedimiento completo e informa de vuelta por cada una antes de comenzar la siguiente.

Documentos relacionados del proyecto

Si el espacio de trabajo tiene documentos relacionados de arquitectura o planificación (incluyendo los archivos de resumen de otros paquetes), completa la tabla opcional "Documentos relacionados del proyecto". Anota si cada elemento confirma, contradice o amplía lo que esos documentos registran.

Controles de calidad

• verify_quotes.py pasa con 0 fallos.
• La tabla de Hablantes tiene una fila para cada etiqueta en el índice de turnos, y cada mapeo de nombre indica su evidencia.
• Ningún responsable se nombra sin evidencia explícita, ofrecida, delegada o inferida explicada.
• Las decisiones marcadas como Acordadas muestran una señal de aceptación, no solo una sugerencia.
• Las opiniones y especulaciones se etiquetan como tales.
• Los responsables que no estaban en la reunión se marcan (no presente).
• Cada entrada en gaps aparece bajo Advertencias de transcripción.
• Cuando hay una reunión anterior, cada uno de sus elementos de acción y preguntas abiertas tiene una fila de Trasladado.

Paquetes heredados

Para alinear paquetes más antiguos (por ejemplo input.txt junto a <carpeta>.turns.md), ejecuta python "$S\backfill.py" "<raíz>" para una simulación, luego --apply. Luego ejecuta finalize_bundle.py por paquete con un título y etiquetas. Backfill nunca regenera un índice de turnos existente, por lo que las citas existentes siguen siendo válidas.