# Hallazgo Crítico: Desincronización Rutas /docs/ en Gamilit

> ✅ **RESUELTO** - Este hallazgo fue corregido el 2026-01-10
>
> **Solución aplicada:** Opción A - Actualizar referencias en .claude/
> **Archivos corregidos:** 26 archivos
> **Validación:** Ver `VALIDACION-B5-RUTAS-DOCS-2026-01-10.md`

**Fecha:** 2026-01-10
**Severidad:** ~~ALTA~~ RESUELTA
**Detectado en:** Fase B5 de Auditoría de Documentación
**Archivos afectados:** 26 archivos en `.claude/` (CORREGIDOS)

---

## Resumen

Las referencias a `/docs/` en los archivos de configuración del sistema NEXUS (`.claude/`) **NO coinciden** con la estructura real de documentación del proyecto Gamilit.

---

## Estructura Referenciada vs Real

| Referencia Esperada | Estado | Ubicación Real |
|---------------------|--------|----------------|
| `/docs/01-requerimientos/` | NO EXISTE | `/docs/01-fase-alcance-inicial/` |
| `/docs/02-especificaciones-tecnicas/` | NO EXISTE | `/docs/90-transversal/` |
| `/docs/03-desarrollo/` | NO EXISTE | No encontrado |
| `/docs/04-planificacion/` | NO EXISTE | `/docs/planning/` |
| `/docs/standards/` | NO EXISTE | `/docs/archivados/98-standards-deprecated/` |
| `/docs/02-especificaciones-tecnicas/apis/` | NO EXISTE | `/docs/90-transversal/api/` |
| `/docs/02-especificaciones-tecnicas/database/` | NO EXISTE | `/docs/90-transversal/inventarios-database/` |

---

## Estructura Real de /docs/

```
docs/
├── 00-vision-general/
├── 01-fase-alcance-inicial/         (EAI-001 a EAI-008)
├── 02-fase-robustecimiento/         (EMR-001)
├── 03-fase-extensiones/             (EXT-001 a EXT-011)
├── 04-fase-backlog/
├── 90-transversal/                  (APIs, Database, Arquitectura)
├── 95-guias-desarrollo/
├── 96-quick-reference/
├── 97-adr/
├── 99-finiquito/
├── 99-troubleshooting/
├── archivados/
├── audits/
└── planning/                        (Planificación, Análisis)
```

---

## Archivos Afectados

### Críticos (validación de documentación)
1. `directivas/DIRECTIVA-VALIDACION-DOCUMENTACION.md`
2. `.claude/README.md`

### Agentes NEXUS (9 archivos)
- `INIT-NEXUS-BACKEND.md`
- `INIT-NEXUS-BACKEND-AVANZADO.md`
- `INIT-NEXUS-FRONTEND.md`
- `INIT-NEXUS-FRONTEND-AVANZADO.md`
- `INIT-NEXUS-DATABASE.md`
- `INIT-NEXUS-DATABASE-AVANZADO.md`
- `INIT-NEXUS-TESTING.md`
- `INIT-NEXUS-INTEGRATION.md`
- `INIT-NEXUS-VALIDATION.md`
- `INIT-NEXUS-DEVOPS.md`
- `INIT-NEXUS-COMPLETITUD.md`

### Directivas (11 archivos)
- `DIRECTIVAS-PRINCIPALES.md`
- `DIRECTIVAS-FLUJOS.md`
- `PROCESO-VALIDACION.md`
- `PRINCIPIOS-SOLID-DOCS.md`
- Y otras...

### Referencias y Templates (6 archivos)
- `referencias/PATHS-TRABAJO.md`
- `referencias/PATHS-DOCUMENTACION.md`
- `templates/TEMPLATES-SUBAGENTES.md`

---

## Opciones de Corrección

### Opción A: Actualizar Referencias en .claude/ (RECOMENDADA)
- **Esfuerzo:** Medio (26 archivos)
- **Riesgo:** Bajo
- **Descripción:** Actualizar todas las referencias para usar las rutas reales existentes

### Opción B: Reorganizar /docs/
- **Esfuerzo:** Alto
- **Riesgo:** Medio-Alto (puede romper otras referencias)
- **Descripción:** Mover contenido para coincidir con las referencias esperadas

### Opción C: Crear Symlinks como Puente
- **Esfuerzo:** Bajo
- **Riesgo:** Bajo (pero requiere mantenimiento)
- **Descripción:** Crear enlaces simbólicos que mapeen rutas antiguas a nuevas

---

## Mapeo Propuesto para Opción A

```yaml
mapeo_rutas:
  antiguo: "/docs/01-requerimientos/"
  nuevo: "/docs/01-fase-alcance-inicial/"

  antiguo: "/docs/02-especificaciones-tecnicas/"
  nuevo: "/docs/90-transversal/"

  antiguo: "/docs/02-especificaciones-tecnicas/apis/"
  nuevo: "/docs/90-transversal/api/"

  antiguo: "/docs/02-especificaciones-tecnicas/database/"
  nuevo: "/docs/90-transversal/inventarios-database/"

  antiguo: "/docs/04-planificacion/"
  nuevo: "/docs/planning/"

  antiguo: "/docs/standards/"
  nuevo: "/docs/archivados/98-standards-deprecated/"
```

---

## Impacto si NO se Corrige

1. **Validación de documentación fallará** - DIRECTIVA-VALIDACION-DOCUMENTACION no encontrará rutas
2. **Agentes NEXUS operarán con contexto incorrecto** - Referencias a docs inexistentes
3. **Sistema de validación de coherencia disfuncional** - No puede validar código vs docs

---

## Próximos Pasos

1. [ ] Decidir entre Opción A, B o C
2. [ ] Si Opción A: Crear script de migración de referencias
3. [ ] Actualizar los 26 archivos afectados
4. [ ] Validar que las nuevas referencias funcionan
5. [ ] Actualizar CONTEXTO-REFERENCIAS.md con el nuevo mapeo

---

**Estado:** ✅ RESUELTO
**Fecha resolución:** 2026-01-10
**Solución:** Opción A - Actualizar 26 archivos .claude/ con rutas reales