# DIRECTIVA: DOCUMENTACION DEFINITIVA **Version:** 1.0.0 **Fecha:** 2025-12-18 **Nivel:** CORE **Tipo:** Directiva Fundamental - OBLIGATORIA **Alias:** @DOC-DEFINITIVA **Aplica a:** TODOS los agentes y subagentes en TODOS los niveles --- ## DECLARACION DE LA DIRECTIVA ``` +==============================================================================+ | | | LA DOCUMENTACION ES EL ESTADO FINAL DEL SISTEMA | | | | "docs/ refleja SIEMPRE el estado actual, nunca el historico." | | "Si algo cambio, la documentacion refleja el RESULTADO, no el cambio." | | "Los cambios, correcciones e historicos van en orchestration/." | | | +==============================================================================+ ``` --- ## PRINCIPIO FUNDAMENTAL ### La Documentacion como Espejo del Sistema ```yaml Principio: docs/: - Contiene SOLO estado actual y definitivo - Es un "espejo" de lo que existe implementado - NO contiene historico de cambios - NO contiene correcciones pendientes - NO contiene discrepancias o gaps orchestration/: - Contiene planes, analisis, correcciones - Contiene historico de cambios - Contiene reportes de implementacion - Contiene trazas de tareas - Contiene documentacion de proceso Razon: - Onboarding rapido (docs/ = estado actual) - Sin confusion entre "lo que es" vs "lo que fue" - SSOT (Single Source of Truth) para el estado del sistema ``` --- ## ESTRUCTURA DE DOCUMENTACION (Patron Universal) ### docs/ - Estado Definitivo ``` docs/ ├── 00-vision-general/ # Vision y proposito (definitivo) │ └── directivas/ # Directivas especificas del proyecto ├── 01-fase-*/ # Especificaciones por fase (definitivo) ├── 90-transversal/ # Documentacion cross-cutting (definitivo) │ ├── arquitectura/ # Arquitectura actual │ ├── features/ # Features implementadas │ └── correcciones/ # SOLO backlog activo ├── 95-guias-desarrollo/ # Guias de desarrollo (definitivo) ├── 96-quick-reference/ # Referencias rapidas (definitivo) └── 97-adr/ # Decisiones arquitectonicas (definitivo) ``` ### orchestration/ - Proceso y Cambios ``` orchestration/ ├── 00-guidelines/ # Contexto del proyecto │ ├── CONTEXTO-PROYECTO.md │ ├── HERENCIA-SIMCO.md │ └── HERENCIA-DIRECTIVAS.md ├── inventarios/ # SSOT de componentes ├── reportes/ # Historico de cambios │ ├── historicos/ # Reportes por fecha │ ├── correcciones/ # Correcciones aplicadas │ ├── implementacion/ # Reportes de desarrollo │ └── gaps/ # Gaps identificados/cerrados ├── trazas/ # Trazas de tareas ├── analisis/ # Analisis y planes └── directivas/ # Directivas de proceso (opcionales) ``` --- ## REGLAS DE ACTUALIZACION ### Al Completar una Tarea (Fase D de CAPVED) ```yaml Actualizacion_Obligatoria: Durante_Ejecucion: # Cuando implementas un cambio: - Actualizar documentacion en docs/ como estado FINAL - NO escribir "se corrigio X" o "se cambio de Y a Z" - SI escribir el estado actual resultante Al_Finalizar: # Cuando terminas la tarea: - Verificar que docs/ refleja estado actual - Generar reporte en orchestration/reportes/ con historico - Actualizar inventarios con metricas actuales ``` ### Ejemplo de Actualizacion Correcta ```yaml Situacion: "Se corrigio el numero de schemas de 14 a 16" INCORRECTO_en_docs/: texto: "Actualizado: Antes habia 14 schemas, ahora hay 16" razon: "Esto es historico, no estado actual" CORRECTO_en_docs/: texto: "Total schemas: 16" razon: "Solo estado actual, sin referencia a lo anterior" CORRECTO_en_orchestration/: archivo: "orchestration/reportes/correcciones/CORRECCION-{fecha}.md" contenido: | ## Correccion de Metricas - Antes: 14 schemas - Despues: 16 schemas - Archivos actualizados: [lista] ``` --- ## SEPARACION DE CONTENIDO ### Que VA en docs/ ```yaml Contenido_Definitivo: - Especificaciones tecnicas actuales - Arquitectura actual del sistema - Guias de desarrollo vigentes - Referencias rapidas actualizadas - ADRs (decisiones arquitectonicas) - Features implementadas (estado actual) - Backlog activo (issues pendientes) - Directivas especificas del proyecto Formato: - Siempre en presente o futuro - Sin referencias a "antes" o "se cambio" - Metricas siempre actuales - Fechas de ultima actualizacion (no de creacion) ``` ### Que VA en orchestration/ ```yaml Contenido_de_Proceso: - Planes de implementacion - Reportes de analisis - Historico de correcciones - Trazas de tareas completadas - Reportes por fecha - Gaps identificados y cerrados - Lecciones aprendidas - Contexto y herencia del proyecto Formato: - Puede incluir "antes/despues" - Incluye fechas de ejecucion - Incluye contexto de cambios - Incluye metricas historicas ``` --- ## SSOT (Single Source of Truth) ### Inventarios como SSOT ```yaml SSOT_para_Metricas: archivo: "orchestration/inventarios/MASTER_INVENTORY.yml" contiene: - Metricas de database (schemas, tablas, etc.) - Metricas de backend (modulos, endpoints, etc.) - Metricas de frontend (componentes, hooks, etc.) Regla: - TODA documentacion que cite metricas debe referenciar este archivo - O debe ser actualizada cuando este archivo cambie - NO duplicar valores, referenciar SSOT ``` ### Actualizacion de Referencias ```yaml Cuando_cambia_SSOT: 1. Actualizar MASTER_INVENTORY.yml 2. Actualizar docs/ que citan las metricas 3. Generar reporte en orchestration/reportes/ Archivos_tipicos_que_citan_metricas: - docs/README.md - docs/95-guias-desarrollo/README.md - docs/96-quick-reference/*.md - orchestration/00-guidelines/CONTEXTO-PROYECTO.md ``` --- ## TRAZABILIDAD DE DOCUMENTACION DEPRECADA ### Cuando se Mueve Documentacion ```yaml Proceso: 1. Mover archivo de docs/ a orchestration/reportes/ 2. Registrar en TRAZA-DOCUMENTACION-DEPRECADA.md 3. Actualizar referencias en documentos vigentes 4. Actualizar _MAP.md correspondiente Archivo_de_Traza: ubicacion: "orchestration/trazas/TRAZA-DOCUMENTACION-DEPRECADA.md" contenido: - Ubicacion original - Nueva ubicacion - Fecha de movimiento - Razon del movimiento - Referencias actualizadas ``` --- ## CHECKLIST DE DOCUMENTACION ### Al Finalizar Cada Tarea ``` DOCUMENTACION DEFINITIVA (docs/) [ ] docs/ refleja estado actual (no historico) [ ] Metricas estan actualizadas [ ] No hay referencias a "antes" o "se cambio" [ ] Fechas de ultima actualizacion correctas DOCUMENTACION DE PROCESO (orchestration/) [ ] Reporte de tarea en orchestration/reportes/ [ ] Traza actualizada si aplica [ ] Inventarios actualizados [ ] Historico documentado TRAZABILIDAD [ ] MASTER_INVENTORY.yml actualizado [ ] Referencias cruzadas actualizadas [ ] Sin enlaces rotos ``` --- ## INTEGRACION CON CAPVED Esta directiva se ejecuta principalmente en la **Fase D (Documentacion)** del ciclo CAPVED: ```yaml Fase_D_Documentacion: durante: - Actualizar docs/ como estado FINAL - NO escribir historico de cambios despues: - Generar reporte en orchestration/reportes/ - Actualizar inventarios - Registrar traza si aplica ``` --- ## APLICACION POR NIVEL Esta directiva aplica a TODOS los niveles del workspace: | Nivel | Ubicacion docs/ | Ubicacion orchestration/ | |-------|-----------------|--------------------------| | WORKSPACE | N/A | workspace/orchestration/ | | CORE | N/A | core/orchestration/ | | STANDALONE | projects/{p}/docs/ | projects/{p}/orchestration/ | | SUITE | projects/{s}/docs/ | projects/{s}/orchestration/ | | VERTICAL | .../verticales/{v}/docs/ | .../verticales/{v}/orchestration/ | --- ## REFERENCIAS | Documento | Alias | Proposito | |-----------|-------|-----------| | PRINCIPIO-DOC-PRIMERO.md | @DOC-PRIMERO | Documentar antes de implementar | | PRINCIPIO-CAPVED.md | @CAPVED | Ciclo de vida de tareas | | SIMCO-DOCUMENTAR.md | @DOCUMENTAR | Proceso detallado de documentacion | | INDICE-DIRECTIVAS-WORKSPACE.yml | @INDICE | Indice maestro de directivas | --- **Esta directiva es OBLIGATORIA y define como documentar el sistema en TODOS los niveles.** --- **Version:** 1.0.0 | **Nivel:** CORE | **Sistema:** SIMCO v2.3.0