c0sogi/write-korean-meeting-minutes-hwpx

Redacción de actas de reunión en coreano HWPX

Redacta actas de reunión formales en coreano basadas en evidencia de audio, video o transcripciones, y las proporciona como un archivo .hwpx válido. Si no hay transcripción, primero se crea una transcripción en Markdown con meetdown. El alcance actual llega hasta la generación de HWPX; no se realiza conversión a PDF.

Entorno de ejecución

• Se utilizan permisos de sistema de archivos y ejecución de shell.
• Los comandos y paquetes de Python se ejecutan con 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 de red y credenciales de uno de los siguientes: CLOVA Speech, OpenAI o Gemini.
• La creación de HWPX utiliza una plantilla incluida y un script basado en la biblioteca estándar de Python.

Principios que deben seguirse estrictamente

• No inferir la fecha, hora, lugar, asistentes, nombres reales de los hablantes, responsables, plazos, decisiones, cifras o nombres propios de la reunión.
• El Created at de meetdown es la hora de generación de la transcripción, no la hora de la reunión.
• Indicaciones como A, B, [[SPEAKER_1]] no son nombres reales; solo se reemplazan con nombres cuando el usuario proporciona una asignación de hablantes.
• Distinguir entre propuestas, preocupaciones, decisiones, acciones de seguimiento y asuntos pendientes.
• No elevar automáticamente ideas repetidas a decisiones.
• Si las opiniones iniciales difieren del acuerdo explícito al final de la reunión, se prioriza el último acuerdo o instrucción.
• Las referencias a la pantalla como "aquí", "esta imagen", "este lado" no se concretan sin material de referencia.
• No exponer claves API en argumentos de comandos, registros, Markdown, JSON, HWPX o en la respuesta final.
• Los títulos de documentos y de secciones/subsecciones se muestran en negrita.
• Solo se resaltan en azul #2F5597 y negrita las frases cortas de decisiones, conclusiones o acciones de seguimiento importantes. No se debe poner la mayor parte del texto en azul.

Materiales incluidos

Solo se leen los materiales relevantes según la situación.

• references/meetdown-guide.md: Se lee cuando no hay transcripción o falla la ejecución de meetdown.
• references/minutes-writing.md: Se lee antes de reorganizar la transcripción en acta.
• references/hwpx-template.md: Se lee al crear, reemplazar o modificar la plantilla HWPX.
• references/installation.md: Se lee para guiar la ubicación de instalación o la configuración del operador.
• references/evaluation.md: Se lee al diseñar pruebas de regresión después de modificar la habilidad.
• assets/minutes.schema.json: Es la referencia para la estructura de minutes.json.
• assets/example-minutes.json: Se utiliza solo como ejemplo de estructura de datos, no de contenido.
• assets/example-audit.json: Es un ejemplo del formato del libro de evidencia.
• assets/meeting-minutes-template.hwpx: Es la plantilla básica de actas de reunión.

Scripts a utilizar

Todas las rutas son relativas a la raíz de la habilidad.

• scripts/transcribe.py: Ejecuta meetdown de forma no interactiva y protege los valores secretos.
• scripts/inspect_transcript.py: Inspecciona la estructura y los factores de riesgo del Markdown de meetdown.
• scripts/validate_minutes.py: Valida minutes.json antes de crear el HWPX.
• scripts/render_hwpx.py: Aplica el contenido estructurado a la plantilla HWPX.
• scripts/validate_hwpx.py: Verifica ZIP, XML, frases obligatorias, negritas y resaltado en azul.
• scripts/validate_skill.py: Verifica las reglas principales de Agent Skills.
• scripts/self_test.py: Verifica todo el procedimiento local sin red.

Orden de trabajo

Estado de progreso:

• 1. Clasificar los archivos de entrada y los materiales de referencia.
• 2. Si no hay transcripción, transcribir con meetdown.
• 3. Inspeccionar la estructura y calidad de la transcripción.
• 4. Crear el libro de evidencia.
• 5. Crear y validar minutes.json.
• 6. Generar el HWPX.
• 7. Validar el HWPX y corregir errores.
• 8. Informar los resultados y los puntos 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 hablantes, 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 marca de tiempo y hablante.
4. Transcripción completa sin marca de tiempo.
5. Solo si se especifica el formato, se utiliza la pista de fecha del nombre del archivo.

Procesamiento por tipo de entrada:

• Si hay 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 hay transcripción y grabación, se prioriza la transcripción. Solo se vuelve a transcribir si la transcripción está vacía, dañada o contiene contenido de otra reunión.
• Las grabaciones múltiples se transcriben por separado. Solo cuando se confirma que son grabaciones consecutivas de la misma reunión, se combinan preservando el orden de los archivos.
• Si no hay grabación ni transcripción, solo se redacta un borrador de revisión si las notas de la reunión son suficientes. Si falta evidencia, no se inventa el contenido de la reunión.

2. Transcripción cuando sea necesario

Leer references/meetdown-guide.md antes de transcribir.

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

uv run scripts/transcribe.py "<archivo_de_audio>" \
  -o "<transcripcion.md>" \
  --provider clova \
  --language ko-KR

Reintentar con las siguientes opciones solo cuando falle la carga única de un archivo largo o cuando estén claras las limitaciones del proveedor:

