template-saas/orchestration/analisis/FASE-5-PLAN-REFINADO-DOCUMENTACION-2026-01-10.md

# FASE 5: PLAN REFINADO - DOCUMENTACION TEMPLATE-SAAS

**Fecha:** 2026-01-10
**Proyecto:** template-saas
**Estado:** COMPLETADO
**Perfil:** ORQUESTADOR (TECH-LEADER)
**Referencia:** FASE-4-VALIDACION-PLAN-DOCUMENTACION-2026-01-10.md

---

## 1. AJUSTES INCORPORADOS

### 1.1 Cambios desde FASE-4

| # | Ajuste | Razon | Impacto |
|---|--------|-------|---------|
| A1 | Agregar docs/02-especificaciones/_MAP.md | Gap G1 faltante | +1 archivo Wave 1 |
| A2 | Agregar docs/02-integraciones/_MAP.md | Gap G1 faltante | +1 archivo Wave 1 |
| A3 | Mover ADR-006 a Wave 3.pre | Dependencia ET-SAAS-006 | Reorden Wave 3/4 |

### 1.2 Totales Actualizados

| Metrica | Plan Original | Plan Refinado | Delta |
|---------|---------------|---------------|-------|
| Archivos a modificar | 33 | 35 | +2 |
| Archivos a crear | 19 | 19 | 0 |
| **TOTAL** | **52** | **54** | **+2** |

---

## 2. PLAN REFINADO DE EJECUCION

### WAVE 1: FRONTMATTER YAML (28 archivos)

**Objetivo:** Agregar frontmatter YAML SIMCO a todos los archivos de documentacion.

#### Subwave 1.1: docs/00-vision-general/ (4 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.1.1 | README.md | VIS-001 | Agregar frontmatter |
| 1.1.2 | VISION-TEMPLATE-SAAS.md | VIS-002 | Agregar frontmatter |
| 1.1.3 | ESPECIFICACION-PLATAFORMA-SAAS.md | VIS-003 | Agregar frontmatter |
| 1.1.4 | ARQUITECTURA-MULTI-TENANT.md | VIS-004 | Agregar frontmatter |

#### Subwave 1.2: docs/02-especificaciones/ (3 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.2.1 | ET-SAAS-007-notifications-v2.md | ET-SAAS-007 | Agregar frontmatter |
| 1.2.2 | PLAN-IMPLEMENTACION-NOTIFICATIONS-V2.md | PLAN-SAAS-007 | Agregar frontmatter |
| 1.2.3 | _MAP.md | MAP-SPECS | **NUEVO** - Crear con frontmatter |

#### Subwave 1.3: docs/02-integraciones/ (8 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.3.1 | INT-001-stripe.md | INT-001 | Agregar frontmatter |
| 1.3.2 | INT-002-oauth.md | INT-002 | Agregar frontmatter |
| 1.3.3 | INT-003-email.md | INT-003 | Agregar frontmatter |
| 1.3.4 | INT-004-push.md | INT-004 | Agregar frontmatter |
| 1.3.5 | INT-005-storage.md | INT-005 | Agregar frontmatter |
| 1.3.6 | INT-006-webhooks.md | INT-006 | Agregar frontmatter |
| 1.3.7 | INT-007-redis.md | INT-007 | Agregar frontmatter |
| 1.3.8 | _MAP.md | MAP-INT | **NUEVO** - Crear con frontmatter |

#### Subwave 1.4: docs/02-devops/ (2 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.4.1 | CICD-GUIDE.md | DEVOPS-001 | Agregar frontmatter |
| 1.4.2 | _MAP.md | MAP-DEVOPS | Agregar frontmatter |

