c0sogi/meeting-minutes

Escritura de Actas de Reunión en Coreano en formato HWPX

Redacta actas de reunión oficiales en coreano basándose en grabaciones de audio/video o transcripciones, y las proporciona como archivos .hwpx válidos. Si no hay transcripción, primero crea una transcripción Markdown con meetdown. El alcance actual llega hasta la generación de HWPX; no se realiza la conversión a PDF.

Entorno de ejecución

• Utiliza el sistema de archivos y permisos de ejecución de shell.
• Para ejecutar comandos y paquetes de Python se emplean uv y uvx. La herramienta de transcripción de voz meetdown==0.2.1 requiere Python 3.12 o superior.
• La transcripción de voz requiere conexión a red y credenciales de uno de los siguientes: CLOVA Speech, OpenAI o Gemini.
• Las credenciales se proporcionan mediante variables de entorno. Si se instaló como plugin de Claude Code, también se pueden ingresar en la configuración del plugin; si ambas están presentes, se prioriza la configuración del plugin.
• La redacción de HWPX utiliza una plantilla incluida y un script basado en la biblioteca estándar de Python.

Principios que deben cumplirse estrictamente

• No se debe estimar la fecha, lugar, asistentes, nombres reales de los oradores, responsables, plazos, decisiones, cifras ni nombres propios de la reunión.
• El campo Created at de meetdown indica la hora de creación de la transcripción, no la fecha de la reunión.
• Marcadores como A, B, [[SPEAKER_1]] no son nombres reales; solo se reemplazan por nombres si el usuario proporciona una asignación de oradores.
• Se deben distinguir propuestas, preocupaciones, decisiones, acciones y asuntos pendientes.
• Las ideas repetidas no se elevan automáticamente a decisiones.
• Si la opinión inicial difiere del acuerdo explícito al final de la reunión, se prioriza el acuerdo o la instrucción final.
• Las referencias a la pantalla como "aquí", "esta imagen", "este lado" no se concretan a menos que se disponga de material de referencia.
• No se exponen claves API en argumentos de comandos, registros, Markdown, JSON, HWPX ni en la respuesta final.
• Los títulos de documentos y secciones se muestran en negrita.
• Solo las frases cortas de decisiones, conclusiones y acciones importantes se resaltan con color azul #2F5597 y negrita. No se debe colorear la mayor parte del texto en azul.

Materiales incluidos

Solo se leen los materiales relevantes según el contexto.

• references/meetdown-guide.md: Se lee si no hay transcripción o si la ejecución de meetdown falla.
• references/minutes-writing.md: Se lee antes de reorganizar el contenido de la transcripción en el acta.
• references/hwpx-template.md: Se lee al escribir, reemplazar o modificar la plantilla HWPX.
• references/installation.md: Se lee para guiar sobre la ubicación de instalación o configuración del operador.
• references/evaluation.md: Se lee al diseñar pruebas de regresión tras modificar la habilidad.
• assets/minutes.schema.json: Es el estándar para la estructura de minutes.json.
• assets/example-minutes.json: Se utiliza únicamente como ejemplo de estructura de datos, no como contenido textual.
• assets/example-audit.json: Es un ejemplo del formato del libro de auditoría.
• assets/meeting-minutes-template.hwpx: Es la plantilla básica del acta de reunión.

Scripts a utilizar

Todas las rutas son relativas a la raíz de la habilidad. Si se instala como plugin, la raíz de la habilidad se encuentra en la caché fuera de la carpeta de trabajo; por lo tanto, los archivos de entrada y salida se especifican con rutas absolutas en la carpeta de trabajo del usuario y los resultados no se almacenan dentro de la carpeta de la habilidad.

• scripts/transcribe.py: Ejecuta meetdown en modo no interactivo y protege los valores secretos.
• scripts/inspect_transcript.py: Inspecciona la estructura y los elementos de riesgo de la transcripción Markdown.
• scripts/validate_minutes.py: Valida minutes.json antes de generar el HWPX.
• scripts/render_hwpx.py: Aplica el contenido estructurado a la plantilla HWPX.
• scripts/validate_hwpx.py: Inspecciona ZIP, XML, frases obligatorias, negrita y resaltado en azul.
• scripts/validate_skill.py: Verifica las reglas principales de Agent Skills.
• scripts/self_test.py: Comprueba todo el procedimiento local sin conexión a red.

Orden de trabajo

Estado de progreso:

