yapi777/create-doc

Create-doc — Crear un esquema para pasar al skill de creación de diapositivas

Lee los registros de investigación (registros de ejecución en md, resultados en CSV, figuras, código) y escribe en Markdown un esquema en el que, diapositiva por diapositiva, se decide "qué decir, con qué tipo de diseño mostrarlo, qué contenido incluir y qué se hablará".

El destinatario es el skill progress-report-deck (está en el mismo plugin research-slides, en la carpeta contigua ${CLAUDE_SKILL_DIR}/../progress-report-deck/). La salida de este skill está pensada para que progress-report-deck la lea considerando "cada encabezado ## = una diapositiva" y la inserte en las plantillas. Antes de empezar, lee ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md y comprueba que no haya discrepancias con los "Acuerdos con el skill de diapositivas" que aparecen más abajo (si las reglas de allí han cambiado, adáptate a ellas). Si no encuentras el archivo, puedes escribir siguiendo estos acuerdos.

Si existe el perfil del usuario ~/.claude/yapi-skills/profile.md (nombre, campo de investigación, audiencia principal, reglas propias), léelo al principio. Las reglas propias (esquema de colores, tamaño mínimo de fuente, etc.) tienen prioridad sobre los acuerdos siguientes y deben copiarse también en la sección "Acerca de este documento" del esquema.

Puedes consultar un ejemplo de esquema en references/template.md. Si tienes dudas sobre el formato, ajústate a ese ejemplo.

Acuerdos con el skill de diapositivas (basados en las reglas de progress-report-deck)

El esquema debe cumplir estas reglas. Si no se cumplen, en la fase de creación de diapositivas se eliminarán partes o habrá que rehacerlas.

Elemento	Acuerdo	Razón (regla de progress-report-deck)
Encabezados	Un ## = una diapositiva. No uses ## para nada que no sea una diapositiva, ni siquiera para notas aclaratorias. Usa # para separar capítulos.	El borrador se lee tomando cada ## como una diapositiva
Estructura	Orden fijo: Título → Índice (lo hecho hoy) → Antecedentes (1/2)(2/2) → Objetivo (meta concreta de hoy) → Contenido → Resumen y tareas pendientes → Agradecimientos.	Estructura fija de la plantilla
Antecedentes	Si no cambian con respecto a la vez anterior, escribe solo "Sin cambios (se mantiene el material de base)" sin desarrollar el contenido.	Los antecedentes casi siempre se mantienen
Meta concreta	En la diapositiva de objetivo, debes incluir obligatoriamente la frase "Meta concreta de hoy" (1-2 líneas).	El otro skill pregunta esto cada vez al usuario. Se decide de antemano
Número de diapositivas	Escribe el número final de diapositivas (para que el otro skill no tenga que fusionar o dividir).	Si hay muchos ##, el otro skill sugerirá fusionar
Tipo de diseño	En las diapositivas de contenido, asigna un tipo de diseño de la tabla siguiente.	Si solo se inserta texto con viñetas, se quejará de que "la mitad inferior está en blanco"
Colores	Solo dos significados: azul = propuesta, solución, conclusión, valor protagonista; naranja = método convencional, problema, observación, atención. No asignes un tercer color a un método concreto. En las tablas, indica que la fila protagonista se resalta en "azul claro".	El tema usa solo dos colores: azul #156082 y naranja #E97132
Cantidad de texto	Cada afirmación debe ocupar 30 caracteres o menos (lo que cabe en una línea con fuente de 18pt). Cada ítem de una lista con viñetas también debe tener unos 30 caracteres. Máximo 3 líneas por panel. Si necesitas más, usa una tabla o figura, o divide la diapositiva.	La fuente no puede ser menor de 16pt y no se permite reducir el tamaño para meter más texto
Tamaño de letra	No indiques "más pequeño", "nota en letra pequeña", etc. Incluso las notas al pie deben caber en una línea con 16pt.	No se permite texto con menos de 16pt
Ecuaciones	Escríbelas con $...$ (notación LaTeX) e indica explícitamente "Ecuación (OMML)".	Las ecuaciones se componen en OMML
Figuras	Especifica los PNG copiados en la carpeta images/ de salida con la ruta images/<nombre>.png (si solo hay PDF, conviértelo a PNG e inclúyelo). No uses rutas dentro del repositorio ni ../. Ten en cuenta que la diapositiva tiene una relación de aspecto 4:3 (por ejemplo, coloca dos figuras apaisadas una debajo de la otra).	En el pptx se pegan PNG. La diapositiva es 4:3. Es posible que la diapositiva se cree en otra carpeta o en otro equipo, y las rutas fuera de la carpeta no serán accesibles
Diagramas esquemáticos	Si no hay un archivo de figura y quieres mostrar algo esquemático (flujo de proceso, línea de tiempo, comparativa antes/después), escribe el nombre del tipo de diseño y las instrucciones de dibujo de forma concreta.	El otro skill así podrá manejar la figura sin tener que preguntar al usuario
Notas del orador	El contenido que se va a decir se escribe en "Notas". No se incluye en la diapositiva.	—
Complementos	Las diapositivas complementarias para preguntas se colocan después de "Muchas gracias por su atención".	El cierre es el final de la parte principal

