revisión-de-texto-web

Revisión de texto web

Convierte un código base de sitio web en un documento que un revisor no técnico pueda leer página por página y marcar, donde cada cadena mantiene una dirección (un código de referencia) para que sus correcciones puedan aplicarse mecánicamente al código fuente.

Por qué está construido así

El texto de un sitio web no es prosa. Son cientos de cadenas cortas en ranuras de maquetación fijas dentro del marcado. Por lo tanto:

• Un volcado de prosa con control de cambios devuelve un borrón de inserciones que no se pueden recolocar en el marcado sin adivinanzas. De ahí una fila por cadena, con un código de referencia.
• Un revisor que convierte un encabezado de tarjeta de 4 palabras en 12 palabras rompe el diseño y no puede verlo desde Word. De ahí los conteos de caracteres y la guía de longitud en lenguaje sencillo en filas restringidas.
• Los revisores nunca ven el código. De ahí que cada fila diga qué es ("Etiqueta de botón", "Texto alternativo") en palabras sencillas, y cada sección de página diga dónde está en el sitio real.

El documento debe leerse de arriba abajo por página (para que se pueda juzgar el tono y la narrativa) mientras mantiene cada cadena individualmente direccionable.

Archivos incluidos

scripts/merge_and_verify.py, scripts/build_review_docx.py, references/extraction-brief.md y assets/pages.example.json están junto a este archivo. Si faltan (la habilidad se instaló solo como SKILL.md), búscalos en ~/my-skills/website-copy-review/ o en el repositorio brianitsup/website-copy-review; si no se puede acceder a ninguno, díselo al usuario en lugar de improvisar el diseño del documento, porque no debe variar entre ejecuciones.

Reglas básicas

• Solo lectura. Nunca edites el repositorio. Todo el resultado va al área de trabajo a menos que el usuario lo pida en el repositorio.
• Instala python-docx en un entorno virtual en el área de trabajo, no globalmente: python3 -m venv <scratch>/venv && <scratch>/venv/bin/pip install python-docx
• Informa con honestidad. Si no se pudo analizar un archivo o no se pudo ejecutar una verificación, dilo; nunca reduzcas el alcance en silencio.
• Si el repositorio tiene una convención de flujo de trabajo de issues primero (o similar) en AGENTS.md, CLAUDE.md, PROJECT_WORKFLOW.md o CONTRIBUTING.md, dile al usuario que las correcciones devueltas y cualquier defecto necesitarán un issue antes de la implementación. No abras uno sin que te lo pidan.

Escala esperada: un sitio mediano de folleto tiene ~400–600 elementos en 15–20 páginas, un documento de 50–60 páginas. Eso es normal; las tablas por página lo mantienen navegable.

Paso 1 — Definir el alcance (preguntar una vez, con valores predeterminados)

Pregunta esto junto (usa AskUserQuestion si está disponible), recomendando los valores predeterminados:

1. ¿Qué texto? Texto codificado en plantillas/componentes solamente (predeterminado — el contenido del editor se puede corregir en el CMS sin un cambio de código), o también publicaciones/páginas creadas en el CMS.
2. ¿Cómo marcarán los revisores los cambios? Columna en blanco "Revisión sugerida" (predeterminado — inequívoco y mecánicamente aplicable), o comentarios/control de cambios de Word (natural, pero difícil de aplicar de vuelta).
3. ¿Qué estado del contenido? Árbol de trabajo, o producción/publicado? Indica que una base de datos local o una instantánea de contenido puede estar desactualizada respecto a lo que realmente está publicado.

Si el usuario no está, toma los valores predeterminados y dilo al principio del informe. Las respuestas van en la portada (meta.scope en pages.json).

Paso 2 — Descubrir dónde vive el texto

No asumas una pila. Inspecciona el repositorio (package.json, manifiestos de tema, configuración del framework, estructura de directorios) y enumera las fuentes de texto:

• En el código: .hbs, JSX/TSX, Vue, Svelte, Astro, Blade, ERB, Twig, temas PHP, HTML, archivos de contenido Markdown/MDX, JSON o YAML de i18n/locale.
• Fuera del código: Base de datos/API del CMS (Ghost, WordPress, Sanity, Contentful, Strapi) y configuraciones del sitio visibles para el visitante que no están en el repositorio — título del sitio, meta descripción, etiquetas de navegación, etiquetas de CTA/botón configuradas en el panel de administración. Cuando los extraigas, guarda la exportación sin procesar en <scratch>/snapshots/ para que puedan verificarse como cualquier otra fuente (ver Paso 4).