• 1. Clasificar los archivos de entrada y los materiales de referencia.
• 2. Transcribir con meetdown si no hay transcripción.
• 3. Inspeccionar la estructura y calidad de la transcripción.
• 4. Redactar el libro de auditoría.
• 5. Redactar y validar minutes.json.
• 6. Generar el HWPX.
• 7. Validar el HWPX y corregir errores.
• 8. Informar sobre los resultados y los elementos pendientes de verificación.

1. Clasificación de materiales de entrada

Se aplica el siguiente orden de prioridad:

1. Metadatos de la reunión confirmados por el usuario, asignación de oradores, notación de términos y correcciones.
2. Materiales de referencia como órdenes del día, presentaciones, RFP, listas de asistentes, etc., utilizados en la reunión real.
3. Transcripción válida con marcas de tiempo y oradores.
4. Transcripción completa sin marcas de tiempo.
5. Sugerencias de fecha en el nombre del archivo, solo si el formato está especificado.

Procesamiento por tipo de entrada:

• Si existe una transcripción Markdown válida, se utiliza tal cual y no se vuelve a transcribir la misma grabación.
• Si solo hay audio/video, se transcribe antes de redactar el acta.
• Si se dispone tanto de la transcripción como de la grabación, se prioriza la transcripción. Solo se vuelve a transcribir si la transcripción está vacía, corrupta o corresponde a una reunión diferente.
• Las múltiples grabaciones se transcriben por separado. Solo se fusionan conservando el orden de los archivos si se confirma que son grabaciones consecutivas de la misma reunión.
• Si no hay grabación ni transcripción, se redacta un borrador solo si las notas de la reunión son suficientes. Si faltan fundamentos, no se inventa el contenido de la reunión.

2. Transcripción cuando sea necesario

Antes de transcribir, leer references/meetdown-guide.md.

Ejecución básica para reuniones en coreano con CLOVA Speech:

uv run scripts/transcribe.py "<archivo_de_grabación>" \
  -o "<transcripción.md>" \
  --provider clova \
  --language ko-KR

Si la herramienta disponible es transcribe_meeting, se invoca esta herramienta en lugar del comando anterior. Las credenciales ingresadas en la configuración del plugin solo se pasan a esta herramienta. input_path y output_path se especifican como rutas absolutas, y las siguientes opciones se pasan como parámetros equivalentes (como chunk_duration).

Solo se reintenta con las siguientes opciones si falla la carga única de un archivo largo o si las limitaciones del proveedor son claras.

--chunk-duration 10m

La compresión predeterminada es smallest. Solo se reintenta con lossless si hay evidencia de que la compresión ha degradado la calidad de la transcripción. En reuniones con varios participantes, se mantiene la separación de oradores a menos que haya una razón específica.

Después de la transcripción, se debe inspeccionar.

uv run scripts/inspect_transcript.py "<transcripción.md>" \
  -o "<transcripción.inspect.json>"

No se redacta el acta si el archivo está vacío, contiene una página de error HTML, o si no hay una transcripción completa utilizable ni segmentos con marcas de tiempo.

3. Organización de metadatos

Se registran los siguientes valores si están confirmados.

• Orden del día
• Fecha y hora
• Organización responsable
• Lugar
• Asistentes
• Temas principales
• Asignación de oradores
• Notación definitiva de nombres de personas, organizaciones, proyectos, productos y términos técnicos

No se interrumpe el trabajo aunque falten metadatos de baja importancia. Se crea un borrador, se escribe "requiere verificación" en la celda correspondiente y se registra en quality.missing_metadata. Solo se verifica información adicional que sea crítica para una versión final completa y que pueda cambiar significativamente el resultado.

4. Redacción del libro de auditoría

Antes de escribir el texto final, se crea minutes.audit.json. Para cada elemento importante se utiliza el siguiente formato.

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "Contenido corto normalizado",
  "source": "Nombre del archivo de la transcripción o material de referencia",
  "speaker": "A o nombre real confirmado",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

Criterios de clasificación:

• fact: Hecho confirmado o explicado en la reunión.
• proposal: Propuesta, idea u opción.
• concern: Objeción, riesgo o limitación.
• decision: Acuerdo, selección, confirmación, aprobación o instrucción explícita.
• action: Tarea específica acordada para realizar.
• open_question: Asunto no concluido.

Las acciones posteriores deben incluir una tarea. El responsable y el plazo solo se completan si hay evidencia.

5. Redacción de los datos del acta

