saituye/kullanimkilavuzu

Manual de usuario a partir de capturas de pantalla / Ekran Görüntüsünden Kullanım Kılavuzu → Screenshot → User Manual

Entrada: capturas de pantalla + un manual de ejemplo. Salida: un nuevo manual que imita el estilo y la estructura del ejemplo, pero cuyo contenido proviene de las imágenes.

Input: screenshots + one example manual. Output: a new manual that copies the example's style and structure while its content comes from the images.

Este archivo es bilingüe: las instrucciones están en español, las reglas críticas también se repiten en inglés. El idioma del manual generado es el que el usuario solicite; si no se especifica, se utiliza el idioma del manual de referencia.

---

1. Entradas / Inputs

Entrada	Obligatorio	Notas
Capturas de pantalla	✅	Carpeta o lista de archivos. Pista de orden: nombre de archivo, marca de tiempo, EXIF.
Manual de ejemplo	✅	.pdf, .docx, .md, .txt, .html. Es la fuente de estilo y estructura.
Nombre del producto / proceso	➖	Si no se proporciona, se deduce de las pantallas y se confirma con el usuario.
Público objetivo e idioma	➖	Si no se proporciona, se deduce del manual de referencia.
Formato de salida	➖	Por defecto: Markdown (+ .docx / .html imprimible si se solicita).
Información de marca	➖	Empresa, número de documento, revisión: si no se proporciona, se deja un marcador de posición.

Intenta deducir la información que falte antes de preguntar. Pregunta solo por lo que no se pueda deducir de las pantallas y del manual de referencia; como máximo 3 preguntas.

Infer before you ask. Ask at most 3 questions, only for what the images and the reference manual cannot answer.

Prioridad de la información / Source priority

Si hay conflicto, decide según este orden — el que está arriba gana:

1. Información proporcionada explícitamente por el usuario
2. Capturas de pantalla
3. Fotos de la máquina/producto
4. Información de la plantilla del manual de referencia
5. Conocimiento técnico general (solo se puede usar en lugar de dejar un marcador de posición; no se considera inventado pero se debe solicitar confirmación)

On conflict: user's explicit statements > screenshots > photos > reference template > general knowledge.

Dos modos / Two modes

Modo	Cuándo	Qué se conserva
Modo estilo	La referencia es un .md/.txt simple	Diseño de títulos, modo verbal del paso, formato de advertencias
Modo plantilla	La referencia es un PDF/DOCX corporativo (portada, índice, encabezado, número de documento)	El orden de las secciones, la numeración, la identidad del documento, el formato de tablas/advertencias se conservan exactamente; el contenido se completa con el producto real

En modo plantilla, no copies el PDF. Toma la plantilla como esqueleto, genera el contenido a partir de las capturas de pantalla. Si una sección ya existe, consérvala y mejórala; si falta, añade una nueva sección que se ajuste al diseño del documento.

In template mode: keep the section order, numbering and document identity; never copy the PDF's sentences — fill it with what the screenshots show.

---

2. Salidas / Outputs

<directorio-salida>/
├── manual.md          # Entrega principal — nuevo manual de usuario
├── images/            # Capturas de pantalla copiadas/renombradas
├── manual.html        # (opcional) versión imprimible desde el navegador
├── manual.docx        # (opcional) versión de Word
└── 00-analisis.md     # Notas de trabajo: inventario de pantallas + contrato de estilo

00-analisis.md no es un documento entregable, es evidencia comprobable: muestra qué pantalla va con qué paso y qué decisión de estilo se tomó de la referencia. Genéralo siempre.

---

3. Mapeo de herramientas / Tool mapping

La habilidad no está escrita para ninguna herramienta en particular. Usa la correspondencia que tengas a mano:

Necesidad	Claude Code	Cursor	Codex / DeepSeek Harness	Otros
Ver la imagen	Read (visual)	Read	read_image	Adjunta la imagen al mensaje
Escribir archivo	Write / Edit	Write	write / edit	Editor
Ejecutar script	Bash	terminal	pwsh / bash	Terminal
Leer .docx / .pdf	Bash + python	terminal	pwsh + python	Python