#### Subwave 1.5: docs/architecture/adr/ (6 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.5.1 | ADR-001-multi-tenancy-rls.md | ADR-001 | Agregar frontmatter |
| 1.5.2 | ADR-002-authentication-jwt-oauth.md | ADR-002 | Agregar frontmatter |
| 1.5.3 | ADR-003-billing-stripe.md | ADR-003 | Agregar frontmatter |
| 1.5.4 | ADR-004-notifications-realtime.md | ADR-004 | Agregar frontmatter |
| 1.5.5 | ADR-005-feature-flags.md | ADR-005 | Agregar frontmatter |
| 1.5.6 | _INDEX.md | INDEX-ADR | Agregar frontmatter |

#### Subwave 1.6: docs/ raiz (2 archivos)

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.6.1 | README.md | DOCS-ROOT | Agregar frontmatter |
| 1.6.2 | _MAP.md | MAP-DOCS | Agregar frontmatter |

#### Subwave 1.7: docs/01-modulos/ - Solo _INDEX.md

| # | Archivo | ID | Accion |
|---|---------|-----|--------|
| 1.7.1 | _INDEX.md | INDEX-SAAS | Verificar frontmatter |

**Total Wave 1:** 28 archivos

---

### WAVE 2: CONTENIDO INTEGRACIONES (7 archivos)

**Objetivo:** Expandir las 7 integraciones con secciones SIMCO faltantes.

#### Detalle por Archivo

| # | Archivo | Secciones a Agregar |
|---|---------|---------------------|
| 2.1 | INT-001-stripe.md | Endpoints (17), Fallbacks, Credenciales |
| 2.2 | INT-002-oauth.md | Fallbacks |
| 2.3 | INT-003-email.md | (verificar completitud) |
| 2.4 | INT-004-push.md | Fallbacks |
| 2.5 | INT-005-storage.md | Fallbacks |
| 2.6 | INT-006-webhooks.md | DLQ Strategy |
| 2.7 | INT-007-redis.md | Endpoints (18), Fallbacks |

**Total Wave 2:** 7 archivos

---

### WAVE 3: ESPECIFICACIONES TECNICAS + ADR-006 (14 archivos)

**Objetivo:** Crear 13 ETs y ADR-006 (prerequisito para ET-SAAS-006).

#### Subwave 3.0: ADR Prerequisito

| # | Archivo | Ubicacion |
|---|---------|-----------|
| 3.0.1 | ADR-006-ai-integration-multi-provider.md | docs/architecture/adr/ |

#### Subwave 3.1-3.13: Especificaciones Tecnicas

| # | Archivo | Modulo Base |
|---|---------|-------------|
| 3.1 | ET-SAAS-001-authentication.md | SAAS-001 |
| 3.2 | ET-SAAS-002-multi-tenancy.md | SAAS-002 |
| 3.3 | ET-SAAS-003-users-rbac.md | SAAS-003 |
| 3.4 | ET-SAAS-004-billing.md | SAAS-004 |
| 3.5 | ET-SAAS-005-plans.md | SAAS-005 |
| 3.6 | ET-SAAS-006-ai-integration.md | SAAS-006 |
| 3.7 | ET-SAAS-008-audit-logs.md | SAAS-008 |
| 3.8 | ET-SAAS-009-feature-flags.md | SAAS-009 |
| 3.9 | ET-SAAS-010-webhooks.md | SAAS-010 |
| 3.10 | ET-SAAS-011-storage.md | SAAS-011 |
| 3.11 | ET-SAAS-012-crud-base.md | SAAS-012 |
| 3.12 | ET-SAAS-013-email.md | SAAS-013 |
| 3.13 | ET-SAAS-014-whatsapp.md | SAAS-014 |

**Total Wave 3:** 14 archivos

---

### WAVE 4: ADRs RESTANTES (5 archivos)

**Objetivo:** Crear 5 ADRs restantes (ADR-007 a ADR-011).

| # | Archivo | Tema |
|---|---------|------|
| 4.1 | ADR-007-storage-abstraction-layer.md | Storage multi-provider |
| 4.2 | ADR-008-webhook-retry-strategy.md | BullMQ + backoff |
| 4.3 | ADR-009-whatsapp-business-integration.md | Meta Cloud API |
| 4.4 | ADR-010-audit-log-retention-policy.md | Tiered retention |
| 4.5 | ADR-011-rate-limiting-strategy.md | Token bucket Redis |

