From 6692eca99ec0336ec63311d90c34312c9d24f00c Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sat, 10 Jan 2026 09:01:33 -0600 Subject: [PATCH] [SIMCO-V38] docs: Agregar ejecucion piloto y guia de uso - Ejecutar checklist piloto @CHK_MANTENIMIENTO en workspace - Crear guia de uso SIMCO v3.8.0 en shared/knowledge-base/ Co-Authored-By: Claude Opus 4.5 --- ...ION-PILOTO-CHK-MANTENIMIENTO-2026-01-10.md | 190 +++++++++++++++ .../standards/GUIA-SIMCO-V38-DOCUMENTACION.md | 216 ++++++++++++++++++ 2 files changed, 406 insertions(+) create mode 100644 orchestration/trazas/EJECUCION-PILOTO-CHK-MANTENIMIENTO-2026-01-10.md create mode 100644 shared/knowledge-base/standards/GUIA-SIMCO-V38-DOCUMENTACION.md diff --git a/orchestration/trazas/EJECUCION-PILOTO-CHK-MANTENIMIENTO-2026-01-10.md b/orchestration/trazas/EJECUCION-PILOTO-CHK-MANTENIMIENTO-2026-01-10.md new file mode 100644 index 000000000..0cd18347b --- /dev/null +++ b/orchestration/trazas/EJECUCION-PILOTO-CHK-MANTENIMIENTO-2026-01-10.md @@ -0,0 +1,190 @@ +# EJECUCION PILOTO: Checklist de Mantenimiento de Documentacion + +**Fecha:** 2026-01-10 +**Ejecutado por:** Claude Opus 4.5 +**Proyecto:** workspace-v1 (nivel workspace) +**Tarea/Fase:** Implementacion SIMCO v3.8.0 +**Checklist:** @CHK_MANTENIMIENTO + +--- + +## 1. IDENTIFICACION (10 items) + +- [x] 1.1 Listar todos los documentos modificados en la tarea + - 9 directivas SIMCO nuevas + - 4 templates nuevos + - 6 checklists nuevos (5 + _MAP) + - 1 perfil de agente nuevo + - INDICE-DIRECTIVAS-WORKSPACE.yml actualizado + - _INDEX.md y _MAP.md actualizados +- [x] 1.2 Listar documentos con dependencia directa + - 16 archivos HERENCIA-SIMCO.md en proyectos (actualizados) +- [x] 1.3 Listar documentos dependientes + - ALIASES.yml (referencias a nuevas directivas) +- [x] 1.4 Identificar documentos con >3 meses sin actualizar + - N/A - todos los documentos modificados son nuevos +- [x] 1.5 Verificar frontmatter YAML de cada documento modificado + - Todos tienen frontmatter correcto +- [x] 1.6 Identificar secciones potencialmente obsoletas + - N/A - documentos nuevos +- [x] 1.7 Revisar referencias cruzadas en documentos afectados + - Referencias cruzadas entre directivas validadas +- [x] 1.8 Listar inventarios que deben actualizarse + - N/A - no aplica a nivel workspace +- [x] 1.9 Identificar scripts de BD afectados + - N/A - no hay cambios de BD +- [x] 1.10 Documentar alcance total del mantenimiento + - Documentado en ANALISIS-ESTADO-PROPAGACION-SIMCO-V38-CONTINUACION-2026-01-10.md + +**Resultado Seccion 1:** 10/10 completados + +--- + +## 2. SINCRONIZACION (15 items) + +### Specs vs Codigo +- [N/A] 2.1-2.4 No aplica - son directivas de orquestacion, no specs tecnicos + +### Backend +- [N/A] 2.5-2.7 No aplica - cambios a nivel de documentacion de orquestacion + +### Frontend +- [N/A] 2.8-2.9 No aplica + +### Inventarios +- [N/A] 2.10-2.13 No aplica a nivel workspace + +### Indices +- [x] 2.14 Todos los _MAP.md actualizados + - checklists/_MAP.md: ACTUALIZADO (v3.8.0, 10 checklists) + - templates/_MAP.md: ACTUALIZADO (v3.8.0, 28 templates) +- [x] 2.15 Fechas `updated_date` actualizadas + - INDICE-DIRECTIVAS-WORKSPACE.yml: 2026-01-10 + +**Resultado Seccion 2:** 2/2 aplicables completados, 13 N/A + +--- + +## 3. VALIDACION DE DEPENDENCIAS (15 items) + +### Dependencias Verticales +- [x] 3.1-3.3 Jerarquia workspace → proyectos consistente via HERENCIA-SIMCO.md + +### Dependencias Horizontales +- [N/A] 3.4-3.6 No aplica - no hay cambios DDL/Entity/API +- [x] 3.7 Docs consistentes con estructura de orquestacion + +### Referencias +- [x] 3.8 Links internos funcionan (alias verificados) +- [x] 3.9 Referencias a archivos correctas +- [x] 3.10 No hay referencias a docs eliminados +- [x] 3.11 No hay referencias a codigo eliminado + +### Validaciones Tecnicas +- [N/A] 3.12-3.15 No aplica - solo documentacion de orquestacion + +**Resultado Seccion 3:** 6/6 aplicables completados, 9 N/A + +--- + +## 4. DEPRECACION (10 items) + +- [x] 4.1-4.2 No hay documentos obsoletos por esta tarea +- [N/A] 4.3-4.10 No aplica - no hay deprecaciones en esta tarea + +**Resultado Seccion 4:** 1/1 aplicable completado, 9 N/A + +--- + +## 5. PURGA GRADUAL (10 items) + +- [x] 5.1-5.3 No hay redundancia identificada - documentos nuevos +- [N/A] 5.4-5.10 No aplica - documentos nuevos + +**Resultado Seccion 5:** 1/1 aplicable completado, 9 N/A + +--- + +## 6. VERIFICACION FINAL (15 items) + +### Frontmatter +- [x] 6.1 Todos los docs tienen frontmatter YAML valido +- [x] 6.2 Fechas actualizadas: 2026-01-10 +- [x] 6.3 Versiones: v3.8.0 +- [x] 6.4 Estados correctos + +### Indices e Inventarios +- [x] 6.5 _MAP.md actualizados (checklists, templates) +- [N/A] 6.6-6.9 No aplica a nivel workspace + +### Validaciones Tecnicas +- [N/A] 6.10-6.12 No aplica - solo documentacion + +### Documentacion +- [x] 6.13 Traza creada: este documento +- [N/A] 6.14 PROXIMA-ACCION.md - no hay trabajo pendiente critico +- [x] 6.15 Commits realizados con mensajes descriptivos: + - `[SIMCO-V38] feat: Implementar sistema SIMCO v3.8.0 completo` + - `[SIMCO-V38] docs: Actualizar indices _INDEX.md y _MAP.md a v3.8.0` + +**Resultado Seccion 6:** 7/7 aplicables completados, 8 N/A + +--- + +## 7. CARGA DE CONTEXTO PARA SUBAGENTES (5 items) + +- [x] 7.1 Directivas documentadas en HERENCIA-SIMCO.md de cada proyecto +- [x] 7.2 Contexto heredable actualizado (seccion v3.7 y v3.8 en cada proyecto) +- [x] 7.3 Instrucciones claras en directivas nuevas +- [N/A] 7.4 Perfiles compactos - no aplica +- [N/A] 7.5 SESSION-TRACKING - no aplica + +**Resultado Seccion 7:** 3/3 aplicables completados, 2 N/A + +--- + +## RESUMEN DE EJECUCION + +| Seccion | Items | Completados | N/A | Pendientes | +|---------|-------|-------------|-----|------------| +| 1. Identificacion | 10 | 10 | 0 | 0 | +| 2. Sincronizacion | 15 | 2 | 13 | 0 | +| 3. Validacion Dependencias | 15 | 6 | 9 | 0 | +| 4. Deprecacion | 10 | 1 | 9 | 0 | +| 5. Purga Gradual | 10 | 1 | 9 | 0 | +| 6. Verificacion Final | 15 | 7 | 8 | 0 | +| 7. Carga de Contexto | 5 | 3 | 2 | 0 | +| **TOTAL** | **80** | **30** | **50** | **0** | + +--- + +## RESULTADO + +| Campo | Valor | +|-------|-------| +| **Fecha de ejecucion** | 2026-01-10 | +| **Ejecutado por** | Claude Opus 4.5 | +| **Proyecto** | workspace-v1 | +| **Tarea/Fase** | Implementacion SIMCO v3.8.0 | +| **Resultado** | **APROBADO** | + +### Observaciones Generales + +El checklist de mantenimiento fue disenado para proyectos con codigo (backend, frontend, BD), por lo que muchos items no aplican a nivel de workspace que solo contiene documentacion de orquestacion. Los 30 items aplicables fueron completados exitosamente. + +### Cobertura Efectiva + +- **Items Aplicables:** 30/80 (37.5%) +- **Items Completados:** 30/30 (100%) +- **Items N/A justificados:** 50/80 (62.5%) + +### Recomendaciones + +1. Para proyectos con codigo, la cobertura del checklist sera mayor (~80-90%) +2. Considerar crear version "lite" del checklist para tareas solo de documentacion +3. Los items N/A estan correctamente justificados por el contexto del workspace + +--- + +**Checklist Piloto:** EXITOSO +**Validacion del instrumento:** El checklist es funcional y aplicable diff --git a/shared/knowledge-base/standards/GUIA-SIMCO-V38-DOCUMENTACION.md b/shared/knowledge-base/standards/GUIA-SIMCO-V38-DOCUMENTACION.md new file mode 100644 index 000000000..b4cca2a45 --- /dev/null +++ b/shared/knowledge-base/standards/GUIA-SIMCO-V38-DOCUMENTACION.md @@ -0,0 +1,216 @@ +# Guia de Uso: Sistema SIMCO v3.8.0 - Documentacion y Mantenimiento + +**Version:** 1.0.0 +**Fecha:** 2026-01-10 +**Sistema:** SIMCO v3.8.0 + +--- + +## Resumen + +Esta guia explica como usar las nuevas directivas SIMCO v3.7 (Estandarizacion de Documentacion) y v3.8 (Mantenimiento de Documentacion) para mantener la documentacion de proyectos sincronizada, consistente y libre de redundancias. + +--- + +## 1. Cuando Usar Estas Directivas + +### 1.1 Directivas de Estandarizacion (v3.7) + +| Directiva | Cuando Usar | Alias | +|-----------|-------------|-------| +| `SIMCO-DOCUMENTACION-PROYECTO.md` | Al crear estructura inicial de docs de un proyecto | @DOC_PROYECTO | +| `SIMCO-NOMENCLATURA.md` | Al crear archivos, carpetas o nombrar recursos | @NOMENCLATURA | +| `SIMCO-ESTRUCTURA-DOCS.md` | Al organizar contenido dentro de documentos | @ESTRUCTURA_DOCS | +| `SIMCO-INVENTARIOS.md` | Al crear o actualizar inventarios YAML | @INVENTARIOS | +| `SIMCO-TESTING.md` | Al definir cobertura y estandares de tests | @TESTING | +| `SIMCO-MIGRACIONES-BD.md` | Al crear scripts de migracion o DDL | @MIGRACIONES | +| `SIMCO-INTEGRACIONES-EXTERNAS.md` | Al documentar APIs o servicios externos | @INTEGRACIONES | + +### 1.2 Directivas de Mantenimiento (v3.8) + +| Directiva | Cuando Usar | Alias | +|-----------|-------------|-------| +| `SIMCO-MANTENIMIENTO-DOCUMENTACION.md` | Al finalizar tareas significativas para purgar/sincronizar docs | @MANTENIMIENTO_DOCS | +| `SIMCO-SINCRONIZACION-BD.md` | Cuando hay cambios en DDL que afectan docs y codigo | @SYNC_BD | + +--- + +## 2. Flujo de Trabajo Tipico + +### 2.1 Al Iniciar un Proyecto Nuevo + +``` +1. Cargar @DOC_PROYECTO +2. Crear estructura base de docs/ +3. Aplicar @NOMENCLATURA para nombres +4. Crear inventarios con @INVENTARIOS +``` + +### 2.2 Al Desarrollar Features + +``` +1. Documentar specs con @ESTRUCTURA_DOCS +2. Si hay cambios DDL: @MIGRACIONES + @SYNC_BD +3. Si hay integraciones: @INTEGRACIONES +4. Crear/actualizar tests: @TESTING +``` + +### 2.3 Al Finalizar Tareas + +``` +1. Cargar @MANTENIMIENTO_DOCS +2. Ejecutar @CHK_MANTENIMIENTO (checklist) +3. Purgar documentacion obsoleta +4. Sincronizar inventarios +``` + +--- + +## 3. Checklists Disponibles + +| Checklist | Items | Cuando Usar | +|-----------|-------|-------------| +| @CHK_DOCUMENTACION | 44 | Validar estructura de documentacion | +| @CHK_INVENTARIOS | 63 | Validar inventarios YAML | +| @CHK_NOMENCLATURA | 40 | Validar convenciones de nombres | +| @CHK_MANTENIMIENTO | 80 | Mantenimiento post-tarea | +| @CHK_SYNC_BD | 70 | Sincronizacion BD-Codigo-Docs | + +--- + +## 4. Templates Disponibles + +| Template | Alias | Uso | +|----------|-------|-----| +| TEMPLATE-INVENTARIO-PROYECTO.md | @TPL_INVENTARIO | Crear inventarios YAML | +| TEMPLATE-INTEGRACION-EXTERNA.md | @TPL_INTEGRACION | Documentar APIs externas | +| TEMPLATE-MODULO-ESTANDAR.md | @TPL_MODULO_ESTANDAR | Documentar modulos | +| TEMPLATE-DEPRECACION.md | @TPL_DEPRECACION | Marcar docs como deprecados | + +--- + +## 5. Ciclo de Mantenimiento (CAPVED + M) + +``` +C - Contexto → Identificar documentos afectados +A - Analisis → Detectar inconsistencias y obsolescencia +P - Planeacion → Definir que sincronizar/purgar +V - Validacion → Verificar dependencias antes de ejecutar +E - Ejecucion → Aplicar cambios +D - Documentar → Registrar cambios realizados +M - Mantenimiento → Ejecutar @CHK_MANTENIMIENTO +``` + +--- + +## 6. Estructura de Archivos HERENCIA-SIMCO.md + +Cada proyecto debe tener su archivo `orchestration/00-guidelines/HERENCIA-SIMCO.md` con: + +```markdown +## Directivas de Documentacion (SIMCO v3.7) +[Tabla de directivas aplicables al proyecto] + +## Directivas de Mantenimiento (SIMCO v3.8) +[Tabla de directivas de mantenimiento] +``` + +--- + +## 7. Ejemplos de Uso + +### 7.1 Documentar Nueva Integracion + +```bash +# 1. Cargar directiva +"Cargando @INTEGRACIONES para documentar integracion con Stripe" + +# 2. Usar template +"Usando @TPL_INTEGRACION como base" + +# 3. Crear archivo +docs/02-integraciones/INT-XXX-stripe.md +``` + +### 7.2 Actualizar Despues de Cambio DDL + +```bash +# 1. Cargar directiva +"Cargando @SYNC_BD para sincronizar cambios DDL" + +# 2. Ejecutar checklist +"Ejecutando @CHK_SYNC_BD" + +# 3. Actualizar +- database/scripts/ +- backend/entities/ +- backend/DTOs/ +- inventarios/DATABASE_INVENTORY.yml +``` + +### 7.3 Marcar Documento como Deprecado + +```bash +# 1. Cargar template +"Usando @TPL_DEPRECACION" + +# 2. Agregar bloque +[DEPRECATED] +- Fecha: 2026-01-10 +- Razon: Reemplazado por docs/specs/ET-XXX.md +- Eliminacion: 2026-02-10 +[/DEPRECATED] +``` + +--- + +## 8. Perfil Especializado + +Para tareas de mantenimiento extenso, usar el perfil: + +``` +@PERFIL_DOC_MAINT → PERFIL-DOCUMENTATION-MAINTAINER.md +``` + +Este perfil esta optimizado para: +- Identificacion de documentos obsoletos +- Sincronizacion entre capas +- Purga gradual de redundancia +- Deprecacion sistematica + +--- + +## 9. Referencias Rapidas + +### Ubicacion de Directivas +``` +orchestration/directivas/simco/SIMCO-*.md +``` + +### Ubicacion de Templates +``` +orchestration/templates/TEMPLATE-*.md +``` + +### Ubicacion de Checklists +``` +orchestration/checklists/CHECKLIST-*.md +``` + +### Indice Principal +``` +orchestration/INDICE-DIRECTIVAS-WORKSPACE.yml +``` + +--- + +## 10. Soporte + +Para dudas sobre el uso de estas directivas: +1. Consultar `directivas/simco/_INDEX.md` +2. Revisar `INDICE-DIRECTIVAS-WORKSPACE.yml` +3. Ver ejemplos en proyectos actualizados (gamilit, erp-core, template-saas) + +--- + +**Sistema:** SIMCO v3.8.0 | **Mantenido por:** Tech Lead