# ST3.2: Documentation Reorganization Analysis

**Fecha:** 2026-01-26
**Tarea:** TASK-2026-01-29-DOCUMENTATION-PURGE
**Subtarea:** ST3.2 (4h estimadas)
**Agente:** Claude Opus 4.5

---

## Resumen Ejecutivo

Análisis de estructura docs/ para identificar archivos redundantes, obsoletos, o desorganizados que requieren reorganización post-integración de ST1-ST2.

---

## Hallazgos

### 1. Archivos Sueltos en docs/ (Potencialmente Redundantes)

| Archivo | Líneas | Fecha | Estado | Acción Recomendada |
|---------|--------|-------|--------|-------------------|
| **API.md** | 636 | 2026-01-04 | ⚠️ Posiblemente redundante | Comparar con swagger.yml (ST2.3), consolidar/archivar |
| **ARCHITECTURE.md** | 576 | 2026-01-04 | ⚠️ Posiblemente redundante | Verificar vs docs/01-arquitectura/, consolidar |
| **SECURITY.md** | 822 | 2026-01-04 | ✅ Legítimo | Mover a docs/90-transversal/security/ |
| **_MAP.md** | 455 | 2026-01-07 | ⚠️ Desactualizado | Actualizar fecha y contenido |
| **README.md** | 280 | 2026-01-04 | ✅ Legítimo | Mantener (punto de entrada) |

### 2. Carpetas Sueltas (Posiblemente Obsoletas)

#### docs/planning/ (Contenido obsoleto)
```
planning/
├── Board.md                          # 2026-01-04 - Tablero Kanban obsoleto
├── config.yml                        # 2026-01-04 - Config antigua
└── REESTRUCTURACION-PROGRESS.md      # 2026-01-04 - Proceso antiguo GAMILIT
```

**Análisis:** Documenta "reestructuración GAMILIT" de enero 2026. Contenido obsoleto.

**Acción:** ❌ **ELIMINAR** (archivar en docs/99-analisis/obsoletos/ si hay valor histórico)

---

#### docs/architecture/ (Contenido desorganizado)
```
architecture/
└── EA-BRIDGE-ARCHITECTURE.md         # 14,401 líneas - MT4 Expert Advisor bridge
```

**Análisis:** Arquitectura MT4 que debería estar en docs/01-arquitectura/

**Acción:** ➡️ **MOVER** a docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md

---

#### docs/api-contracts/ (Contenido desorganizado)
```
api-contracts/
└── SERVICE-INTEGRATION.md            # 13,103 líneas - Integración servicios
```

**Análisis:** Documenta integración entre servicios (MCP, ML, backend).

**Acción:** ➡️ **MOVER** a docs/90-transversal/integraciones/INT-SERVICES-INTEGRATION.md

---

### 3. Archivos Duplicados/Redundantes

#### API.md vs swagger.yml

| Aspecto | API.md (636 líneas) | swagger.yml (1,335 líneas) |
|---------|---------------------|----------------------------|
| Fecha | 2026-01-04 | 2026-01-26 (ST2.3) |
| Formato | Markdown | OpenAPI 3.0.3 |
| Contenido | Overview puertos, auth | Especificación completa 34 endpoints |
| Estado | ⚠️ Posiblemente desactualizado | ✅ Actualizado y completo |

**Decisión:**
- swagger.yml es la fuente oficial de especificación API
- API.md tiene valor como overview legible (puertos, conceptos)
- **Acción:** Actualizar API.md para referenciar swagger.yml, reducir duplicación

---

#### ARCHITECTURE.md vs docs/01-arquitectura/

| Aspecto | ARCHITECTURE.md (576 líneas) | docs/01-arquitectura/ (múltiples archivos) |
|---------|------------------------------|-------------------------------------------|
| Fecha | 2026-01-04 | 2026-01-24 (actualizado) |
| Contenido | Overview general, tech stack | Arquitecturas específicas detalladas |
| Nivel | Alto nivel (introducción) | Detallado (implementación) |

**Decisión:**
- ARCHITECTURE.md tiene valor como overview de alto nivel
- docs/01-arquitectura/ contiene documentos especializados
- **Acción:** Mover secciones de ARCHITECTURE.md a docs/00-vision-general/ARQUITECTURA-GENERAL.md (consolida con doc existente)

---

## Plan de Reorganización

### Fase 1: Archivos Temporales Obsoletos (✅ ST3.1 - Completado)

```bash
rm -f nul " -u" -u
git add -A && git commit -m "chore: Remove temporary error files"
```

**Resultado:** ✅ Commit f10c31db

---

### Fase 2: Reorganizar Carpetas Sueltas

#### 2.1: Mover architecture/EA-BRIDGE-ARCHITECTURE.md

```bash
mv docs/architecture/EA-BRIDGE-ARCHITECTURE.md \
   docs/01-arquitectura/ARQUITECTURA-EA-BRIDGE-MT4.md

rmdir docs/architecture/

git add -A && git commit -m "docs: Move EA bridge architecture to 01-arquitectura/"
```

