lint de documentación
Se ejecuta justo antes de poner el despliegue en lote. Solo revisa lo que la validación estructural (pnpm docs:validate) no atrapa.
Ejecutar con el modelo más potente. La capacidad de encontrar reglas y la capacidad de seguir reglas son diferentes.
Alcance de lectura
No se lee todo. Leer demasiado añade documentos que interfieren y reduce la precisión.
- Obtener las rutas de código involucradas en este despliegue usando
pnpm docs:related <ruta…>para obtener los documentos enrutados. - Los ADR enlazados desde esos documentos y los planes activos de esa área.
- Documentos permanentes para los cuales
pnpm docs:validateadvirtió que su verificación excede los 90 días. - Elementos abiertos en
docs/findings.md.
Qué se revisa
- Discrepancias bidireccionales entre documento y código. Se revisan por separado las omisiones (presentes en el código pero no en la documentación) y las alucinaciones (presentes en la documentación pero no en el código). Revisar solo un lado hace perder la mitad.
- Candidatos a contradicción en ADR. Dos ADR Aceptados de la misma área que llegan a conclusiones opuestas sin relación de reemplazo. Se verifica la cadena de reemplazo con
pnpm docs:links <ADR>. - Tablas de valores duplicados del código. ¿La documentación ha copiado valores o listas que se pueden leer directamente del código?
- Planes pendientes con más de 90 días. Se plantea como un elemento que pregunta si cerrarlo o reanudarlo.
- ADR Propuestos con más de 14 días. La decisión está retrasada.
- Registros de experiencia mezclados en guías. Elementos del tipo «lo intenté pero no funcionó» deben ir a
docs/flows/. - Filas caducadas en
docs/operations/current-state.md. Líneas con fecha de verificación antigua no son un éxito, sino una falta de verificación.
Resultado
Se añaden elementos a docs/findings.md. Cada elemento tiene cinco líneas.
- Hallazgo 2026-09-04 · docs/policies/xxx.md
Afirmación: (qué dice el documento)
Evidencia: (ruta de código o número de ADR)
Propuesta: (qué se debe hacer)
Alcance: (si se corrige en este despliegue o se aplaza)
No se corrige. La resolución la hará el PR que realice ese trabajo, y ese PR eliminará el elemento.
Se actualiza la fecha de verificación de los documentos permanentes leídos a la fecha de hoy. Solo se actualizan los documentos que realmente se contrastaron con el código. Poner la fecha de hoy en un documento no contrastado da una señal falsa de que está actualizado.
Presupuesto
Se asume que uno de cada tres hallazgos será un falso positivo y se comienza con esa premisa. La precisión de la detección de inconsistencias por parte de un LLM por sí solo ronda el 0,6. Si no hay certeza, se anota así en el elemento.
En la primera línea del informe se escribe «número de hallazgos abiertos y antigüedad del elemento más antiguo».
Al añadir o eliminar reglas
Para añadir un elemento a esta lista se debe presentar un caso real que ese elemento haya atrapado. No se añaden elementos sin fundamento. Si un mismo fallo no ha ocurrido en 12 meses y pnpm docs:harness-eval no muestra que sea útil, se elimina.