**Total Wave 4:** 5 archivos

---

### WAVE 5: ACTUALIZACION DE INDICES

**Objetivo:** Actualizar todos los archivos _INDEX y _MAP con nuevos documentos.

| # | Archivo | Agregar |
|---|---------|---------|
| 5.1 | docs/architecture/adr/_INDEX.md | ADR-006 a ADR-011 |
| 5.2 | docs/02-especificaciones/_MAP.md | 13 ET-SAAS-* |
| 5.3 | docs/_MAP.md | Referencias actualizadas |

**Total Wave 5:** 3 archivos

---

## 3. CRONOGRAMA DE EJECUCION REFINADO

| Wave | Descripcion | Archivos | Dependencias | Orden |
|------|-------------|----------|--------------|-------|
| Wave 1 | Frontmatter YAML | 28 | Ninguna | 1ro |
| Wave 2 | Contenido INT | 7 | Wave 1 completa | 2do |
| Wave 3 | ETs + ADR-006 | 14 | Wave 1, 2 | 3ro |
| Wave 4 | ADRs 007-011 | 5 | Wave 3 | 4to |
| Wave 5 | Indices | 3 | Wave 3, 4 | 5to |
| **TOTAL** | | **57** | | |

---

## 4. TEMPLATES FINALES

### 4.1 Template Frontmatter General

```yaml
---
id: "{PREFIJO}-{NNN}"
title: "{Titulo descriptivo}"
type: "{Overview|Vision|Specification|Integration|ADR|Index|Guide}"
status: "{Draft|InReview|Approved|Published|Deprecated}"
priority: "{P0|P1|P2|P3}"
version: "1.0.0"
created_date: "2026-01-10"
updated_date: "2026-01-10"
---
```

### 4.2 Template Frontmatter Integracion

```yaml
---
id: "INT-{NNN}"
title: "Integracion {Nombre}"
type: "Integration"
status: "{Implemented|Documented|Roadmap}"
priority: "{P0|P1|P2}"
provider: "{Nombre provider}"
category: "{Payments|Auth|Notifications|Storage|Infrastructure}"
multi_tenant: {true|false}
version: "1.0.0"
created_date: "2026-01-10"
updated_date: "2026-01-10"
---
```

### 4.3 Template Frontmatter ET

```yaml
---
id: "ET-SAAS-{NNN}"
title: "Especificacion Tecnica {Modulo}"
type: "TechnicalSpec"
status: "{Draft|Published}"
priority: "P0"
module: "{nombre_modulo}"
version: "1.0.0"
created_date: "2026-01-10"
updated_date: "2026-01-10"
---
```

### 4.4 Template Frontmatter ADR

```yaml
---
id: "ADR-{NNN}"
title: "{Titulo decision}"
type: "ADR"
status: "{Proposed|Accepted|Deprecated|Superseded}"
priority: "P0"
supersedes: "N/A"
superseded_by: "N/A"
version: "1.0.0"
created_date: "2026-01-10"
updated_date: "2026-01-10"
---
```

### 4.5 Template _MAP.md

```markdown
---
id: "MAP-{AREA}"
title: "Mapa {Area}"
type: "Index"
status: "Published"
priority: "P2"
version: "1.0.0"
created_date: "2026-01-10"
updated_date: "2026-01-10"
---

# Mapa de {Area}

## Documentos

| Archivo | Descripcion | Estado |
|---------|-------------|--------|
| ... | ... | ... |

## Referencias

- [Documento relacionado](ruta)

---

**Ultima actualizacion:** 2026-01-10
```

---

## 5. VALIDACIONES POR WAVE

### 5.1 Validacion Wave 1

```bash
# Verificar frontmatter en todos los archivos
grep -l "^---" docs/**/*.md | wc -l  # Debe ser >= 28

# Verificar IDs unicos
grep -h "^id:" docs/**/*.md | sort | uniq -d  # Debe estar vacio
```