Crítico: Debes ver realmente las imágenes. No inventes el contenido a partir del nombre del archivo o de una interfaz que conozcas de antemano.

Always actually view the images. Never infer screen content from file names.

---

4. Flujo de trabajo / Workflow

Realiza un seguimiento del progreso con esta lista:

- [ ] 1. Recopilar y validar entradas
- [ ] 2. Extraer el contrato de estilo de la referencia
- [ ] 3. Leer cada captura de pantalla individualmente
- [ ] 4. Ordenar las pantallas en un flujo, marcar los vacíos
- [ ] 5. Redactar el manual
- [ ] 6. Puerta de control de calidad — `check_manual.py`
- [ ] 7. Entregar (+ docx/html opcional)

Paso 1 — Recopilar y validar entradas / Intake & validate

• Enumera los archivos de captura de pantalla; reporta el número y los formatos.
• Lee el manual de referencia (.docx → python-docx, .pdf → pypdf/pdftotext, texto plano → directamente).
• Si hay archivos ilegibles o dañados, dilo inmediatamente, no los ignores en silencio.
• Determina el directorio de salida y crea la subcarpeta images/.
• Copia las imágenes: copia cada pantalla que usarás en el manual a images/. Conserva los nombres (ej. 01-inicio.png → images/01-inicio.png); si los renombras, el script de QA los emparejará por hash de contenido, pero es más seguro conservar el nombre para no perder el orden. No escribas la ruta relativa a la carpeta original.

List every screenshot, read the reference manual, report unreadable files, create the output folder, then COPY each screenshot into images/ keeping its file name. Never link back to the original screenshots folder.

Paso 2 — Extraer el contrato de estilo de la referencia / Extract the style contract

Primero mide, luego interpreta:

python <directorio-de-la-habilidad>/scripts/read_reference.py <manual-ejemplo> \
    --out 00-analisis-referencia.md --json 00-analisis-referencia.json

Este script extrae un perfil medido del PDF/DOCX/MD: ficha del documento, jerarquía de títulos, profundidad de numeración, encabezado/pie de página que se repite en cada página (número de documento, revisión), patrón de pies de foto de figuras/tablas, tamaño de fuente y colores. Transfiere la salida a la tabla reference/contrato-estilo.md.

read_reference.py requiere PyMuPDF para PDF y python-docx para DOCX; si no están disponibles, pide al usuario la versión .md/.txt (el script muestra el comando de instalación).

No vas a copiar el contenido del manual de referencia, vas a copiar su formato. Completa los campos en el archivo reference/contrato-estilo.md y escríbelos en 00-analisis.md:

• Jerarquía de títulos y numeración (1., 1.1, Paso 1, Capítulo)
• Modo verbal de la frase del paso (imperativo, "haga clic", "pulse") y su longitud
• Ubicación de la captura de pantalla: ¿antes o después del paso? ¿tiene pie de foto? ¿numerado?
• Tipos de cuadros de aviso/advertencia (Nota, Advertencia, Consejo, Precaución) y su formato de marcado
• Uso de tablas, listas, negrita
• Secciones preliminares: portada, versión, fecha, índice
• Secciones finales: preguntas frecuentes, solución de problemas, glosario
• Tono: formal / informal, "usted" / "tú"
• Glosario de términos (la nomenclatura utilizada por la referencia)
• Identidad del documento: número de documento, revisión, fecha, bloque de empresa (en modo plantilla se conserva exactamente; si no se conocen los valores, se deja un marcador de posición)
• Profundidad de la numeración: si la referencia usa 4 niveles como 6.5.1.1, el nuevo manual también usará la misma profundidad

Extract form, not content: hierarchy, numbering, step voice, image placement, callout types, tables, front/back matter, tone, terminology, document identity.

Paso 3 — Leer cada captura de pantalla individualmente / Read every screenshot

Para cada imagen, registra según el esquema reference/analisis-pantallas.md:

Campo	Ejemplo
Archivo	03-configuracion.png
Nombre de la pantalla / página	Configuración
Componentes principales visibles	menú lateral, botón guardar, lista desplegable de idioma
Acción realizada	Se selecciona "Español" en la lista desplegable "Idioma"
Estado	antes / después / paso intermedio
Énfasis / flecha / recuadro	marco rojo en el botón "Guardar"
Ilegible / no claro	nombre de campo borroso → [?]
Nº de paso (borrador)	4

Prohibición de inventar: No escribas nombres de botones, rutas de menú, etiquetas de campos o mensajes de error que no sean visibles en la pantalla. Si no estás seguro, pon [?] y añádelo a la sección "Preguntas abiertas".

Bloque de descripción por pantalla para manuales de interfaz/HMI. Para cada captura de pantalla, escribe las cinco partes siguientes (es la estructura esperada en la documentación del operador):

### <Nombre de la Pantalla>

**Propósito.** Para qué se utiliza esta pantalla — 1–2 frases.
**Información mostrada.** Valores, indicadores, colores de estado visibles.
**Funciones de los botones.**

| Botón | Función | Descripción |
|---|---|---|

**Uso del operador.** Qué se hace paso a paso.
**Precaución.** Si hay algún mal uso, se incluye una advertencia; si no, no escribas esta línea.

Proporciona el pie de foto con el patrón de la referencia (ej. Figura 12–Pantalla de Motores CA). Describe los elementos importantes de la imagen numerándolos (1 – INICIO, 2 – PARADA) pero sin reducir la legibilidad ni escribir sobre ella.

For UI/HMI manuals, describe every screen with the five-part block: purpose, displayed values, button table, operator steps, cautions. Number callouts only when it improves clarity.

Never invent a button label, menu path, field name or message that is not visible in the image. Mark uncertainty with [?] and list it under Open questions.

Paso 4 — Ordenar las pantallas en un flujo / Order into a flow

• Utiliza las señales de orden: número de nombre de archivo → marca de tiempo → estado de la pantalla (antes/después) → flujo lógico.
• Agrupa las pantallas en secciones (ej. Instalación, Configuración Inicial, Uso Diario).
• Marca los vacíos: "Al pasar del paso 1 al paso 3 falta una pantalla intermedia", por ejemplo. No inventes el paso faltante; pídelo al usuario o escríbelo en la sección "Preguntas abiertas".
• Vincula cada pantalla a exactamente un paso. Si la misma pantalla narra varios pasos, usa la imagen en un solo paso y haz referencia al otro paso en el texto.

Order with file names → timestamps → before/after state. Group into sections. Flag gaps instead of inventing steps. One screenshot maps to exactly one step.

Paso 5 — Redactar el manual / Draft the manual

Toma el esqueleto de templates/plantilla-manual.md y complétalo con el contrato de estilo del Paso 2. Reglas:

1. Cada paso = una acción + una captura de pantalla que muestra esa acción.
2. El texto del paso es breve: 1–3 frases. Si se necesita justificación/teoría, muévela a una nota "¿Por qué?" separada.
3. La ruta de la imagen es relativa y portátil: ![Pantalla de configuración](images/03-configuracion.png). Adapta el pie de foto al formato de la referencia.
4. Mantén los títulos y la numeración en el mismo esquema que la referencia; el contenido lo tomas de la pantalla.
5. Usa los términos del glosario de la referencia exactamente igual — no inventes sinónimos.
6. Si la referencia tiene secciones preliminares (título, versión, público objetivo) y secciones finales (FAQ, solución de problemas, glosario), añádelas; si no, no las añadas.
7. Toda la información no verificable de las pantallas se marca: incertidumbre breve con [?], información faltante con un marcador de posición descriptivo del diccionario reference/marcadores-posicion.md ([A COMPLETAR POR EL FABRICANTE], [REQUIERE VERIFICACIÓN] …).
8. Al final del manual, añade una sección "Preguntas Abiertas / Open Questions" (si está vacía, escribe "Ninguna."). Esta sección es un anexo de QA, no forma parte del estilo de la referencia; el usuario puede eliminarla al preparar la publicación. Indícalo en el mensaje de entrega.
9. Separa la información para el operador y para el servicio técnico. La programación del PLC, los nombres de las etiquetas, los parámetros del servo, los algoritmos de software y los detalles de comunicación no entran en la sección principal para el operador; si es necesario, abre una sección separada bajo el título "Servicio Técnico / Personal de Mantenimiento".