Tipos de diseño que se pueden especificar (ejemplos reales en assets/template.pptx de progress-report-deck):

Tipo	Cuándo usarlo	Ejemplo en template.pptx
Chip + panel (problema → solución)	"Problema del método convencional → Solución actual" / "Observación → Solución"	p.7, p.11
Insignia numerada + panel	Enumeración de elementos con números ① ② ③ (ventajas, procedimiento)	p.8-9
Diagrama Antes/Después	Comparación entre método convencional y propuesto (izquierda = marco naranja, derecha = marco azul, flecha en medio)	p.10
Diagrama de línea de tiempo	Flujo de proceso en el tiempo (cajas con línea continua/discontinua + conectores)	p.12
Chip + panel de 2 columnas + barra inferior	Comparación lado a lado de dos métodos o configuraciones, incluye ecuaciones	p.13
Tabla + barra de ancho completo	Tabla de resultados y, debajo, una barra con "Lo que se deduce" (la fila protagonista se pinta de azul oscuro)	p.14
KPI en mosaico (2×2)	Mostrar 4 valores o conclusiones de forma grande y destacada	p.15
Lista de verificación (✓)	Enumeración de lo que se ha comprobado o hecho	p.16
Caja con borde de 2 niveles	Resumen / perspectivas futuras	p.17
Figura + barra de ancho completo	Pegar una figura existente grande y, debajo, una barra con lo que se deduce	(sustituir la tabla de p.14 por una figura)

El índice (lo hecho hoy) no lleva tipo de diseño (se deja como lista con viñetas y solo se ponen en negrita las palabras clave. Sin colores).

Procedimiento

1. Preguntar los requisitos (AskUserQuestion, resumir en una sola pregunta)

No preguntes sobre lo que ya se pueda deducir de la conversación o del texto de la solicitud. Pregunta solo lo que no esté claro.

• Tipo y duración de la presentación: Informe de progreso / Seminario / Congreso. Como referencia, una diapositiva de contenido equivale aproximadamente a 1 minuto (para 15 minutos, unas 10 diapositivas de contenido más las 5-6 de la estructura base)
• Audiencia: Miembros del laboratorio / Congreso / Personas de otras áreas. Esto determina el nivel de conocimiento previo que se puede asumir.
• Información complementaria a incluir (selección múltiple): Motivación / antecedentes, experimentos comparativos, análisis de fallos, evolución del método, impacto de correcciones de errores, etc. Las opciones deben basarse en los temas que se encuentren al leer los registros.
• Si los antecedentes se mantienen sin cambios: Si se van a cambiar con respecto al material anterior, indica qué se cambia.

Si el usuario responde con texto libre no contemplado en las opciones, trátalo también como un requisito (ej.: "Incluye también X como desencadenante").

2. Recopilar material (solo lectura; no reejecutar experimentos)