Siempre cubre estas categorías que se pasan por alto fácilmente, cada una etiquetada para que los revisores sepan lo que están viendo: texto alt (los lectores de pantalla y los motores de búsqueda lo leen — los nombres de socios/productos deben ser correctos), aria-label, placeholders de formularios, etiquetas de envío, mensajes de éxito/error/validación, estados vacíos, páginas 404/error, líneas de copyright y pies de página legales.

Asigna cada plantilla de página a su ruta URL real (routes.yaml, enrutamiento basado en archivos, configuración del router, asignaciones de plantilla→página del CMS). Si una plantilla no tiene página o ruta, dilo explícitamente en la nota de esa página: su texto es inalcanzable, y los revisores deben saberlo antes de dedicarle tiempo.

Luego escribe <scratch>/pages.json a partir de assets/pages.example.json: una entrada por página en el orden en que el documento debe presentarlas, con key, title, url, source, note opcional, más el bloque meta (proyecto, respuestas de alcance, exclusiones, plantillas sin texto codificado). El script de construcción lee esto — los metadatos de la página nunca se codifican.

Paso 3 — Extraer en paralelo con un contrato fijo

1. Enumera primero toda la superficie: cada plantilla de página y cada componente parcial/compartido que esas páginas incluyen (encabezados, pies de página, tarjetas, formularios de boletín, CTAs). Los parciales son lo que se pierde cuando los archivos se dividen entre agentes.
2. Divide en grupos no superpuestos (aproximadamente 3–6 archivos o ~1,500 líneas cada uno) y asigna cada archivo explícitamente. Los parciales compartidos reciben su propia entrada de página (ej. FOOTER, NAV) con una nota de que aparecen en todo el sitio, en lugar de repetirse debajo de cada página.
3. Genera un subagente por grupo, en un solo turno, en un modelo de gama media (ej. Sonnet): el trabajo es mecánico, pero las omisiones son invisibles y fatales. Pega references/extraction-brief.md textualmente en cada indicación, seguido de la lista de archivos de ese agente, el page_key a usar para cada archivo, la raíz del repositorio y la ruta de salida <scratch>/extract/<group>.json.
4. Cuando regresen, confirma que cada archivo enumerado aparece en alguna salida (o se reportó como sin texto). Reasigna cualquier cosa faltante.

Recopila los juicios informados de cada agente; los necesitarás en el Paso 4 y en el informe final.

Paso 4 — Fusionar y verificar de forma independiente (no lo saltes)

Las autoverificaciones de los agentes no son verificación. Ejecuta:

<venv>/bin/python scripts/merge_and_verify.py \
  --extract-dir <scratch>/extract --pages <scratch>/pages.json \
  --repo <repo-root> [--snapshot-dir <scratch>/snapshots] --out <scratch>/out

Esto fusiona todas las extracciones en el orden de pages.json, asigna referencias PAGEKEY-NN, recalcula chars y vuelve a verificar cada cadena contra su archivo fuente con tres normalizaciones progresivamente más flexibles: sin procesar (espacios en blanco colapsados), sin etiquetas, y con espacios en blanco comprimidos — porque cada una detecta algo diferente (el texto de atributo pasa sin procesar y falla sin etiquetas por construcción; eso es esperado). También afirma que no hay referencias duplicadas, ningún texto vacío, y que el page_key de cada elemento existe en pages.json. Salidas: items.json, copy-review-manifest.csv, verification.md.

El código de salida es distinto de cero mientras algo no esté resuelto. Por cada fila UNMATCHED, abre el código fuente y mira. El residuo legítimo suele ser bloques condicionales/de bucle donde el agente registró el texto renderizado en lugar de una subcadena literal — confirma que se renderiza como se registró, luego enuméralo en <scratch>/accepted.json como {"REF": "razón"} y vuelve a ejecutar con --accept <scratch>/accepted.json. Corrige errores genuinos en el JSON de extracción (no en el repositorio) y vuelve a ejecutar. Las referencias se asignan en la fusión, así que corrige los datos, luego vuelve a ejecutar, luego construye.