Seguir references/minutes-writing.md y assets/minutes.schema.json. assets/example-minutes.json solo se utiliza como referencia de estructura, no se copia su contenido.

Estructura obligatoria del documento:

• AC T A
• Tabla de metadatos en la parte superior
• D E S A R R O L L O D E L A R E U N I Ó N
  • Resumen de la reunión
  • 2. Discusión principal
  • 2.1 y siguientes: Discusiones por tema, normalmente de 3 a 7
• R E S U L T A D O D E L A R E U N I Ó N
  • [Resumen]
  • [Acciones posteriores]
  • [Asuntos pendientes de verificación] solo si es necesario

El estilo de redacción es conciso y neutral, propio del ámbito laboral coreano. Las terminaciones básicas son -함, -하기로 함, -논의됨, -필요함, -판단됨. Se eliminan muletillas, tartamudeos, repeticiones y charlas irrelevantes, pero se conservan objeciones, limitaciones técnicas, costos y plazos que sean fundamento de las decisiones.

Las frases a resaltar en azul se colocan en el array emphasis como cadenas cortas exactamente iguales al texto del cuerpo. Los elementos importantes se marcan con important: true.

Validación:

uv run scripts/validate_minutes.py "<minutes.json>"

Se corrigen todos los errores. También se revisan las advertencias sobre metadatos faltantes, frases de énfasis que no están en el cuerpo, proporción excesiva de énfasis y párrafos demasiado largos.

6. Generación de HWPX

Si el usuario no ha proporcionado una plantilla compatible, se utiliza la plantilla predeterminada.

uv run scripts/render_hwpx.py \
  --template assets/meeting-minutes-template.hwpx \
  --data "<minutes.json>" \
  --output "<acta_final.hwpx>"

El renderizador mantiene la estructura de la tabla y los estilos de párrafo existentes, pone en negrita los títulos y subtítulos, y muestra las frases clave especificadas en #2F5597 con negrita. Si el contenido es extenso, no se reduce excesivamente el tamaño de la fuente, sino que se permite que fluya naturalmente a la página siguiente.

Si el usuario proporciona una plantilla HWPX significativamente diferente, no se ejecuta sin más. Primero se verifican las direcciones de las celdas de la tabla y la estructura de los párrafos del cuerpo según references/hwpx-template.md, y luego se ajusta el renderizador.

7. Validación del HWPX

uv run scripts/validate_hwpx.py "<acta_final.hwpx>" \
  --expect-data "<minutes.json>"

Si la validación falla, se modifica el JSON o la plantilla y se regenera. No se entregan archivos en los siguientes estados:

• mimetype no es el primer elemento del ZIP o está comprimido.
• Falta un XML obligatorio o no se puede analizar.
• Falta una frase esperada.
• El título del documento o los títulos de sección no están en negrita.
• Se solicitó énfasis pero no hay estilo de negrita azul.
• Quedan marcadores de posición incompletos.

La validación se completa con la inspección del ZIP, XML, contenido y configuración de formato del archivo. No se realiza ejecución de Hancom Office, Computer Use ni revisión visual mediante capturas de pantalla.

8. Resultados e informe

Según el contexto, se crean los siguientes archivos:

• transcript.md si fue necesaria la transcripción.
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• minutes.review.md si hay elementos no confirmados.
• .hwpx final

Formato del informe final:

Completado
- HWPX: <ruta>
- Transcripción: <ruta o transcripción existente utilizada>
- Validación: Aprobada | Con advertencias
- Pendiente de verificación: Ninguno | Resumen de elementos clave

Gestión de errores

• Si faltan credenciales, se indican los nombres de las variables de entorno necesarias y, en Claude Code, se informa que se pueden ingresar en la configuración del plugin hwpx mediante /plugin. No se solicita al usuario que ingrese valores secretos en el chat.
• Si hay limitaciones de tamaño o tiempo, se reintenta con --chunk-duration 10m.
• Si la confianza en la transcripción es baja, no se corrigen arbitrariamente nombres propios y números, sino que se dejan como elementos de revisión.
• Si el renderizado HWPX falla, se informa la causa y no se proporciona un archivo dañado como resultado.
• Si se solicita PDF, se indica que está fuera del alcance actual de la habilidad y que se necesita un entorno de conversión separado.

Autoverificación

Ejecutar después de instalar la habilidad o de modificar scripts/plantillas.

uv run scripts/self_test.py

Esta prueba no llama a APIs de reconocimiento de voz; realiza análisis de transcripciones, validación JSON, generación HWPX y validación estructural.