--chunk-duration 10m

La compresión predeterminada es smallest. Reintentar con lossless solo cuando haya evidencia de que la compresión degrada la calidad de la transcripción. En reuniones con múltiples participantes, mantener la separación de hablantes a menos que haya una razón específica.

Después de la transcripción, inspeccionar obligatoriamente:

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

No redactar actas con archivos vacíos, páginas de error HTML, o archivos sin una transcripción completa utilizable y sin segmentos de marca de tiempo.

3. Organización de metadatos

Registrar los siguientes valores cuando estén confirmados:

• Asunto
• Fecha y hora
• Organización responsable
• Lugar
• Asistentes
• Temas principales
• Asignación de hablantes
• Notación confirmada de nombres de personas, organizaciones, proyectos, productos y términos técnicos

No interrumpir el trabajo aunque falten metadatos de baja importancia. Crear un borrador de revisión, escribir "requiere verificación" en la celda correspondiente y registrarlo en quality.missing_metadata. Solo verificar información adicional cuando sea estrictamente necesario para un documento final completo y cuando los resultados varíen significativamente.

4. Creación del libro de evidencia

Antes de redactar el texto final, crear minutes.audit.json. Para cada contenido importante, utilizar el siguiente formato:

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "Contenido breve normalizado",
  "source": "Nombre del archivo de 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, elección, confirmación, aprobación o instrucción explícita.
• action: Tarea específica acordada para realizar.
• open_question: Asunto sin concluir.

Las acciones de seguimiento deben incluir obligatoriamente la tarea. Solo se completa el responsable y el plazo cuando haya evidencia.

5. Creación de datos del acta

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

Estructura del documento obligatoria:

• ACTA DE REUNIÓN
• Tabla de metadatos en la parte superior
• CONTENIDO DE LA REUNIÓN
  • Resumen de la reunión
  • 2. Discusiones principales
  • 2.1 y siguientes, discusiones por tema, generalmente de 3 a 7
• RESULTADOS DE LA REUNIÓN
  • [Resumen]
  • [Acciones de seguimiento]
  • [Asuntos pendientes de verificación] solo cuando sea necesario

Redactar en un estilo de negocio coreano conciso y neutral. Las terminaciones básicas son -함, -하기로 함, -논의됨, -필요함, -판단됨. Eliminar muletillas, tartamudeos, repeticiones y charlas irrelevantes, pero conservar objeciones, limitaciones técnicas, costos y plazos que fundamenten las decisiones.

Las frases a resaltar en azul se incluyen en el array emphasis como cadenas cortas idénticas al texto del documento. Los elementos importantes se marcan con important: true.

Validación:

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

Corregir todos los errores. Revisar también las advertencias de metadatos faltantes, frases de énfasis que no aparecen en el texto, proporción excesiva de énfasis y párrafos demasiado largos.

6. Generación de HWPX

Si el usuario no proporciona una plantilla compatible, utilizar la plantilla predeterminada.

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

El renderizador conserva la estructura de las tablas y los estilos de párrafo existentes, pone en negrita los títulos y subtítulos, y marca las frases clave designadas con #2F5597 y negrita. Si el contenido es extenso, no reducir excesivamente el tamaño de la fuente; permitir que fluya naturalmente a la página siguiente.

Si el usuario proporciona una plantilla HWPX significativamente diferente, no ejecutarla sin más. Seguir references/hwpx-template.md para verificar primero las direcciones de las celdas de la tabla y la estructura de los párrafos del cuerpo, y luego ajustar el renderizador.

7. Validación de HWPX

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

Si falla la validación, corregir el JSON o la plantilla y regenerar. No entregar archivos en los siguientes estados:

• mimetype no es el primer elemento ZIP o está comprimido
• Falta XML obligatorio o no se puede analizar
• Faltan frases esperadas
• El título del documento o los títulos de las secciones no están en negrita
• Se solicitó resaltado pero no hay estilo azul en negrita
• Quedan marcadores de posición sin completar

Si se dispone de Hancom Office, abrir el archivo directamente para verificar los bordes de las tablas, la sustitución de fuentes, el flujo de páginas, las oraciones cortadas y el último párrafo. Si no se ha abierto realmente, no afirmar que se ha completado la inspección visual.

8. Resultados e informe

Según la situación, crear 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
• Archivo .hwpx final

Formato del informe final:

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

Manejo de fallos

• Si no hay credenciales, solo indicar los nombres de las variables de entorno necesarias y no solicitar que se ingresen valores secretos en el chat.
• Si hay límites de tamaño o tiempo, reintentar con --chunk-duration 10m.
• Si la confianza en la transcripción es baja, no corregir arbitrariamente nombres propios o números; dejarlos como elementos de revisión.
• Si falla el renderizado de HWPX, informar la causa y no proporcionar un archivo dañado como resultado.
• Si se solicita PDF, indicar que está fuera del alcance de la habilidad actual y que se necesita un entorno de conversión separado.

Autoevaluación

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

uv run scripts/self_test.py

Esta verificación no llama a ninguna API de reconocimiento de voz; realiza el análisis de transcripción, la validación JSON, la generación de HWPX y la validación estructural.