También haz una verificación puntual de integridad: elige dos o tres de los archivos más densos y compara el conteo de elementos con una lectura rápida del archivo. Las cadenas faltantes no aparecen en ninguna verificación automatizada.

Paso 5 — Construir el documento

<venv>/bin/python scripts/build_review_docx.py \
  --pages <scratch>/pages.json --items <scratch>/out/items.json \
  --out <scratch>/out/<Proyecto>-Website-Copy-Review.docx

El script controla el diseño para que nunca varíe entre ejecuciones: A4 apaisado, márgenes de 1,4 cm; portada (alcance, qué está incluido/no incluido, cómo revisar, mantener las filas sensibles a la longitud cerca de su longitud, no renumerar ni eliminar referencias, verificar los hechos — años, recuentos de personal, cifras, nombres de socios, títulos de trabajo — con tanto cuidado como la redacción); tabla de contenido con totales y plantillas vacías; una sección por página en página nueva; columnas Ref 2,2 / Elemento 4,3 / Texto actual 8,4 / Revisión sugerida 8,4 / Notas 3,6 cm; fila de encabezado oscura repetida; filas de banner de sección en mayúsculas teñidas; rayas de cebra; guía de conteo de caracteres en filas restringidas; celdas teñidas y advertencia de "mantén la parte {{…}}" en filas dinámicas; página de cierre con próximos pasos y una tabla de aprobación. Vuelve a abrir el archivo y afirma que el conteo de filas coincide y que las columnas de revisión/notas están vacías.

Nunca rellenes "Revisión sugerida" o "Notas". El juicio del revisor es el objetivo.

Si el usuario eligió comentarios/control de cambios de Word en el Paso 1, igualmente construye este documento (los códigos de referencia son lo que hace trazables los cambios controlados) y diles que las correcciones pueden necesitar coincidencia manual.

Paso 6 — Mirarlo antes de entregar

Las verificaciones estructurales prueban que los datos son correctos, no que se lean bien. Renderiza y realmente visualiza: la portada, una página de configuración/navegación, y la página más densa de párrafos largos (donde fallan los anchos).

soffice --headless --convert-to pdf --outdir <dir> <archivo>.docx
pdftoppm -png -r 80 -f <n> -l <n> <archivo>.pdf <prefijo>

Abre los PNG con Read. Si estas herramientas faltan, di claramente que no se realizó ninguna verificación visual.

Paso 7 — Reportar defectos del código por separado

Leer cada línea del marcado revela errores reales. Repórtalos en una sección separada (o en un source-defects.md separado) — son problemas de código, no de redacción. Comunes:

• Markdown literal en HTML renderizado (**negrita** mostrándose en la página)
• Enlaces de anclaje a IDs que no existen en ninguna parte
• Enlaces a secciones que existen pero no contienen nada accionable
• Plantillas sin página/ruta, por lo que su texto es inalcanzable
• Contenido CMS huérfano detrás de una plantilla personalizada que lo sobrescribe
• Valores de placeholder codificados en plantillas reutilizables

Verifica cada uno tú mismo antes de reportarlo — busca con grep el ID de destino, abre la plantilla. Los agentes exageran estos: un "anclaje roto" una vez resultó tener un objetivo válido cuya sección simplemente no tenía nada que accionar. Describe lo que realmente hay, con archivo y línea.

Paso 8 — Entregar

Envía el .docx al usuario. Menciona, brevemente: total de elementos y páginas, las decisiones de alcance tomadas, el manifiesto CSV (para aplicar las correcciones devueltas por referencia — mantenlo fuera del alcance del revisor), cualquier residuo de verificación que aceptaste y por qué, la lista de defectos, y la nota de issues primero si el repositorio tiene esa convención.

Aplicar las revisiones devueltas (cuando el usuario regrese)

Lee las filas de la tabla del .docx devuelto (Ref + Revisión sugerida + Notas), combínalas con copy-review-manifest.csv por Ref, y por cada revisión no vacía localiza text en file cerca de line y reemplázalo. Señala en lugar de recortar silenciosamente cualquier revisión que esté muy por encima de su chars en una fila restringida, y cualquiera que elimine una expresión {{…}}. Muestra al usuario los cambios planificados antes de editar el repositorio.