workspace/core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-DEFINITIVA.md

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

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)

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

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/

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/

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

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

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

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:

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