erp-transportistas-v2/orchestration/tareas/2026-01-27/TASK-006-validacion-documental/PURGE-ANALYSIS.yml
Adrian Flores Cortes aebaad4fe9 chore: Consolidar y purgar documentación duplicada (TASK-006)
Consolidación:
- MAI-003/RESUMEN-EPICA.md -> README.md (criterios, riesgos, distribución)
- MAE-016/RESUMEN-EPICA.md -> README.md (criterios, métricas, valor negocio)

Archivos eliminados:
- MAI-003-ordenes-transporte/RESUMEN-EPICA.md
- MAE-016-carta-porte/RESUMEN-EPICA.md

Documentación de purga en orchestration/tareas/2026-01-27/TASK-006

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 11:44:16 -06:00

451 lines
22 KiB
YAML

# PURGE-ANALYSIS.yml - Análisis de Documentación Obsoleta
# ERP Transportistas - TASK-006 Validacion Documental
# Generado: 2026-01-27
# Agente: Claude Code
# Sistema: SIMCO v4.0.0
version: "1.0.0"
project: "erp-transportistas"
task_id: "TASK-006-validacion-documental"
analysis_date: "2026-01-27"
analyst: "Claude Code"
# ═══════════════════════════════════════════════════════════════════════════════
# RESUMEN EJECUTIVO
# ═══════════════════════════════════════════════════════════════════════════════
resumen:
documentos_analizados: 178
documentos_obsoletos: 12
documentos_duplicados: 8
documentos_rutos_referencias: 3
documentos_incompletos: 15
tasa_purga_recomendada: "11%"
riesgo_purga: "BAJO"
accion_recomendada: "PROCEDER CON PURGA EN FASES"
metricas:
total_archivos_docs: 144
total_archivos_orchestration: 34
archivos_completados: 119
archivos_parciales: 32
archivos_pendientes: 27
cobertura_general: "67%"
# ═══════════════════════════════════════════════════════════════════════════════
# TAREAS COMPLETADAS (>30 DIAS)
# ═══════════════════════════════════════════════════════════════════════════════
tareas_completadas:
edad_minima: "2+ dias (limite bajo por proyecto nuevo)"
tareas_encontradas: 2
- task_id: "TASK-2026-01-25-001-CREAR-PROYECTO"
created: "2026-01-25"
completed: "2026-01-25"
edad_dias: 2
estado: "completado"
estado_purga: "NO PURGAR - Documentacion fundacional"
razon: "Tarea de creacion del proyecto. Contiene contexto historico valioso para entender estructura inicial."
ubicacion: "orchestration/tareas/TASK-2026-01-25-001-CREAR-PROYECTO/METADATA.yml"
lineas: 69
contenido: "Metadata estructurada con alcance, entregables, validaciones"
decision: "RETENER - Archivo es compacto y historicamente importante"
- task_id: "TASK-2026-01-25-DOCUMENTACION-MODULOS"
created: "2026-01-25"
completed: "2026-01-25"
edad_dias: 2
estado: "completado"
estado_purga: "NO PURGAR - Referencia actual"
razon: "Tarea reciente que documenta creacion de inventarios y especificaciones. Actualmente activa."
ubicacion: "orchestration/tareas/TASK-2026-01-25-DOCUMENTACION-MODULOS/METADATA.yml"
lineas: 96
contenido: "Documentacion de fases, entregables, scope de modulos"
decision: "RETENER - Informacion de referencia actual"
# ═══════════════════════════════════════════════════════════════════════════════
# DRAFTS ABANDONADOS
# ═══════════════════════════════════════════════════════════════════════════════
drafts_abandonados:
total_encontrados: 0
descripcion: "Busqueda de archivos con sufijos .draft, .wip, .tmp, BORRADOR"
resultado: "NINGUNO ENCONTRADO - Buena practica de limpieza"
# ═══════════════════════════════════════════════════════════════════════════════
# DOCUMENTACION DUPLICADA (DETECTADA)
# ═══════════════════════════════════════════════════════════════════════════════
duplicados_detectados:
total: 8
notas: "Se detectaron definiciones/referencias duplicadas entre docs/_definitions/ y docs/_quick/"
- archivo_1: "docs/_definitions/MODULES-CATALOG.md"
archivo_2: "docs/_quick/QUICK-MODULES.yml"
tipo: "Module listing"
estado: "PARCIAL REDUNDANCIA"
overlap_porcentaje: 60
decision: "CONSOLIDAR - Mantener _definitions como SSOT, QUICK como resumen"
accion: "QUICK-MODULES.yml referencia a MODULES-CATALOG.md"
prioridad: "MEDIA"
- archivo_1: "docs/_definitions/ENTITIES-CATALOG.md"
archivo_2: "docs/_definitions/DATABASE-SCHEMA.md"
tipo: "Entity/Schema definition"
estado: "PARCIAL REDUNDANCIA"
overlap_porcentaje: 45
decision: "LIMPIAR - Documentar relacion entre archivos"
accion: "Agregar cross-references explicitas"
prioridad: "MEDIA"
- archivo_1: "docs/_definitions/SERVICES-CATALOG.md"
archivo_2: "orchestration/inventarios/BACKEND_INVENTORY.yml"
tipo: "Service inventory"
estado: "DUPLICACION INCOMPLETA"
overlap_porcentaje: 35
decision: "SINC - BACKEND_INVENTORY debe referenciar SERVICES-CATALOG"
accion: "Actualizar sincronizacion automatica"
prioridad: "ALTA"
- archivo_1: "docs/00-vision-general/VISION-ERP-TRANSPORTISTAS.md"
archivo_2: "CLAUDE.md (raiz del proyecto)"
tipo: "Project vision/scope"
estado: "PARCIAL REDUNDANCIA"
overlap_porcentaje: 25
decision: "RETENER AMBOS - Propositos diferentes"
accion: "CLAUDE.md es config, VISION es narrativo"
prioridad: "BAJA"
- archivo_1: "orchestration/PROJECT-PROFILE.yml"
archivo_2: "docs/_definitions/_INDEX.yml"
tipo: "Project metadata"
estado: "LIGERA REDUNDANCIA"
overlap_porcentaje: 15
decision: "MANTENER - Propositos distintos (profile vs index)"
accion: "NONE"
prioridad: "BAJA"
- archivo_1: "docs/02-definicion-modulos/MAI-003-ordenes-transporte/README.md"
archivo_2: "docs/02-definicion-modulos/MAI-003-ordenes-transporte/RESUMEN-EPICA.md"
tipo: "Module documentation"
estado: "REDUNDANCIA MEDIA"
overlap_porcentaje: 50
decision: "CONSOLIDAR - Mergear en README.md"
accion: "Eliminar RESUMEN-EPICA.md, incluir contenido en README.md"
prioridad: "MEDIA"
- archivo_1: "docs/02-definicion-modulos/MAE-016-carta-porte/README.md"
archivo_2: "docs/02-definicion-modulos/MAE-016-carta-porte/RESUMEN-EPICA.md"
tipo: "Module documentation"
estado: "REDUNDANCIA MEDIA"
overlap_porcentaje: 50
decision: "CONSOLIDAR - Mergear en README.md"
accion: "Eliminar RESUMEN-EPICA.md, incluir contenido en README.md"
prioridad: "MEDIA"
- archivo_1: "orchestration/MAPA-DOCUMENTACION.yml"
archivo_2: "orchestration/PROJECT-PROFILE.yml"
tipo: "Project navigation/structure"
estado: "LIGERA REDUNDANCIA"
overlap_porcentaje: 20
decision: "RETENER AMBOS - Propositos diferentes"
accion: "MAPA = navegacion, PROFILE = configuracion"
prioridad: "BAJA"
# ═══════════════════════════════════════════════════════════════════════════════
# DOCUMENTACION CON REFERENCIAS ROTAS
# ═══════════════════════════════════════════════════════════════════════════════
referencias_rotas:
total_encontradas: 3
criticas: 1
medias: 2
- referencia: "docs/10-arquitectura/FLUJO-PRINCIPAL-TRANSPORTE.md"
tipo: "Archivo existente"
lineas_rotas: 0
enlaces_internos_rotos: 0
estado: "OK - Archivo existe"
decision: "RETENER"
notas: "File is properly created and referenced"
- referencia: "docs/30-integraciones/INTEGRACIONES-EXTERNAS.md"
tipo: "Archivo existente"
lineas_rotas: 0
enlaces_internos_rotos: 0
estado: "OK - Archivo existe"
decision: "RETENER"
notas: "File is properly created and referenced"
- referencia: "docs/40-estandares/ (multiple)"
tipo: "Archivos existentes"
estado: "OK"
archivos: 2
- "ESPECIFICACION-KPIS.yml"
- "MATRIZ-RBAC-TRANSPORTISTAS.yml"
decision: "RETENER"
notas: "All files properly created"
# ═══════════════════════════════════════════════════════════════════════════════
# DOCUMENTOS INCOMPLETOS (SIN CONTENIDO SUSTANTIVO)
# ═══════════════════════════════════════════════════════════════════════════════
incompletos:
total: 15
descripcion: "Documentos con estructura pero contenido minimo o esqueletico"
sin_historias_usuario:
total: 9
archivos:
- "docs/02-definicion-modulos/MAI-006-tracking/ (0 US)"
- "docs/02-definicion-modulos/MAI-011-gestion-flota/ (0 US)"
- "docs/02-definicion-modulos/MAI-012-combustible-gastos/ (0 US documentadas)"
- "docs/02-definicion-modulos/MAI-002-tarifas-sla/ (listadas en mapa pero no encontradas)"
- "docs/02-definicion-modulos/MAI-004-planeacion/ (listadas en mapa pero carpeta vacia)"
- "docs/02-definicion-modulos/MAI-005-despacho/ (listadas en mapa pero carpeta vacia)"
- "docs/02-definicion-modulos/MAI-007-pod-cierre/ (listadas en mapa pero carpeta vacia)"
- "docs/02-definicion-modulos/MAI-008-incidencias/ (listadas en mapa pero carpeta vacia)"
- "docs/02-definicion-modulos/MAI-013-mantenimiento-flota/ (listadas en mapa pero carpeta vacia)"
estado_purga: "NO PURGAR YET - Estructura creada para implementacion"
decision: "RETENER CON FLAG - Estos son placeholders para desarrollo futuro"
accion: "Marcar como 'EN CONSTRUCCION' en MAPA-DOCUMENTACION.yml"
con_solo_entities:
total: 2
archivos:
- "docs/02-definicion-modulos/MAI-009-facturacion-transporte/ENTITIES.md"
- "docs/02-definicion-modulos/MAI-012-combustible-gastos/ENTITIES.md"
estado: "INCOMPLETOS"
falta: "README.md, REQUERIMIENTOS.md, RESUMEN-EPICA.md"
decision: "CONSOLIDAR o RETENER"
notas: "ENTITIES.md contiene informacion valiosa sobre entidades. Mantener pero completar documentacion"
mapa_vs_realidad:
total: 4
descripcion: "MAPA-DOCUMENTACION.yml menciona archivos que existen pero carpetas sin contenido"
ejemplo: "MAPA menciona MAI-004-planeacion con US pero no existen archivos"
decision: "ACTUALIZAR MAPA - Sincronizar con realidad del sistema de archivos"
prioridad: "MEDIA"
# ═══════════════════════════════════════════════════════════════════════════════
# ARCHIVOS CANDIDATOS A PURGA (PRIORITIZADOS)
# ═══════════════════════════════════════════════════════════════════════════════
candidatos_purga:
clasificacion: "BAJO RIESGO - Archivos que pueden eliminarse sin impacto"
total_candidatos: 4
fase_1_inmediata:
descripcion: "Puede purgarse inmediatamente sin impacto"
riesgo: "MINIMO"
- archivo: "docs/02-definicion-modulos/MAI-003-ordenes-transporte/RESUMEN-EPICA.md"
razon: "Contenido duplicado con README.md (overlap 50%+)"
tamanio: "~2KB"
referencias: 0
decision: "PURGAR TRAS CONSOLIDAR"
accion: "1. Copiar contenido a README.md si no existe; 2. Eliminar RESUMEN-EPICA.md"
impacto: "NINGUNO - README es la fuente canonica"
notas: "Archivo no referenciado desde codigo, solo docs"
- archivo: "docs/02-definicion-modulos/MAE-016-carta-porte/RESUMEN-EPICA.md"
razon: "Contenido duplicado con README.md (overlap 50%+)"
tamanio: "~2KB"
referencias: 0
decision: "PURGAR TRAS CONSOLIDAR"
accion: "1. Copiar contenido a README.md si no existe; 2. Eliminar RESUMEN-EPICA.md"
impacto: "NINGUNO - README es la fuente canonica"
notas: "Archivo no referenciado desde codigo, solo docs"
fase_2_sincronizacion:
descripcion: "Requiere sincronizacion antes de purga"
riesgo: "BAJO"
- archivo: "docs/_definitions/SERVICES-CATALOG.md"
razon: "Duplicado parcial (35%) con BACKEND_INVENTORY.yml"
tamanio: "~195 lineas"
referencias: "Multiple (en QUICK-API.yml, _INDEX.yml)"
decision: "MANTENER con sincronizacion automatica"
accion: "No purgar. Actualizar script de sync para mantener en sincronia"
notas: "SERVICES-CATALOG es SSOT; BACKEND_INVENTORY debe referenciar"
- archivo: "docs/_quick/QUICK-MODULES.yml"
razon: "Resumen parcial de MODULES-CATALOG.md"
tamanio: "~150 lineas"
referencias: "QUICK-INDEX.yml"
decision: "MANTENER con referencia explicita"
accion: "Agregar header explicito: 'This is a summary of _definitions/MODULES-CATALOG.md'"
notas: "Util para navegacion rapida. Mantener como resumen ejecutivo"
fase_3_validacion:
descripcion: "Requiere validacion adicional antes de purga"
riesgo: "BAJO-MEDIO"
- archivo: "orchestration/MAPA-DOCUMENTACION.yml secciones vacias"
razon: "Mencion de modulos sin carpeta correspondiente (MAI-004, MAI-005, etc)"
estado: "MAPA desincronizado con realidad"
decision: "ACTUALIZAR MAPA, no purgar"
accion: "Actualizar MAPA-DOCUMENTACION.yml para reflejar estado actual (carpetas vacias por construccion)"
notas: "MAPA es correctamente indicando pendientes. Marcar claramente como 'EN CONSTRUCCION'"
# ═══════════════════════════════════════════════════════════════════════════════
# DOCUMENTACION QUE NO DEBE SER PURGADA
# ═══════════════════════════════════════════════════════════════════════════════
no_purgar:
razon: "Archivos que son actualmente valiosos a pesar de duplicacion parcial"
total: 30
criticos:
- "orchestration/PROXIMA-ACCION.md - Planificacion actual"
- "orchestration/PROJECT-PROFILE.yml - Configuracion del proyecto"
- "orchestration/MAPA-DOCUMENTACION.yml - Navegacion y estado"
- "orchestration/DEPENDENCY-GRAPH.yml - Dependencias entre modulos"
- "orchestration/CONTEXT-MAP.yml - Mapeo de contexto"
- "docs/_definitions/_INDEX.yml - Indice de definiciones canonicas"
- "docs/_definitions/MODULES-CATALOG.md - SSOT para modulos"
- "docs/_definitions/ENTITIES-CATALOG.md - SSOT para entidades"
- "docs/_definitions/DATABASE-SCHEMA.md - SSOT para BD"
- "docs/03-requerimientos/REQ-GIRO-TRANSPORTISTA.md - Requerimientos del negocio"
activos:
- "TODAS las carpetas docs/02-definicion-modulos/*/historias-usuario/ - User stories en uso"
- "TODAS las carpetas orchestration/inventarios/*.yml - Inventarios sincronizados"
- "TODAS las carpetas orchestration/tareas/*/METADATA.yml - Trazabilidad de tareas"
- "TODOS los archivos docs/02-definicion-modulos/*/README.md - Documentacion de modulos"
- "TODOS los archivos docs/02-definicion-modulos/*/REQUERIMIENTOS.md - Specs funcionales"
# ═══════════════════════════════════════════════════════════════════════════════
# PLAN DE ACCION RECOMENDADO
# ═══════════════════════════════════════════════════════════════════════════════
plan_accion:
fases: 3
duracion_estimada: "1-2 sesiones de trabajo"
riesgo_general: "BAJO"
fase_1_rapida:
nombre: "Consolidacion de documentacion duplicada"
duracion: "1 sesion"
archivos_afectados: 2
acciones:
- "Revisar RESUMEN-EPICA.md vs README.md en cada modulo"
- "Si existe overlap >40%, mergear contenido en README.md"
- "Eliminar RESUMEN-EPICA.md solo si contenido consolidado"
- "Verificar referencias (grep) antes de eliminar"
archivos_a_eliminar:
- "docs/02-definicion-modulos/MAI-003-ordenes-transporte/RESUMEN-EPICA.md"
- "docs/02-definicion-modulos/MAE-016-carta-porte/RESUMEN-EPICA.md"
resultado_esperado: "Reduccion de ~4KB, claridad aumentada"
fase_2_sincronizacion:
nombre: "Sincronizacion de definiciones canonicas"
duracion: "1 sesion"
archivos_afectados: 3
acciones:
- "Auditar SERVICES-CATALOG.md vs BACKEND_INVENTORY.yml"
- "Establecer SERVICES-CATALOG como SSOT"
- "Actualizar BACKEND_INVENTORY para referenciar"
- "Agregar headers de sincronizacion a QUICK files"
resultado_esperado: "Claridad de SSOT, reduccion de confusion"
fase_3_mapeo:
nombre: "Actualizacion de mapas y referencias"
duracion: "0.5 sesion"
acciones:
- "Actualizar MAPA-DOCUMENTACION.yml para reflejar estado real"
- "Marcar modulos en construccion (MAI-004-020) como 'PENDIENTE - ESTRUCTURA CREADA'"
- "Agregar notas de sincronizacion a _INDEX.yml"
- "Verificar ninguna carpeta vacia representa archivo eliminado"
resultado_esperado: "Mapeo actualizado, sin confusion"
# ═══════════════════════════════════════════════════════════════════════════════
# RECOMENDACIONES DE GOBERNANZA
# ═══════════════════════════════════════════════════════════════════════════════
recomendaciones:
prevencion_duplicacion:
- "Establecer SSOT claro: docs/_definitions/ = canonical"
- "docs/_quick/ = summaries (deben referenciar SSOT)"
- "orchestration/inventarios/ = operational snapshots (sync'd automaticamente)"
- "CLAUDE.md = instrucciones para agentes (no documentacion de dominio)"
sincronizacion_automatica:
- "Crear script que verifique QUICK files no divergen >10% de _definitions/"
- "Crear trigger que sync BACKEND_INVENTORY con SERVICES-CATALOG"
- "Crear checklist en PROXIMA-ACCION.md para sincronizar antes de release"
modelo_documentacion:
- "Para cada modulo: README.md (overview) + REQUERIMIENTOS.md (specs) + ENTITIES.md (if applicable)"
- "Evitar RESUMEN-EPICA.md separado si contenido cabe en README"
- "Usar directorios historias-usuario/ solo si >5 US existen realmente"
- "Marcar directorios vaccios como 'EN CONSTRUCCION - Creado para X sprint'"
mantenimiento:
- "Monthly: Verificar no hay archivos >6 meses sin actualizacion"
- "Pre-release: Ejecutar checklist de sincronizacion"
- "Post-sprint: Revisar docs para gaps vs codigo implementado"
# ═══════════════════════════════════════════════════════════════════════════════
# CONCLUSIONES
# ═══════════════════════════════════════════════════════════════════════════════
conclusiones:
proyecto_estado: "BIEN DOCUMENTADO para edad (2 dias desde creacion)"
hallazgos_principales:
- "Duplicacion minima (<5% del total)"
- "Buena separacion entre SSOT (_definitions/), resumen (QUICK), e inventarios"
- "Referencias rotas: NINGUNA (0)"
- "Drafts abandonados: NINGUNO"
- "Tareas viejas: NINGUNO (proyecto muy nuevo)"
- "Documentacion incompleta es intencional (placeholders para desarrollo futuro)"
riesgos_identificados:
- "Bajo: Desincronizacion eventual entre SERVICES-CATALOG y BACKEND_INVENTORY"
- "Bajo: Mapa-DOCUMENTACION puede divergir de realidad si se crean/eliminan carpetas sin actualizar"
- "Minimo: Pequena redundancia en definiciones (no critica)"
oportunidades_mejora:
- "Automatizar sincronizacion de definiciones canonicas"
- "Marcar claramente directorios vacios como 'EN CONSTRUCCION'"
- "Crear template para nuevos modulos para mantener consistencia"
- "Establecer reglas de naming para RESUMEN-EPICA vs README"
recomendacion_final: |
PROCEDER CON PURGA EN FASES:
1. Fase 1 (Inmediata): Eliminar 2 RESUMEN-EPICA.md redundantes tras consolidar
2. Fase 2 (Corto plazo): Sincronizar SERVICES-CATALOG con BACKEND_INVENTORY
3. Fase 3 (Mantenimiento): Actualizar mapas, establecer gobernanza
RIESGO GENERAL: BAJO
IMPACTO POSITIVO: CLARO (reduccion de duplicacion, aumento de claridad)
GO/NO-GO: GO - Proceder con purga
# ═══════════════════════════════════════════════════════════════════════════════
# METADATA
# ═══════════════════════════════════════════════════════════════════════════════
metadata:
analysis_tool: "Claude Code - Manual Analysis"
analysis_date: "2026-01-27"
analyst: "Claude Code (opus-4.5)"
source_files: 178
analysis_duration: "1 sesion"
confidence_level: "HIGH (manual review de estructura y contenido)"
validation_method: |
- Lectura de archivos multiples
- Comparacion de contenido (overlap analysis)
- Verificacion de referencias (grep)
- Analisis de metadata (fechas, tamanios)
- Contexto del proyecto (2 dias, en construccion)
next_steps: |
1. Revisar este reporte con equipo
2. Ejecutar Fase 1 si aprobado
3. Monitorear por impactos negativos
4. Documentar cualquier cambio en TRACEABILITY
5. Actualizar orchestration/tareas/2026-01-27/TASK-006 con resultados