# PLAN MAESTRO: Auditoría y Reestructuración de Documentación - Gamilit

**Fecha:** 2026-01-10
**Perfil Responsable:** Arquitecto de Documentación y Orquestador de Calidad
**Estado:** FASE INICIAL - PLANEACIÓN

---

## 1. RESUMEN EJECUTIVO

### 1.1 Objetivo
Realizar una auditoría completa y reestructuración de toda la documentación del proyecto Gamilit para:
- Eliminar duplicados y documentación obsoleta
- Consolidar definiciones actuales
- Crear trazabilidad correcta entre funcionalidades
- Mantener un histórico resumido de la evolución del proyecto
- Homologar documentación con el estado actual del desarrollo

### 1.2 Alcance
| Ubicación | Archivos | Tipo |
|-----------|----------|------|
| `/projects/gamilit/.claude/` | 44 | Sistema NEXUS interno |
| `/orchestration/analisis/` | 63+ | Análisis y planes de gamilit |
| `/orchestration/reportes/` | 25+ | Reportes de ejecución |
| `/shared/knowledge-base/projects/gamilit/` | 1 | Knowledge base |
| `/orchestration/directivas/` | 47 | Directivas SIMCO + Principios |

**Total estimado:** ~180 archivos a auditar

### 1.3 Entregables Finales
1. **CATALOGO-DOCUMENTACION-VIGENTE.md** - Único catálogo de documentación activa
2. **HISTORICO-EVOLUCIONES-GAMILIT.md** - Histórico resumido de cambios
3. **MATRIZ-TRAZABILIDAD-FUNCIONALIDADES.yml** - Mapeo funcionalidades ↔ documentación
4. **REGISTRO-DUPLICADOS-OBSOLETOS.md** - Registro de elementos eliminados/consolidados
5. **Documentación reestructurada** - Archivos actualizados y organizados

---

## 2. METODOLOGÍA DE TRABAJO

### 2.1 Principio Rector
```
CAPVED: Contexto → Análisis → Planeación → Validación → Ejecución → Documentación
```

### 2.2 Fases del Proceso (Por cada Módulo/Funcionalidad)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ FASE 1: ANÁLISIS INICIAL Y PLANEACIÓN                                      │
│   └─ Identificar documentos relacionados con el módulo                     │
│   └─ Clasificar: Vigente | Obsoleto | Duplicado | Parcialmente actualizado │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 2: ANÁLISIS DETALLADO                                                 │
│   └─ Leer contenido completo de cada documento                             │
│   └─ Extraer definiciones, especificaciones, reglas de negocio             │
│   └─ Identificar dependencias con otros módulos                            │
│   └─ Detectar inconsistencias y conflictos                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 3: PLANEACIÓN DETALLADA                                               │
│   └─ Definir acciones: Mantener | Actualizar | Consolidar | Eliminar       │
│   └─ Especificar cambios exactos por archivo                               │
│   └─ Mapear impacto en dependencias                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 4: VALIDACIÓN DEL PLAN                                                │
│   └─ Verificar coherencia con estado actual del código                     │
│   └─ Validar que no se pierda información crítica                          │
│   └─ Confirmar que dependencias están contempladas                         │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 5: REFINAMIENTO DEL PLAN                                              │
│   └─ Ajustar basado en hallazgos de validación                             │
│   └─ Priorizar acciones por impacto                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 6: EJECUCIÓN                                                          │
│   └─ Ejecutar cambios archivo por archivo                                  │
│   └─ Documentar cada modificación realizada                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ FASE 7: VALIDACIÓN DE EJECUCIÓN                                            │
│   └─ Verificar integridad de documentos modificados                        │
│   └─ Confirmar trazabilidad correcta                                       │
│   └─ Validar contra requisitos iniciales                                   │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 3. SEGMENTACIÓN POR MÓDULOS/FUNCIONALIDADES

### 3.1 Orden de Procesamiento (Por Dependencias)

```
NIVEL 0: FUNDAMENTOS (Sin dependencias)
├── M01: Sistema NEXUS Base
├── M02: Directivas y Principios
└── M03: Perfiles de Agentes

NIVEL 1: INFRAESTRUCTURA (Depende de N0)
├── M04: Database (Esquemas, Tablas, RLS)
├── M05: Backend Core (APIs, Services)
└── M06: Frontend Core (Components, Hooks)

NIVEL 2: FUNCIONALIDADES CORE (Depende de N1)
├── M07: Autenticación y Autorización
├── M08: Gestión de Usuarios (Estudiantes, Profesores, Admin)
├── M09: Cursos y Contenido Académico
└── M10: Evaluaciones y Calificaciones

NIVEL 3: GAMIFICACIÓN (Depende de N2)
├── M11: Puntos y Experiencia
├── M12: Achievements/Logros
├── M13: Leaderboards
├── M14: Rewards/Recompensas
└── M15: Gamification Summary

NIVEL 4: PORTALES (Depende de N2-N3)
├── M16: Student Portal
├── M17: Teacher Portal
├── M18: Admin Portal
└── M19: Parent Portal

NIVEL 5: INTEGRACIONES (Depende de N1-N4)
├── M20: DevOps (Docker, CI/CD)
├── M21: Reportes y Analytics
└── M22: Auditoría y Logging
```

