# 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