Sincronizar documentación

¿Qué hace Sincronizar documentación?

La documentación se desvía silenciosamente. Nada falla cuando un README nombra un archivo que se movió. Ejecuta esto después de cada fase de PR apilada o característica completada, antes de que se abra el PR.

El contrato de esta habilidad incluye confirmar cambios. Puede confirmar sin preguntar, siempre en la rama actual, nunca main.

Cuándo saltar

• Nada de lo que un documento referencia ha cambiado (lógica interna pura). Aun así, escribe "documentación revisada, sin desviación" en la sección de Pruebas del PR, para que el revisor sepa que se ejecutó.
• El usuario explícitamente no quiere una confirmación de documentación todavía.

El inventario: docs/DOCS.md

La lista de documentos dentro del ámbito vive en docs/DOCS.md, no en AGENTS.md, para que el contexto siempre activo no crezca con cada sincronización.

# Inventario de documentación

| Ruta | Propósito | Generado por |
|---|---|---|
| README.md | Propuesta, configuración, variables de entorno, diseño | |
| AGENTS.md | Reglas del agente + compuertas del proyecto | |
| packages/api/README.md | Endpoints, scripts, variables de entorno | |
| docs/api/openapi.json | Referencia de API | `pnpm generate:openapi` |

## Congelado (nunca editado por una sincronización)
- docs/plans/

## Verificaciones de desviación
<!-- un grep por cada error que realmente haya ocurrido, con un comentario explicando por qué -->

Primera ejecución: constrúyelo. Busca README.md / AGENTS.md / CLAUDE.md raíz y por paquete, documentos de colaboradores, documentación de API (descripciones OpenAPI, llms.txt), directorios de habilidades y reglas, y referencias a variables de entorno (.env.example, esquemas de configuración). Anota qué posee cada uno.

Cada ejecución: un documento que encuentres y que no esté listado se añade, en la misma confirmación.

Procedimiento

1. Auditar. Compara la rama con su base (git diff <base>...HEAD --stat), y enumera lo que cambió que un documento podría mencionar: rutas, nombres de paquetes, rutas de API, comandos y scripts, variables de entorno, APIs exportadas, comportamiento, convenciones.
2. Verificar. Para cada documento en el inventario, comprueba cada afirmación concreta contra el código: cada archivo nombrado existe en esa ruta, cada comando existe en el manifiesto, cada variable de entorno se lee realmente, cada ruta y exportación existe como se describe. Lee el código; no confíes en la prosa, incluida la prosa que escribiste antes.
3. Editar. Corrige la desviación. Describe lo que hace el código y nunca inventes comportamiento para que un documento se lea mejor. Si el código y el documento discrepan y no puedes determinar cuál está mal, márcalo en lugar de adivinar.
4. Regenerar. Ejecuta cada comando de generación listado en el inventario. Nunca edites manualmente un documento generado.
5. Ejecutar las verificaciones de desviación listadas en docs/DOCS.md. Cuando una sincronización encuentre un error que probablemente se repita (una ruta antigua, un comando renombrado), añade un grep para él con un comentario explicando por qué.
6. Confirmar. Prepara los archivos por ruta, nunca git add -A. Haz una confirmación atómica, docs(<ámbito>): sincronizar <qué> con <cambio>, en la rama actual.
7. Subir si la rama ya tiene un remoto (git pull --rebase primero). Nunca subas a main.

Reglas

• Historial congelado: los diseños, planes y traspasos en docs/plans/ son instantáneas de lo que se decidió en ese momento. Aparecerán en los greps; eso es esperado, no es desviación. Nunca los edites en una sincronización.
• Los spikes y prototipos se eliminan una vez que su dirección se envía o se descarta, no se mantienen como referencia. Las conclusiones de un spike son el texto menos fiable del repositorio una vez que la producción sabe más. Cualquier cosa que aún valga la pena saber se mueve a la documentación del código enviado.
• Presupuesto de tamaño: las líneas de documentación cuentan para el presupuesto del PR. Si la sincronización empuja una fase más allá de las 500 líneas, entrégala como una fase solo de documentación encima de la pila (consulta stacked-prs).
• Los archivos puntero se mantienen pequeños. Un CLAUDE.md o GEMINI.md que solo apunta a AGENTS.md debe mantenerse así. No copies contenido en él.