### 5.2 Validacion Wave 2

```bash
# Verificar secciones en INT
for f in docs/02-integraciones/INT-*.md; do
  echo "=== $f ==="
  grep -c "## Rate Limits\|## Fallbacks\|## Multi-tenant" "$f"
done
```

### 5.3 Validacion Wave 3

```bash
# Verificar ETs creadas
ls docs/02-especificaciones/ET-SAAS-*.md | wc -l  # Debe ser 14

# Verificar estructura ET
for f in docs/02-especificaciones/ET-SAAS-*.md; do
  grep -c "## Arquitectura\|## Modelo de Datos\|## API Endpoints" "$f"
done
```

### 5.4 Validacion Wave 4

```bash
# Verificar ADRs
ls docs/architecture/adr/ADR-*.md | wc -l  # Debe ser 11

# Verificar estructura ADR
for f in docs/architecture/adr/ADR-*.md; do
  grep -c "## Contexto\|## Decision\|## Alternativas" "$f"
done
```

### 5.5 Validacion Wave 5

```bash
# Verificar _INDEX.md actualizado
grep -c "ADR-006\|ADR-007" docs/architecture/adr/_INDEX.md  # Debe ser >= 2
```

---

## 6. METRICAS OBJETIVO

### 6.1 Antes vs Despues

| Metrica | Antes | Despues |
|---------|-------|---------|
| Archivos con frontmatter | 14 | 42 |
| Integraciones completas | 0 | 7 |
| ET Specs | 1 | 14 |
| ADRs | 5 | 11 |
| _MAP.md actualizados | 2 | 5 |
| Cobertura SIMCO | ~80% | 100% |

### 6.2 KPIs de Ejecucion

| KPI | Objetivo |
|-----|----------|
| Archivos sin errores YAML | 100% |
| Links validos | 100% |
| IDs unicos | 100% |
| Secciones completas | 100% |

---

## 7. RIESGOS MITIGADOS

| Riesgo Original | Mitigacion Aplicada | Estado |
|-----------------|---------------------|--------|
| Archivos _MAP faltantes | Agregados a Wave 1 | [x] |
| Dependencia circular | ADR-006 movido a Wave 3.0 | [x] |
| IDs duplicados | Template con prefijos unicos | [x] |
| Links rotos | Validacion post-wave | [x] |

---

## 8. RESUMEN DEL PLAN REFINADO

### Cambios vs Plan Original

| Aspecto | Original | Refinado |
|---------|----------|----------|
| Total archivos | 52 | 54 |
| Waves | 4 | 5 |
| Subwaves Wave 1 | 6 | 7 |
| Orden Wave 3/4 | Separados | ADR-006 en Wave 3 |

### Estructura Final

```
WAVE 1: Frontmatter (28 archivos)
  └── 7 subwaves por ubicacion

WAVE 2: Contenido INT (7 archivos)
  └── Secciones SIMCO faltantes

WAVE 3: ETs + ADR-006 (14 archivos)
  ├── 3.0: ADR-006 (prerequisito)
  └── 3.1-3.13: ET-SAAS-*

WAVE 4: ADRs 007-011 (5 archivos)
  └── Decisiones arquitectonicas

WAVE 5: Indices (3 archivos)
  └── _INDEX y _MAP actualizados
```

---

## 9. APROBACION PARA EJECUCION

| Criterio | Estado |
|----------|--------|
| Ajustes FASE-4 incorporados | [x] |
| Templates definidos | [x] |
| Validaciones definidas | [x] |
| Dependencias resueltas | [x] |
| Metricas objetivo claras | [x] |

**DECISION:** Plan APROBADO para ejecucion en FASE 6

---

**Creado:** 2026-01-10
**Autor:** Claude Code (ORQUESTADOR)
**Sistema:** SIMCO v3.7
**Siguiente Fase:** FASE 6 - Ejecucion del Plan