---

## 4. TAREAS DETALLADAS POR MÓDULO

### MÓDULO M01: Sistema NEXUS Base

#### FASE 1: Análisis Inicial
| ID | Tarea | Archivos a Revisar | Criterio de Éxito |
|----|-------|-------------------|-------------------|
| M01-F1-T01 | Identificar todos los archivos del sistema NEXUS | `.claude/README.md`, `.claude/*/_MAP.md` | Lista completa de 44 archivos categorizada |
| M01-F1-T02 | Clasificar estado de cada archivo | Todos en `.claude/` | Cada archivo etiquetado: Vigente/Obsoleto/Duplicado |
| M01-F1-T03 | Mapear estructura jerárquica | Carpetas agents/, directivas/, etc. | Árbol de dependencias documentado |

#### FASE 2: Análisis Detallado
| ID | Tarea | Detalle | Criterio de Éxito |
|----|-------|---------|-------------------|
| M01-F2-T01 | Analizar README.md principal | Extraer: versión, arquitectura, referencias | Resumen de 1 página con hallazgos |
| M01-F2-T02 | Analizar cada perfil de agente | `agents/INIT-NEXUS-*.md` | Tabla comparativa de capacidades y solapamientos |
| M01-F2-T03 | Analizar directivas internas | `directivas/*.md` | Lista de directivas con estado de vigencia |
| M01-F2-T04 | Identificar referencias cruzadas | Todos los archivos | Mapa de dependencias entre documentos |
| M01-F2-T05 | Detectar duplicados internos | Comparar contenidos similares | Lista de candidatos a consolidación |

#### FASE 3: Planeación
| ID | Tarea | Detalle | Entregable |
|----|-------|---------|------------|
| M01-F3-T01 | Definir estructura objetivo | Nueva organización de `.claude/` | Diagrama de estructura propuesta |
| M01-F3-T02 | Planificar consolidaciones | Fusionar duplicados identificados | Plan de consolidación por archivo |
| M01-F3-T03 | Planificar actualizaciones | Archivos desactualizados | Lista de cambios específicos |
| M01-F3-T04 | Planificar eliminaciones | Archivos obsoletos | Lista de archivos a eliminar con justificación |

#### FASE 4: Validación del Plan
| ID | Tarea | Detalle | Criterio de Éxito |
|----|-------|---------|-------------------|
| M01-F4-T01 | Validar contra código actual | Comparar documentación vs implementación | 0 inconsistencias críticas |
| M01-F4-T02 | Validar dependencias | Verificar que no se rompen referencias | Todas las referencias válidas |
| M01-F4-T03 | Review de impacto | Evaluar efecto en otros módulos | Impacto documentado y mitigado |

#### FASE 5: Refinamiento
| ID | Tarea | Detalle | Entregable |
|----|-------|---------|------------|
| M01-F5-T01 | Incorporar feedback de validación | Ajustar plan según hallazgos | Plan refinado v2 |
| M01-F5-T02 | Priorizar acciones | Ordenar por criticidad e impacto | Lista priorizada de acciones |

#### FASE 6: Ejecución
| ID | Tarea | Detalle | Verificación |
|----|-------|---------|--------------|
| M01-F6-T01 | Ejecutar consolidaciones | Fusionar archivos duplicados | Archivos consolidados sin pérdida de info |
| M01-F6-T02 | Ejecutar actualizaciones | Modificar archivos desactualizados | Contenido actualizado y coherente |
| M01-F6-T03 | Ejecutar eliminaciones | Remover archivos obsoletos | Archivos eliminados, sin referencias rotas |
| M01-F6-T04 | Actualizar _MAP.md | Reflejar nueva estructura | _MAP.md actualizado y correcto |

#### FASE 7: Validación de Ejecución
| ID | Tarea | Detalle | Criterio de Éxito |
|----|-------|---------|-------------------|
| M01-F7-T01 | Verificar integridad de archivos | Leer cada archivo modificado | Sin errores de formato o contenido |
| M01-F7-T02 | Verificar referencias cruzadas | Todas las referencias válidas | 0 enlaces rotos |
| M01-F7-T03 | Validar contra requisitos | Comparar resultado vs objetivo | Todos los requisitos cumplidos |

