¿Qué hace Validador de Consistencia de Contenido?
Resumen
Verifica la consistencia de contenido en tono, terminología, formato y estructura entre múltiples fuentes de documentación (sitios web, repositorios de GitHub, documentos locales). Genera informes de discrepancia de solo lectura con hallazgos clasificados por gravedad y sugerencias de corrección procesables, incluyendo rutas de archivo y números de línea.
Ejemplos
- Auditoría previa al lanzamiento: Antes de etiquetar una nueva versión, ejecuta el validador para detectar discrepancias de versión entre tu README, sitio de documentación y changelog — por ejemplo, el sitio web dice v2.1.0 pero el README de GitHub aún referencia v2.0.0.
- Verificación posterior a un cambio de marca: Después de renombrar un producto o actualizar terminología (por ejemplo, de "plugin" a "extensión"), valida que toda la documentación, páginas de aterrizaje y guías de contribución usen el nuevo término de manera consistente.
- Revisión de incorporación: Cuando un nuevo colaborador señala documentación confusa, ejecuta una verificación de consistencia para detectar afirmaciones contradictorias sobre funciones, información de contacto desactualizada o secciones faltantes en tus fuentes de documentación.
Requisitos previos
- Acceso al menos a dos fuentes de contenido (sitio web, repositorio de GitHub o directorio de documentos locales)
- Permisos de WebFetch configurados para URLs remotas (sitios desplegados, contenido raw de GitHub)
- Documentación local almacenada en rutas reconocibles (
docs/,claudes-docs/,internal/)
Instrucciones
- Descubrir fuentes — escanea directorios de compilación (
dist/,build/,public/,out/,_site/), archivos README/CONTRIBUTING de GitHub y carpetas de documentación local:find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - Extraer datos estructurados de cada fuente: números de versión, afirmaciones sobre funciones, nombres de productos, lemas, información de contacto, URLs y requisitos técnicos:
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - Verificar la extracción — confirma al menos 3 puntos de datos por fuente. Si una fuente devuelve vacío, revisa la tabla de Manejo de Errores antes de continuar.
- Construir matriz de comparación emparejando cada fuente contra todas las demás (sitio web vs GitHub, sitio web vs documentación local, GitHub vs documentación local):
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - Clasificar discrepancias por gravedad:
- Crítico: números de versión contradictorios, listas de funciones contradictorias, información de contacto no coincidente, referencias cruzadas rotas
- Advertencia: terminología inconsistente (por ejemplo, "plugin" vs "extensión"), información faltante en una fuente, fechas desactualizadas
- Informativo: diferencias estilísticas, redacción específica de la plataforma, niveles de detalle diferentes
- Aplicar prioridad de confianza: sitio web (más autorizado) > GitHub (orientado a desarrolladores) > documentación local (uso interno).
- Generar informe en Markdown con: resumen ejecutivo, tablas de comparación por pares, matriz de consistencia de terminología y elementos de acción priorizados con rutas de archivo y números de línea.
- Guardar en
consistency-reports/YYYY-MM-DD-HH-MM-SS.md.
Formato del Informe
# Informe de Consistencia — YYYY-MM-DD
## Resumen Ejecutivo
| Gravedad | Conteo |
|----------|--------|
| Crítico | 2 |
| Advertencia | 5 |
| Info | 3 |
## Sitio Web vs GitHub
| Campo | Sitio Web | GitHub | Gravedad |
|-------------|---------------|---------------|------------|
| Versión | v2.1.0 | v2.0.0 | Crítico |
| Función X | listada | faltante | Advertencia|
## Elementos de Acción
1. **Crítico** — Actualizar `README.md:14` versión de v2.0.0 → v2.1.0
2. **Advertencia** — Agregar "Función X" a la lista de funciones de `README.md`
Manejo de Errores
| Error | Causa | Solución |
|---|---|---|
| Contenido del sitio web inalcanzable | La URL devuelve 4xx/5xx o falta el directorio de compilación | Verifica que el sitio esté desplegado o ejecuta una compilación local; revisa los permisos de WebFetch |
| Límite de tasa de la API de GitHub | Demasiadas solicitudes en poco tiempo | Pausa y reintenta después del reinicio de la ventana; usa solicitudes autenticadas |
| Ningún directorio de documentación | Las rutas esperadas no existen | Confirma el directorio de trabajo; especifica la ruta de documentación explícitamente |
| Extracción de contenido vacía | Renderizado del lado del cliente no visible para la solicitud | Usa el directorio de compilación local en lugar de la URL en vivo |
| Fallo del comando diff | Las rutas de archivo contienen caracteres especiales | Pon entre comillas todas las rutas de archivo pasadas a diff y grep |
Recursos
- Lógica de descubrimiento de fuentes de contenido:
${CLAUDE_SKILL_DIR}/references/how-it-works.md - Prioridad de confianza y tiempo de validación:
${CLAUDE_SKILL_DIR}/references/best-practices.md - Ejemplos de casos de uso:
${CLAUDE_SKILL_DIR}/references/example-use-cases.md