e56e927a4d
Cambios incluidos: - INDICE-DIRECTIVAS-WORKSPACE.yml actualizado - Perfiles de agentes: PERFIL-ML.md, PERFIL-SECURITY.md - Directivas SIMCO actualizadas: - SIMCO-ASIGNACION-PERFILES.md - SIMCO-CCA-SUBAGENTE.md - SIMCO-CONTEXT-ENGINEERING.md - SIMCO-CONTEXT-RESOLUTION.md - SIMCO-DELEGACION-PARALELA.md - Inventarios actualizados: DEVENV-MASTER, DEVENV-PORTS - Documentos de analisis agregados: - Analisis y planes de fix student portal - Analisis scripts BD - Analisis achievements, duplicados, gamification - Auditoria documentacion gamilit - Backlog discrepancias NEXUS - Planes maestros de resolucion - Reportes de ejecucion agregados - Knowledge base gamilit README actualizado - Referencia submodulo gamilit actualizada (commit beb94f7) Validaciones: - Plan validado contra directivas SIMCO-GIT - Dependencias verificadas - Build gamilit: EXITOSO
388 lines
18 KiB
Markdown
388 lines
18 KiB
Markdown
# 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
|