# 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