---

### MÓDULO M02: Directivas y Principios (SIMCO)

#### FASE 1: Análisis Inicial
| ID | Tarea | Archivos | Criterio |
|----|-------|----------|----------|
| M02-F1-T01 | Catalogar directivas SIMCO | `/orchestration/directivas/simco/*.md` (41 archivos) | Lista completa con propósito de cada una |
| M02-F1-T02 | Catalogar principios | `/orchestration/directivas/principios/*.md` (6 archivos) | Lista con estado de vigencia |
| M02-F1-T03 | Identificar índice maestro | `INDICE-DIRECTIVAS-WORKSPACE.yml` | Validar coherencia con archivos físicos |
| M02-F1-T04 | Mapear herencia | Directivas gamilit vs workspace | Diagrama de herencia |

#### FASE 2: Análisis Detallado
| ID | Tarea | Detalle | Entregable |
|----|-------|---------|------------|
| M02-F2-T01 | Analizar cada directiva SIMCO | Contenido, versión, aplicabilidad | Matriz de directivas vigentes |
| M02-F2-T02 | Detectar directivas duplicadas | Comparar propósito y contenido | Lista de duplicados candidatos |
| M02-F2-T03 | Identificar directivas obsoletas | Comparar contra práctica actual | Lista de obsoletas con evidencia |
| M02-F2-T04 | Analizar coherencia interna | Reglas contradictorias | Lista de conflictos |
| M02-F2-T05 | Mapear uso real | Qué directivas se aplican efectivamente | Estadísticas de uso |

#### FASE 3-7: [Similar estructura a M01]

---

### MÓDULO M03: Perfiles de Agentes

#### FASE 1: Análisis Inicial
| ID | Tarea | Archivos | Criterio |
|----|-------|----------|----------|
| M03-F1-T01 | Catalogar perfiles completos | `/orchestration/agents/perfiles/*.md` (28 archivos) | Lista con rol de cada perfil |
| M03-F1-T02 | Catalogar perfiles compactos | `/orchestration/agents/perfiles/compact/*.md` (7 archivos) | Mapeo a perfiles completos |
| M03-F1-T03 | Catalogar perfiles NEXUS internos | `.claude/agents/*.md` (12 archivos) | Relación con perfiles de workspace |
| M03-F1-T04 | Identificar aliases | `ALIASES.yml` | Mapeo completo de aliases |

#### FASE 2: Análisis Detallado
| ID | Tarea | Detalle | Entregable |
|----|-------|---------|------------|
| M03-F2-T01 | Analizar solapamiento de perfiles | Capacidades duplicadas entre perfiles | Matriz de solapamiento |
| M03-F2-T02 | Validar coherencia NEXUS vs Workspace | Perfiles gamilit vs generales | Lista de inconsistencias |
| M03-F2-T03 | Identificar perfiles no utilizados | Sin referencias activas | Lista de candidatos a deprecar |
| M03-F2-T04 | Analizar especializaciones | Avanzados vs Base | Recomendación de consolidación |

---

### MÓDULO M04: Database

#### FASE 1: Análisis Inicial
| ID | Tarea | Archivos | Criterio |
|----|-------|----------|----------|
| M04-F1-T01 | Catalogar documentación de BD | Archivos relacionados con database | Lista categorizada |
| M04-F1-T02 | Identificar esquemas documentados | Definiciones de tablas, funciones, triggers | Inventario de objetos |
| M04-F1-T03 | Mapear análisis de BD | Reportes de auditoría, gaps | Lista de análisis existentes |

#### FASE 2: Análisis Detallado
| ID | Tarea | Detalle | Entregable |
|----|-------|---------|------------|
| M04-F2-T01 | Validar documentación vs DDL actual | Comparar docs vs scripts SQL | Lista de discrepancias |
| M04-F2-T02 | Analizar reportes de auditoría | Estado de tablas de auditoría | Resumen consolidado |
| M04-F2-T03 | Identificar duplicados funcionales | Tablas/funciones con mismo propósito | Lista de candidatos a consolidar |
| M04-F2-T04 | Mapear dependencias de esquemas | FK, triggers, funciones | Diagrama de dependencias |

---

### MÓDULOS M05-M22: [Estructura similar adaptada a cada módulo]

---

## 5. CRITERIOS DE CLASIFICACIÓN

### 5.1 Estado de Documentos

| Estado | Código | Descripción | Acción |
|--------|--------|-------------|--------|
| Vigente | VIG | Actualizado y en uso activo | Mantener |
| Desactualizado | DES | Contenido correcto pero no actualizado | Actualizar |
| Obsoleto | OBS | Ya no aplica al proyecto actual | Eliminar o Archivar |
| Duplicado | DUP | Mismo contenido en múltiples archivos | Consolidar |
| Parcial | PAR | Parte vigente, parte obsoleta | Limpiar |
| Conflictivo | CON | Contradice otra documentación | Resolver |