• Skill de diapositivas: ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md (confirmación de los acuerdos anteriores)
• Registros: Registro_ejecucion_*.md, *Resultados*.md, README.md, documentos de planificación, etc. Leer empezando por los más recientes.
• Valores numéricos: Tablas en summary/*.csv, *.md. Los valores que se vayan a incluir en la presentación deben copiarse siempre de estas fuentes.
• Figuras: Buscar PNG existentes con ls. Si hay figuras con etiquetas en español o japonés (dependiendo del idioma del proyecto), priorízalas. Anota la ruta original de las figuras que se vayan a usar (para copiarlas a images/ en el paso 4 y para citar la fuente).
• Valores de configuración: Los hiperparámetros, constantes y configuraciones de modelo que se incluyan en las diapositivas complementarias deben obtenerse del código real (constantes en el código, valores por defecto de argparse, JSON de configuración guardado en tiempo de ejecución), no de los registros en md. Si hay discrepancia entre el registro y el código, se da prioridad al código y se informa al usuario.

3. Decidir la estructura

Estructura base (ajustada a la plantilla de progress-report-deck):

1. Título
2. Lo hecho hoy (índice; lista breve de los encabezados de las diapositivas de contenido)
3. Antecedentes (1/2)
4. Antecedentes (2/2)
5. Objetivo (propósito + meta concreta de hoy)
6. ~ Diapositivas de contenido
7. Resumen y tareas pendientes
8. Muchas gracias por su atención
9. Diapositivas complementarias (para preguntas)

El flujo general de las diapositivas de contenido (ajustar el número según la duración):

1. Motivación / problema (por qué se hizo esto) → Chip + panel
2. Contenido de la propuesta / cambio y sus ventajas → Diagrama Antes/Después o Insignia numerada + panel
3. Detalle del método (flujo del proceso) → Diagrama de línea de tiempo
4. Garantía de corrección / verificación → Lista de verificación
5. Cómo se determinaron los parámetros → KPI en mosaico o Tabla + barra
6. Configuración experimental (datos, métodos de comparación, métricas de evaluación) → 2 columnas o Tabla + barra
7. Resultados (una diapositiva por afirmación principal) → Tabla + barra, Figura + barra
8. Coste / limitaciones → Tabla + barra o KPI en mosaico

Incluir siempre diapositivas complementarias (para preguntas). No cuentan para el tiempo de presentación.

• Configuración detallada (tabla del modelo, optimización, constantes)
• Configuración de datos o simulación
• Detalle de los métodos de comparación (especificar OMML para ecuaciones)
• Definición exacta de las métricas de evaluación
• Tabla de resultados completos de la búsqueda de parámetros, etc.
• Preguntas previstas y ejemplos de respuesta (unas 8): Estas no se convierten en diapositivas (se colocan como un capítulo con # al final del esquema, para uso del presentador). Prioriza preguntas que apunten a puntos débiles: "¿No es pequeña la diferencia?", "¿Se puede afirmar con un solo ensayo?", "¿Por qué este objeto de comparación?", "¿Cuál es el coste computacional?", "¿Cuál es la base de la afirmación no verificada?", etc.

4. Escribir (generar la salida en una carpeta)

Puede que las diapositivas se creen en otra carpeta o en otro equipo (un PC con PowerPoint). Por lo tanto, hay que empaquetar el esquema y las imágenes que se van a usar en una sola carpeta, de modo que con solo llevar esa carpeta se puedan crear las diapositivas.

Documento-creacion-diapositivas-<fecha>/
├── Documento-creacion-diapositivas-<fecha>.md   ← Esquema
└── images/
    ├── speed_sweep.png
    └── ...

• El nombre de la carpeta y del archivo md deben ser Documento-creacion-diapositivas-<fecha> (ej.: Documento-creacion-diapositivas-2026-10-15/). La fecha es la de creación, en formato YYYY-MM-DD. Si el mismo día se crea otro esquema para otra presentación y hay conflicto de nombres, añadir un identificador corto después de la fecha (ej.: Documento-creacion-diapositivas-2026-10-15-seminario/). No sobrescribir carpetas existentes. Crear la carpeta en la raíz del proyecto.
• Imágenes: Copiar todas las figuras que se usen en el esquema a images/ (copia, no mover. No modificar los archivos originales).
  • Mantener el nombre original del archivo. Si hay conflicto de nombres o el nombre es poco descriptivo (fig1.png, etc.), renombrar a un nombre alfanumérico que indique el contenido (ej.: velocity_field_f195.png). No usar espacios.
  • Si una figura solo existe en PDF, convertirla a PNG e incluirla (ej.: pdftoppm -png -r 200 -singlefile in.pdf images/nombre, o con PyMuPDF a 200 dpi).
  • En el esquema, referenciarla con images/<nombre>.png.
  • Dejar la ruta original en el capítulo "Fuentes", en el formato "images/xxx.png ← ruta original" (para poder localizar la figura si hay que rehacerla más adelante).
• Diagramas esquemáticos (cuando no hay archivo de figura): No crear imagen; escribir las instrucciones de dibujo en el esquema.

Al principio, en la sección "Acerca de este documento" (capítulo con #, que no se convierte en diapositiva), incluir las instrucciones para progress-report-deck:

• Tipo, duración, número de diapositivas y audiencia de la presentación.
• Formato de cada diapositiva (ver más abajo).
• No modificar ni redondear los valores numéricos.
• Usar esta carpeta como carpeta de trabajo para ejecutar progress-report-deck. Las figuras están en images/ de esta carpeta y se especifican con images/<nombre>.png. No crear figuras nuevas (los diagramas esquemáticos se dibujan según las instrucciones).
• Reglas de notación para nombres de métodos, asignación de colores (azul = propuesta, naranja = método convencional / de comparación).
• Si los antecedentes se mantienen sin cambios o no.

Formato de cada diapositiva:

## Diapositiva N — <Título>

- **Tipo**: <Tipo de diseño (uno de la tabla anterior)>
- **Afirmación**: <Una frase de 30 caracteres o menos. Lo más importante que se quiere decir en esta diapositiva>
- **Texto**: <Lista con viñetas. Unos 30 caracteres por ítem, máximo 3-4 ítems>
- **Tabla** / **Figura**: <Para tabla, escribirla en Markdown, indicando qué fila/columna se resalta. Para figura, ruta `relative/path.png` (de qué figura se trata)>
- **Ecuación (OMML)**: <Si la hay, con $...$>
- **Notas**: <Contenido que se va a decir. No se incluye en la diapositiva>

Reglas al escribir:

• La afirmación debe ser una conclusión. No escribir "Resultado 1", "Acerca de X", "Mostrar X", sino "La diferencia aumenta a medida que aumenta la velocidad". No terminar con "desu/masu" (en español no se aplica, pero en general, evitar gerundios o formas no concluyentes).
• Las palabras valorativas deben respaldarse con números. Si se escribe "significativamente", "efectivo", "superior", en la misma diapositiva debe incluirse el objeto de comparación, la métrica y el número de ensayos. Términos como "equivalente", "garantizado" tienden a ser exagerados (mejor "casi equivalente", "se ha confirmado").
• Evitar palabras típicas de texto generado por IA (muy, innovador, es posible hacerlo, sin interrupciones, etc.). Consultar la lista y ejemplos de sustitución en ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md.
• Cada ítem de la lista debe ser una oración completa (si hay dos oraciones unidas por punto, separarlas en dos ítems).
• Si algo no está verificado, escríbelo explícitamente. No mezclar propiedades esperadas con lo que se ha demostrado experimentalmente. Incluir una línea en el texto o en la barra de la diapositiva correspondiente, y también en la sección "Futuro" del resumen y tareas pendientes.
• Las condiciones para una comparación justa (por ejemplo, se usó una configuración que aseguraba la convergencia) se escriben en una línea como nota al pie. Las explicaciones largas sobre los antecedentes solo se escriben si el usuario ha dicho que las incluya.
• Las explicaciones detalladas que no caben en la diapositiva se trasladan a las notas o a las diapositivas complementarias. No alargar el texto de la diapositiva.
• Al final, añadir una tabla de "Fuentes" (contenido → archivo) como capítulo con #.

5. Verificar (obligatorio)

1. Verificación mecánica de valores numéricos: Extraer todos los números decimales del esquema mediante una expresión regular y comprobar si aparecen en los archivos md / CSV de origen (en los CSV, redondeados a 4 o 2 dígitos). Para aquellos que no se encuentren, comprobar uno por uno si se trata de una diferencia calculada por ti mismo, un error de transcripción o una incoherencia en el redondeo, y corregirlo. Colocar el script de verificación en el scratchpad.
2. Autosuficiencia de la carpeta: Comprobar que todas las referencias a figuras en el esquema son a archivos PNG dentro de images/ y que esos archivos existen realmente. No deben quedar rutas con ../ ni rutas absolutas ni rutas dentro del repositorio. A la inversa, no debe haber archivos sobrantes en images/ que no se referencien. Informar también del tamaño total de la carpeta.
3. Contenido de las figuras: Abrir realmente las figuras y comprobar que las afirmaciones que se hacen sobre ellas ("X es grande", etc.) son correctas.
4. Verificación mecánica de los acuerdos: Comprobar que el número de ## coincide con el número de diapositivas previsto, que todas las diapositivas tienen un "Tipo" (excepto las de la estructura base), que no hay instrucciones de un tercer color. La longitud de las afirmaciones (30 caracteres o menos), si la afirmación es una conclusión, el uso de palabras con olor a IA, y las incoherencias ortográficas se comprueban con el script de inspección del skill de diapositivas:

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<esquema.md>" > check_doc.txt
   

   Leer la salida con Read y corregir las advertencias (se pueden dejar si es la forma correcta de decirlo en la investigación). Si la última línea no es DONE: …, la comprobación ha fallado; no considerarla como sin errores. Si no se encuentra el script, comprobar este punto manualmente.
5. Número de diapositivas: Contar que el número de diapositivas de la parte principal se ajusta al requisito.

6. Informar

• En la primera línea, indicar el lector previsto (ej.: "Lector previsto: skill progress-report-deck (y, más allá, la audiencia del seminario del laboratorio)").
• La ruta de la carpeta de salida y su contenido (1 archivo md + número y tamaño total de las imágenes).
• La estructura (una línea por diapositiva) y el contenido de las diapositivas complementarias.
• El resultado de la verificación (número de valores numéricos cotejados, confirmación de figuras, comprobación de acuerdos).
• Puntos que el usuario debería conocer antes de la presentación: Afirmaciones no verificadas, valores numéricos que puedan ser objeto de preguntas difíciles y su motivo, de qué fecha y código son los resultados utilizados.
• Próximo paso: Indicar que "con esta carpeta (si se va a usar en otro equipo, copiar la carpeta completa) se puede ejecutar progress-report-deck para generar las diapositivas". La forma de transportarla (USB, Box/OneDrive, comprimir en zip y enviar, etc.) queda a criterio del usuario.
• No hacer commit (a menos que se solicite).