One step = one action + one screenshot. Relative image paths. Mirror the reference's numbering and terminology. Mark unverifiable claims with [?].

Paso 6 — Puerta de control de calidad / QA gate

Ejecuta los comandos desde la raíz del proyecto y proporciona la ruta completa del script según la carpeta de la habilidad — el script y el manual están en carpetas diferentes:

python <directorio-de-la-habilidad>/scripts/check_manual.py <salida>/manual.md \
    --screenshots <carpeta-pantallas> --reference <manual-ejemplo.md>

El script verifica: si las rutas de las imágenes existen, si cada pantalla se ha utilizado al menos una vez (por nombre o hash de contenido), si la numeración de títulos/secciones es continua, si la numeración de pasos es consistente (global o por sección), si hay restos de TODO/XXX/<marcador de posición>, si los [?] están en la sección "Preguntas Abiertas", y cuántos marcadores de posición de campo esperan ser completados. Si hay errores, corrígelos y vuelve a ejecutar. No entregues sin que pase.

No pases .docx/.pdf como --reference; primero extrae el perfil con read_reference.py para la comparación de estilo (el script lo indicará como advertencia).

Run the checker; fix and re-run until it passes. Do not deliver a failing manual.

Paso 7 — Entregar / Deliver

• manual.md + images/ + 00-analisis.md están listos.
• Si se solicita: python <directorio-de-la-habilidad>/scripts/convert.py <salida>/manual.md --format docx,html (si --out es otra carpeta, las imágenes también se copian allí; --lang determina el idioma del HTML).
  • Para .docx se necesita python-docx; si no está disponible, el script muestra el comando de instalación.
  • .html siempre se puede generar e imprimir desde el navegador con Ctrl+P → PDF.
• En modo plantilla, pon el número de documento/revisión en el encabezado del .docx y el número de página en el pie de página (consulta convert.py --doc-no, --header, --footer).
• En el mensaje de entrega: número de pantallas, número de pasos, número de secciones, número de [?], número de marcadores de posición de campo y, si faltan pantallas, su lista.

---

5. Reglas estrictas / Hard rules

1. No escribas sin ver. Ve realmente cada captura de pantalla; no deduzcas el contenido del nombre del archivo.
2. No inventes. No escribas etiquetas, menús, mensajes, versiones o números que no estén en la pantalla.
3. Formato de la referencia, contenido de la pantalla. No copies las frases del manual de referencia.
4. Que la incertidumbre sea visible. [?] + sección "Preguntas Abiertas"; no hagas suposiciones silenciosas.
5. Una pantalla = un paso. Ninguna imagen se queda sin usar.
6. Rutas portátiles. Ruta relativa images/...; no escribas rutas absolutas de Windows.
7. Idioma del usuario. El idioma del manual es el solicitado; no el idioma de las instrucciones de la habilidad.
8. Informa de las entradas faltantes. Si hay un archivo ilegible o falta una pantalla intermedia, dilo.
9. Si no puedes ver, detente. Si no tienes capacidad para leer imágenes (la herramienta no la tiene o el modelo no admite imágenes), no empieces a escribir el manual. Informa al usuario de que no puedes leer las imágenes en esta sesión y solicita una sesión con capacidad de procesamiento de imágenes. Está prohibido generar contenido a partir de conjeturas basadas en nombres de archivos.

1 Never write without viewing. 2 Never invent UI. 3 Form from reference, content from images. 4 Surface uncertainty with [?] or an explicit placeholder. 5 One screenshot = one step, none unused. 6 Relative image paths. 7 Manual language = requested language. 8 Report missing or unreadable inputs. 9 If you cannot see, stop.