audit-html-project

name	audit-html-project
description	Procedimiento sistemático para auditar proyectos HTML masivos: detectar errores de navegación rota, atribuciones incorrectas, páginas huérfanas, inconsistencias de diseño y consistencia de contenido. Incluye formato de salida estructurado con severidades.
version	2.2.0
author	Hermes Agent
tags	["html","audit","quality","static-site","education"]

Audit HTML Project — Auditoría Sistemática de Proyectos HTML

Procedimiento para auditar proyectos HTML grandes (10+ archivos) de forma sistemática y eficiente.

Cuándo usar

• Proyecto HTML con 10+ archivos y el usuario reporta errores
• Antes de hacer commit/push a un repositorio de contenido educativo
• Cuando se genera contenido HTML masivamente y se necesita QA
• Cuando un sitio estático muestra errores de navegación
• SPA con backend (Express + Chart.js + Three.js) — auditoría de endpoints, sync de datos, responsive de componentes JS, estado de DB

Pasos

1. Inventario del proyecto

import os
base = "/path/to/project"
html_files = [f for f in os.listdir(base) if f.endswith('.html')]
# Clasificar por tipo: páginas de contenido, páginas índice, archivos de navegación

2. Detección de errores sistemáticos

Escanear cada archivo por estos problemas:

Críticos (❌):

• Sin atribución correcta (David Antizar + ❤️)
• Navegación rota: href="#"> con texto "Anterior" o "Siguiente"
• Enlaces rotos internos: referencias a archivos que no existen

Advertencias (⚠️):

• Sin ejercicios interactivos (en contenido educativo)
• Sin resumen final
• Sin sección de teoría
• Sin ejemplos
• Sin caja de error frecuente o idea clave
• Sin barra de progreso
• Contenido inexistente (páginas de volumen vacías)

3. Clasificar por severidad

1. Bloqueantes — navegación rota, enlaces rotos, contenido inexistente
2. Importantes — atribuciones incorrectas, sin resumen
3. Mejora — sin ejercicios, sin ejemplos

4. Estrategia de escaneo para proyectos grandes (30+ archivos)

Para proyectos con 30+ archivos HTML, NO usar read_file por cada archivo — es lento y consume el límite de tool calls. Usar grep vía terminal para el escaneo inicial:

# Escaneo masivo de atribución
grep -c 'David Antizar' *.html | grep ':0$'

# Escaneo de KaTeX
grep -c 'katex' *.html | grep ':0$'

# Enlaces a archivos que no existen
for f in *.html; do
  grep -oP 'href="[^"]*\.html"' "$f" | while read -r href; do
    target=$(echo "$href" | sed 's/href="//;s/"//')
    [ ! -f "$target" ] && echo "ROTO: $f → $target"
  done
done

Luego, para las fases de corrección y verificación profunda, usar execute_code con Python y un solo script que procese todos los archivos.

5. Corrección en lotes

Usar execute_code con Python para batch-fix:

from hermes_tools import read_file, write_file, patch
import os

base = "/path/to/project"
html_files = sorted([f for f in os.listdir(base) if f.endswith('.html')])
all_set = set(html_files)

# Ejemplo: corregir todas las atribuciones
files = ['s09-3-bachiller.html', 's10-1-carrera.html', ...]
for f in files:
    content = read_file(path=os.path.join(base, f)).get('content', '')
    content = content.replace("corazón", "❤️")
    write_file(path=os.path.join(base, f), content=content)

5.1 Añadir CDN faltante (KaTeX, Plotly.js, etc.)

Para proyectos educativos con contenido matemático, verificar si KaTeX está presente y añadirlo si falta:

katex_cdn = '''<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" onload="renderMathInElement(document.body,{delimiters:[{left:'\\\\[',right:'\\\\]',display:true},{left:'\\\\\\(',right:'\\\\)',display:false}]})"></script>'''

for fname in archivos_sin_katex:
    content = read_file(path=join(base, fname)).get('content', '')
    new_content = content.replace('</title>', f'</title>\n{katex_cdn}', 1)
    write_file(path=join(base, fname), content=new_content)

Regla: KaTeX SOLO para niveles donde haya fórmulas (ESO, Bachiller, Universidad). Primaria usa emojis y texto plano — no necesita KaTeX.

5.2 Crear índices de nivel faltantes

Cuando un nivel (ej: 1º Primaria) carece de índice, y otros niveles (4º+) sí tienen, crear el índice replicando el diseño visual y estructural de los existentes:

# 1. Identificar un índice de referencia (ej: s04-4primaria.html)
# 2. Extraer su estructura: header, grid de tarjetas, colores, footer
# 3. Mapear las sesiones reales del nivel
# 4. Generar el nuevo índice con ese mismo diseño

El nuevo índice debe incluir:

• Header con título y descripción del nivel
• Grid de tarjetas, UNA por sesión, con: título, descripción corta, tag/tema
• Cada tarjeta enlaza a su sesión correspondiente
• Footer con atribución y enlace "Volver al índice general"
• Misma paleta de colores y glassmorphism que los índices existentes

Regla: NO reutilizar nombres de archivo existentes. Si s01-1primaria.html ya existe y es una sesión, crear s01-1primaria-index.html como índice.

6. Verificación post-corrección

Re-ejecutar el escáner para confirmar que todos los errores se resolvieron. Usar un script de verificación único que cubra 8 checks:

print('1. ENLACES ROTOS:')    # 0 = perfecto
print('2. ATRIBUCION:')       # 0 = perfecto
print('3. KATEX:')            # 0 en niveles que lo necesitan
print('4. NUEVOS INDICES:')   # existen los que creamos
print('5. INDEX.HTML ENLACES:')  # apuntan a los nuevos índices
print('6. ENLACES CORREGIDOS:')  # los targets rotos ya no aparecen
print('7. CONEXION CADENAS:')    # cadenas paralelas conectadas
print('8. INDEX.HTML ATRIBUCION:') # tiene footer

Formato de salida (preferido por el usuario)

El usuario pide auditorías "estrictas y críticas" que "expliquen todo bien". Usar este formato:

# 🔍 AUDITORÍA COMPLETA — [Nombre del Proyecto]

**Proyecto:** [Descripción]
**Archivos HTML:** [N]

---

## 📊 RESUMEN EJECUTIVO

| Severidad | Encontrados | Estado |
|-----------|------------|--------|
| ❌ **Críticos** | N | [resumen] |
| ⚠️ **Importantes** | N | [resumen] |
| 💡 **Mejoras** | N | [resumen] |

---

## ❌ ERRORES CRÍTICOS

### 1. [Descripción del error]
[Tabla con archivos afectados y detalle del error]

**Impacto:** [Qué le pasa al usuario/alumno]

---

## ⚠️ PROBLEMAS IMPORTANTES

[Similar formato]

---

## 💡 MEJORAS SUGERIDAS

[Similar formato]

---

## ✅ LO QUE FUNCIONA BIEN

[Bullet points positivos]

---

## 📋 PLAN DE CORRECCIÓN

Si quieres que arregle todo, el orden sería:
1. **Fase 1 (Crítico):** [Acción]
2. **Fase 2 (Crítico):** [Acción]
...

Regla: SIEMPRE terminar con "¿Quieres que empiece a corregir?" — el usuario quiere acción, no solo diagnóstico.

Reglas

• NUNCA modificar la estructura de navegación de sesiones individuales (eso es responsabilidad del generador)
• Las páginas de volumen (nivel educativo completo) deben ser índices funcionales con: título, descripción, lista de sesiones con enlaces, objetivos de aprendizaje y resumen
• El INDEX.html debe reflejar correctamente el contenido real (niveles, etiquetas, descripciones)
• Siempre verificar que los archivos referenciados existen antes de corregir enlaces
• Commit y push tras las correcciones
• RITMO: no parar entre pasos — El usuario frustración = "¿por qué has parado?". Flujo: terminar un fix → siguiente inmediatamente. Mostrar progreso en vivo, no esperar a tener todo perfecto para comunicar. Si hay 3+ fixes, hacerlos secuencialmente sin preguntar entre cada uno.

Flujo post-auditoría: fix → generate → deploy

Cuando el usuario pide "arreglar y completar" tras una auditoría, el flujo natural es:

1. Fix crítico → corregir enlaces rotos, atribuciones, navegación (usar execute_code + patch para fixes simples, write_file para HTML completo)
2. Fix importante → actualizar trackers (progress.json, README, etc.) — ⚠️ NO usar read_file para JSON (prependea números de línea), usar terminal("cat ...") + json.loads()
3. Generar contenido faltante → cargar skill del dominio, generar HTML con template, verificar calidad (>12KB, SVG, ejercicios)
4. Actualizar índice → INDEX.html con todos los temas
5. Deploy → git push (Pages se activa automático si repo es público)

Cada fase → commit separado

• 🔧 Fix: <descripción> para correcciones
• 📝 <bloque>: <temas generados> para contenido nuevo
• INDEX: actualizado con N temas para actualización del índice

Pitfalls