---

#### 2.2: Mover api-contracts/SERVICE-INTEGRATION.md

```bash
mv docs/api-contracts/SERVICE-INTEGRATION.md \
   docs/90-transversal/integraciones/INT-SERVICES-INTEGRATION.md

rmdir docs/api-contracts/

git add -A && git commit -m "docs: Move service integration to 90-transversal/integraciones/"
```

---

#### 2.3: Eliminar docs/planning/ (obsoleto)

```bash
# Opción 1: Archivar si hay valor histórico
mkdir -p docs/99-analisis/obsoletos/planning-2026-01-04
mv docs/planning/* docs/99-analisis/obsoletos/planning-2026-01-04/

# Opción 2: Eliminar directamente
rm -rf docs/planning/

git add -A && git commit -m "docs: Remove obsolete planning/ directory"
```

---

### Fase 3: Consolidar Archivos Sueltos

#### 3.1: Consolidar ARCHITECTURE.md

**Acción:** Mover contenido único a docs/00-vision-general/ARQUITECTURA-GENERAL.md

```bash
# Editar docs/00-vision-general/ARQUITECTURA-GENERAL.md para incorporar secciones únicas
# Eliminar docs/ARCHITECTURE.md

rm docs/ARCHITECTURE.md
git add -A && git commit -m "docs: Consolidate ARCHITECTURE.md into 00-vision-general/"
```

---

#### 3.2: Actualizar API.md para referenciar swagger.yml

**Acción:** Reducir API.md a overview con referencia a swagger.yml

**Ejemplo:**
```markdown
# API Documentation

**⚠️ For complete API specification, see: [swagger.yml](../apps/backend/swagger.yml)**

This document provides a high-level overview of the API.

## Base URL

Development: http://localhost:3080/api/v1

## Service Ports

| Service | Port | Description |
|---------|------|-------------|
| Backend API | 3080 | Main REST API |
| Frontend | 3000 | React SPA |
...

## Authentication

See [swagger.yml](../apps/backend/swagger.yml) for detailed authentication endpoints.
```

---

#### 3.3: Mover SECURITY.md

```bash
mkdir -p docs/90-transversal/security/
mv docs/SECURITY.md docs/90-transversal/security/SECURITY.md

git add -A && git commit -m "docs: Move SECURITY.md to 90-transversal/security/"
```

---

### Fase 4: Actualizar _MAP.md

**Cambios necesarios:**
```yaml
Metadata:
  updated_date: "2026-01-26"  # Actualizar fecha
  version: "2.2.0"           # Incrementar versión

Métricas:
  Documentación: 98% -> 100%  # Después de ST1-ST3
  Implementación: 25% -> 30%  # Reflejar OQI-006, OQI-007 completados

Secciones nuevas:
  - API Specification (swagger.yml)
  - Endpoint Routing (ENDPOINT-ROUTING.md)
  - Type Coherence (ST1 fixes)
```

---

## Estructura Final Propuesta

```
docs/
├── _MAP.md                          # ✅ Actualizado (ST3.4)
├── README.md                        # ✅ Mantener
│
├── 00-vision-general/
│   ├── ARQUITECTURA-GENERAL.md      # ✅ Consolidado ARCHITECTURE.md aquí
│   └── ...
│
├── 01-arquitectura/
│   ├── ARQUITECTURA-EA-BRIDGE-MT4.md  # ➡️ Movido desde architecture/
│   └── ...
│
├── 02-definicion-modulos/
│   └── OQI-*/                       # ✅ Sin cambios
│
├── 90-transversal/
│   ├── integraciones/
│   │   ├── INT-SERVICES-INTEGRATION.md  # ➡️ Movido desde api-contracts/
│   │   └── ...
│   └── security/
│       └── SECURITY.md              # ➡️ Movido desde raíz
│
├── 99-analisis/
│   └── obsoletos/                   # ❌ Archivos obsoletos (planning/)
│
└── API.md                           # ⚠️ Reducido, referencia swagger.yml
```

---

## Validaciones Post-Reorganización

### Checklist

- [ ] Todos los archivos movidos tienen rutas actualizadas en _MAP.md
- [ ] No quedan carpetas vacías (architecture/, api-contracts/, planning/)
- [ ] Referencias internas actualizadas (links relativos)
- [ ] _MAP.md refleja estructura final
- [ ] Git: 5-7 commits lógicos separados por tipo de cambio

---

## Esfuerzo Real vs Estimado

| Fase | Estimado | Real | Comentarios |
|------|----------|------|-------------|
| ST3.1: Eliminar temporales | 0.5h | 0.25h | ✅ Completado |
| ST3.2: Reorganizar docs/ | 4h | TBD | En progreso |
| ST3.3: Actualizar inventarios | 1.5h | Pendiente | |
| ST3.4: Deployment guide | 2h | Pendiente | |

---

**Total ST3 estimado:** 8h
**Progreso:** 12.5% (ST3.1 completado)