Mantenimiento de la documentación
Responsabilidad y momento de actualización
La persona que modifica una función debe incluir sus documentos en el mismo Pull Request. El revisor del dominio comprueba la correspondencia con código, pruebas y controles visibles.
| Cambio | Actualización requerida |
|---|---|
| Nueva capacidad o límite de disponibilidad | product/features.md, reference/feature-status.md y guía de tarea |
| Cambio de interfaz o etiqueta | Guía correspondiente en builder/ o guides/; verificar la etiqueta literal en TSX |
| Cambio de API, esquema o herramienta MCP | Referencia MCP, ejemplos, datos y autenticación según corresponda |
| Cambio de instalación o variables | developer/ y .env.example solo mediante una tarea de implementación autorizada |
| Cambio de rutas, despliegue o dependencias | architecture/ y operations/ |
| Cambio incompatible | CHANGELOG.md: antes/después, afectados, migración respaldada y límites |
| Cambio de propuesta, estructura o comandos principales | README.md |
Añadir una función documentada
- Identifica archivos, contratos y pruebas que la implementan.
- Clasifica su estado: Implementada, Parcialmente implementada, Experimental, Planificada o No verificada.
- Describe propósito, ubicación exacta, requisitos, pasos, parámetros, resultado y límites. No uses un mock como prueba de una integración externa.
- Añade enlaces relativos a fuentes y referencias cruzadas al índice.
- Ejecuta validación de enlaces y verifica los ejemplos contra el esquema actual.
- Registra la comprobación efectuada y lo que no se pudo ejecutar.
Lista para revisar un Pull Request
- La documentación describe la rama objetivo y distingue trabajo pendiente de producción.
- Cada capacidad importante tiene una fuente o prueba identificable.
- Los nombres de controles, campos y herramientas son exactos.
- Los comandos existen y los efectos de escritura/despliegue están identificados.
- No hay credenciales, valores secretos ni capturas con datos personales.
- Enlaces relativos, anclas y diagramas siguen siendo válidos.
- Guías, estado, arquitectura y cambios no se contradicen.
- Se actualizó el índice y se preservó información técnica válida.
Revisiones periódicas
Revisar tras cambios relevantes y antes de cada publicación de documentación. En cada revisión registrar commit, fecha y área. Mantener español como fuente inicial; una futura traducción puede usar docs/es/ y docs/en/ con equivalencias explícitas, sin duplicar hoy contenido no mantenido.
Los planes y auditorías fechadas deben conservar su contexto; si contradicen el producto actual, añade una nota histórica y enlaza la referencia vigente. No presentes una prueba antigua como ejecutada nuevamente.
Automatizaciones propuestas
No se modifica CI en esta entrega. Puede añadirse más adelante un job documental sin credenciales ni despliegue que:
- Valide destinos locales y anclas de Markdown.
- Compare comandos documentados con
scriptsde cadapackage.json. - Compare herramientas publicadas con el registro y operaciones MCP.
- Detecte patrones de secretos en el diff sin imprimir valores.
- Compile diagramas Mermaid y compruebe jerarquías y texto alternativo.
Ese job debe tratar enlaces externos separadamente: redirecciones, restricciones de red y autenticación no son necesariamente errores de documentación. La revisión humana sigue siendo necesaria para exactitud de funciones y limitaciones.