• 🔴 CSS CON DOBLES LLAVES {{}} DE TEMPLATE ENGINE — Algunos archivos HTML generados por scripts Python/Jinja pueden contener {{ y }} en lugar de { y } en bloques <style>. Esto rompe TODOS los estilos CSS del archivo. Detección: grep -n '{{' *.html dentro de bloques <style>. Corrección: reemplazar {{ → { y }} → } SOLO dentro de <style> tags (nunca en HTML content). Prioridad: ❌ Crítico — el archivo se ve sin estilos. Ver references/css-double-braces-fix.md para patrón de corrección batch.
• 🔴 PREFIJOS DE LÍNEA N| EN HTML — Archivos HTML contienen prefijos tipo 1|, 2| al inicio de cada línea. Causa CSS destruido + texto basura visible. Origen: output de tools de visualización de código guardado como archivo real. Detección: grep -rlP '^\s*\d+\|' *.html. Corrección: re.sub(r'^\s*\d+\|', '', content, flags=re.MULTILINE). Trampa: read_file de Hermes SIEMPRE prependea N| — no confundir con corrupción real. Usar terminal("head -5 file") para verificar contenido real. Ver references/line-number-prefix-corruption.md.
• 🔴 NÚMEROS DE LÍNEA INCORPORADOS EN HTML (N| PREFIX) — Archivos HTML pueden contener prefijos tipo 52| o 3| al inicio de cada línea. Causa: una herramienta escribe el output de read_file() (que prependea números de línea) de vuelta al archivo. Síntomas: números como texto visible en la página, CSS roto (números dentro de <style>), contenido renderizado con basura. Detección: grep -cP '^\s*\d+\|' *.html | grep -:0$ — si algún archivo tiene matches, está corrompido. Corrección: re.sub(r'^\s*\d+\|', '', content, flags=re.MULTILINE) para eliminar todos los prefijos. Prioridad: ❌ Crítico — el archivo se ve completamente roto. Ver references/line-number-corruption-fix.md para patrón de detección y corrección.
• 🔴 write_file DOBLE-ESCAPA BACKSLASHES EN REGEX — Cuando write_file escribe código que contiene patrones regex como new RegExp('[\\s\\S]*?') o /\\d+/g, el tool puede duplicar los backslashes (escritura: [\\s\\S] → archivo: [\\\\s\\\\S]). El regex queda roto silenciosamente — el código pasa node --check pero no funciona en runtime. Detección: grep -n '\\\\\\\\' file.js — si hay resultados sospechosos, hay doble-escape. Prevención: Usar indexOf/substring en vez de regex para patrones simples (limpiar tags, extraer JSON). Si se necesita regex, verificar el contenido real con cat -n file | grep 'pattern' tras escribir. Trampa: read_file de Hermes también puede mostrar doble-escape — usar terminal("cat -n file") para verificar el contenido real del archivo. Ver pdf-to-landing/references/server-2-endpoint-pattern.md para ejemplo completo.
• 🔴 write_file CORROMPE CONTENIDO COMPLEJO (NO solo prefijos de línea) — Cuando se usa read_file dentro de execute_code para leer HTML/JS y luego write_file para escribir de vuelta (incluso después de procesar), el contenido puede corromperse: strings truncados, secuencias de escape rotas, caracteres UTF-8 mangled. Esto ES DIFERENTE al pitfall de prefijos N| — aquí el problema es que write_file dentro de execute_code puede truncar o corromper datos dentro de strings JavaScript complejos (arrays de objetos, datos con caracteres especiales). Síntomas: SyntaxError: Invalid or unexpected token en Node.js, navegador no ejecuta inline scripts, datos de referencia (como _contractTypes) truncados. Detección: node --check falla. Corrección: Restaurar desde el último commit funcional (git show COMMIT:index.html). Prevención: NUNCA usar write_file para reescribir archivos completos con contenido JS/CSS complejo extraído de read_file dentro de execute_code. Usar patch con old_string/new_string para ediciones específicas. Ver references/write-file-corruption-pattern.md para el caso completo.
• 🔴 BATCH FIX SOBRESCRIBE CORRECCIONES ANTERIORES — Si haces múltiples fases de corrección (ej: Fase 2 añade transiciones, Fase 5 reconstruye navegación), la Fase 5 puede sobrescribir lo que hiciste en Fase 2. SOLUCIÓN: Al hacer batch-fix de navegación, PRESERVAR los enlaces de transición entre niveles que ya existían. Marcarlos antes del batch y re-insertarlos después. Verificar con test específico post-fix.
• 🔴 FÓRMULAS KATEX COMO TEXTO PLANO — Las fórmulas pueden estar escritas como texto (R², {(1,0), (0,1)}) en lugar de KaTeX ($R^2$, $\\{(1,0), (0,1)\\}$). El CDN de KaTeX puede estar cargado pero las fórmulas no se renderizan porque no tienen delimitadores $. SIEMPRE verificar: (1) KaTeX CDN presente, (2) script auto-render con delimiters, (3) fórmulas envueltas en $...$ o $$...$$. Detectar con: re.findall(r'(?<!\\$)R[²³](?!\\$)', content).