### 5.2 Prioridad de Acción

| Prioridad | Código | Descripción |
|-----------|--------|-------------|
| Crítica | P0 | Bloquea desarrollo o causa errores |
| Alta | P1 | Afecta múltiples módulos |
| Media | P2 | Afecta un solo módulo |
| Baja | P3 | Mejora cosmética o menor |

### 5.3 Tipo de Acción

| Acción | Código | Descripción |
|--------|--------|-------------|
| Mantener | KEEP | Sin cambios necesarios |
| Actualizar | UPD | Modificar contenido |
| Consolidar | CONS | Fusionar con otro archivo |
| Eliminar | DEL | Remover completamente |
| Archivar | ARCH | Mover a histórico |
| Crear | NEW | Nuevo documento necesario |

---

## 6. ENTREGABLES POR FASE DE PROYECTO

### Fase Global 1: Auditoría Completa
- [ ] Inventario completo de documentación
- [ ] Clasificación de cada documento
- [ ] Mapa de dependencias
- [ ] Identificación de duplicados y obsoletos

### Fase Global 2: Planificación de Reestructuración
- [ ] Plan detallado de acciones por módulo
- [ ] Validación del plan
- [ ] Plan refinado aprobado

### Fase Global 3: Ejecución
- [ ] Consolidación de duplicados
- [ ] Actualización de documentos
- [ ] Eliminación/Archivo de obsoletos
- [ ] Creación de nuevos documentos necesarios

### Fase Global 4: Validación Final
- [ ] Verificación de integridad
- [ ] Verificación de trazabilidad
- [ ] Documentación de cambios realizados

---

## 7. PROGRESO Y TRACKING

### Estado Actual por Módulo

| Módulo | Fase 1 | Fase 2 | Fase 3 | Fase 4 | Fase 5 | Fase 6 | Fase 7 |
|--------|--------|--------|--------|--------|--------|--------|--------|
| M01: NEXUS Base | PENDIENTE | - | - | - | - | - | - |
| M02: Directivas | PENDIENTE | - | - | - | - | - | - |
| M03: Perfiles | PENDIENTE | - | - | - | - | - | - |
| M04: Database | PENDIENTE | - | - | - | - | - | - |
| M05-M22 | PENDIENTE | - | - | - | - | - | - |

### Métricas de Progreso

| Métrica | Objetivo | Actual |
|---------|----------|--------|
| Archivos auditados | 180 | 0 |
| Duplicados identificados | - | - |
| Obsoletos identificados | - | - |
| Conflictos resueltos | - | - |
| Archivos consolidados | - | - |

---

## 8. PRÓXIMOS PASOS INMEDIATOS

1. **Iniciar M01: Sistema NEXUS Base**
   - Leer y catalogar los 44 archivos de `.claude/`
   - Crear clasificación inicial

2. **Paralelizar análisis inicial de M02 y M03**
   - Directivas SIMCO (41 archivos)
   - Perfiles de Agentes (47 archivos)

3. **Crear estructura de reportes de auditoría**
   - Plantilla para reporte por módulo
   - Plantilla para tracking de cambios

---

## ANEXOS

### A. Rutas Críticas de Documentación

```
/home/isem/workspace-v1/
├── projects/gamilit/.claude/          # Sistema NEXUS interno (44 archivos)
├── orchestration/
│   ├── analisis/                      # Análisis y planes (63+ archivos)
│   ├── reportes/                      # Reportes de ejecución (25+ archivos)
│   ├── directivas/simco/              # Directivas SIMCO (41 archivos)
│   ├── directivas/principios/         # Principios (6 archivos)
│   ├── agents/perfiles/               # Perfiles de agentes (35 archivos)
│   ├── templates/                     # Plantillas (50+ archivos)
│   └── inventarios/                   # Inventarios (10 archivos)
└── shared/knowledge-base/projects/gamilit/  # Knowledge base (1 archivo)
```

### B. Convenciones de Nomenclatura para Nuevos Archivos

```
FORMATO: [TIPO]-[MODULO]-[DETALLE]-[FECHA].md

Ejemplos:
- AUDITORIA-M01-NEXUS-BASE-2026-01-10.md
- CONSOLIDACION-M02-DIRECTIVAS-2026-01-10.md
- VALIDACION-M04-DATABASE-2026-01-10.md
```

---

**Documento creado:** 2026-01-10
**Próxima revisión:** Al completar Fase 1 de M01
**Responsable:** Arquitecto de Documentación y Orquestador de Calidad