roi-theme/_planificacion/plan-mejora-especificaciones-openspec.md

# Plan de Mejora de Especificaciones OpenSpec - ROI Theme

**Fecha:** 2026-01-08
**Referencia:** Modelo de especificaciones de Aditec (`D:\_Desarrollo\100Aditec\_openspec`)

---

## INSTRUCCIONES DE RECUPERACIÓN (LEER PRIMERO)

> **Si la conversación se compactó, se fue el internet o se apagó la computadora:**

1. **Estado actual:** Ver sección "ESTADO ACTUAL" abajo
2. **Buscar primer `[ ]`:** Ir a la tarea sin marcar
3. **Continuar desde ahí:** No repetir tareas marcadas `[x]`
4. **Marcar `[x]` al completar:** Guardar después de cada cambio

### ESTADO ACTUAL

| Campo | Valor |
|-------|-------|
| **Última actualización** | 2026-01-08 |
| **Última tarea completada** | FASE 3 - Referencias y verificación COMPLETADO |
| **Próxima tarea** | CASO PILOTO P.1 - Crear spec para AntiSpamValidator |
| **Progreso total** | 66/75 tareas |

### Archivos de contexto a leer si es necesario:
- `_planificacion/analisis-spam-formularios.md` - Análisis de spam
- `_planificacion/validacion-specs-vs-codigo-actual.md` - Validación código vs specs
- `_openspec/specs/` - Specs base del proyecto (3 archivos)
- `_openspec/changes/` - Specs de features específicos
- `D:\_Desarrollo\100Aditec\_openspec\` - Referencia de Aditec

---

## CHECKLIST MAESTRO DE PROGRESO

### Estado General
- [x] Análisis de especificaciones Aditec completado
- [x] Comparación ROI Theme vs Aditec completado
- [x] Validación código actual vs especificaciones propuestas
- [x] **FASE 1: Crear archivos faltantes** (COMPLETADO)
- [x] **FASE 2: Expandir archivos existentes** (COMPLETADO)
- [x] **FASE 3: Actualizar referencias** (COMPLETADO)
- [ ] **CASO PILOTO: Implementar anti-spam con nuevo sistema**

---

## FASE 1: CREAR ARCHIVOS FALTANTES

### 1.1 WORKFLOW-ROI-THEME.md (~300 líneas)
**Ubicación:** `_openspec/WORKFLOW-ROI-THEME.md`
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

#### Secciones a crear:
- [x] **1.1.1** Encabezado y metadata (version, fecha)
- [x] **1.1.2** Regla de Oro del proyecto
  - [x] "SI NO EXISTE spec.md → NO SE TOCA CÓDIGO"
  - [x] Explicación de por qué esta regla
- [x] **1.1.3** Flujo de 3 fases obligatorio
  - [x] Fase 1: Proponer (qué archivos se crean)
  - [x] Fase 2: Especificar (qué archivos se crean)
  - [x] Fase 3: Implementar (qué archivos se crean)
- [x] **1.1.4** Flujo de 5 fases para componentes ROI Theme
  - [x] Fase 1: Schema JSON (ubicación, formato, campos obligatorios)
  - [x] Fase 2: Sincronización BD (comando WP-CLI)
  - [x] Fase 3: Renderer (ubicación, patrones, DI)
  - [x] Fase 4: FormBuilder (ubicación, patrones, Design System)
  - [x] Fase 5: Validación (script, qué valida)
- [x] **1.1.5** Agentes disponibles y cuándo usarlos
  - [x] roi-schema-architect
  - [x] roi-renderer-builder
  - [x] roi-form-builder
- [x] **1.1.6** Comandos WP-CLI disponibles
  - [x] sync-component
  - [x] sync-all-components
  - [x] Ejemplos de uso
- [x] **1.1.7** Reglas de Clean Architecture resumidas
  - [x] Qué puede y no puede hacer Domain
  - [x] Qué puede y no puede hacer Application
  - [x] Qué puede y no puede hacer Infrastructure
- [x] **1.1.8** Sección de Lecciones Aprendidas
  - [x] Errores comunes y cómo evitarlos
  - [x] Patrones que funcionan

---

### 1.2 nomenclatura.md (~600 líneas)
**Ubicación:** `_openspec/specs/nomenclatura.md`
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

#### Pre-requisitos:
- [x] **1.2.0** Archivo plano en `_openspec/specs/` (sin carpeta anidada)

#### Secciones a crear:
- [x] **1.2.1** Encabezado y Feature principal
- [x] **1.2.2** Tabla resumen de TODAS las nomenclaturas (vista rápida)
- [x] **1.2.3** Nomenclatura de Carpetas
  - [x] Carpetas principales (Admin/, Public/, Shared/)
  - [x] Carpetas de módulo (PascalCase)
  - [x] Carpetas auxiliares (_planificacion, _arquitectura)
  - [x] Carpetas de capas (Domain/, Application/, Infrastructure/)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.4** Nomenclatura de Archivos PHP
  - [x] Archivos de clase (PascalCase.php)
  - [x] Archivos de interface (PascalCaseInterface.php)
  - [x] Archivos de trait (PascalCaseTrait.php)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.5** Nomenclatura de Archivos JSON (Schemas)
  - [x] Nombres en kebab-case
  - [x] Extensión .json
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.6** Nomenclatura de Namespaces
  - [x] Patrón: ROITheme\[Context]\[Component]\[Layer]
  - [x] Context: Admin, Public, Shared
  - [x] Layer: Domain, Application, Infrastructure
  - [x] Subcapas: Ui, Api, Persistence, Services
  - [x] Ejemplos completos
- [x] **1.2.7** Nomenclatura de Clases
  - [x] Clases regulares (PascalCase)
  - [x] Renderers ([Component]Renderer)
  - [x] FormBuilders ([Component]FormBuilder)
  - [x] UseCases ([Action][Entity]UseCase)
  - [x] Services ([Entity]Service)
  - [x] Repositories ([Entity]Repository)
  - [x] Handlers ([Action]Handler)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.8** Nomenclatura de Interfaces
  - [x] Sufijo Interface o Contract
  - [x] Ubicación en Domain/Contracts/
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.9** Nomenclatura de Métodos
  - [x] Métodos públicos (camelCase)
  - [x] Métodos privados (camelCase)
  - [x] Métodos booleanos (is*, has*, can*, should*)
  - [x] Getters/Setters (get*, set*)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.10** Nomenclatura de Propiedades
  - [x] Propiedades (camelCase)
  - [x] Propiedades booleanas (is*, has*)
  - [x] Visibilidad (private por defecto)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.11** Nomenclatura de Variables
  - [x] Variables locales ($camelCase)
  - [x] Parámetros ($camelCase)
  - [x] Variables de iteración ($item, $key, $i)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.12** Nomenclatura de Constantes
  - [x] Constantes de clase (UPPER_SNAKE_CASE)
  - [x] Constantes globales (ROI_THEME_*)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.13** Nomenclatura de component_name
  - [x] Formato kebab-case en JSON
  - [x] Formato kebab-case en BD
  - [x] Conversión kebab-case ↔ PascalCase
  - [x] Ejemplos de conversión
- [x] **1.2.14** Nomenclatura de Hooks WordPress
  - [x] Actions (roi_theme_*)
  - [x] Filters (roi_theme_filter_*)
  - [x] Ejemplos correctos e incorrectos
- [x] **1.2.15** Validación Pre-commit
  - [x] Checklist de nomenclatura
  - [x] Errores comunes a evitar

---

## FASE 2: EXPANDIR ARCHIVOS EXISTENTES

### 2.1 arquitectura-limpia.md (+485 líneas)
**Ubicación:** `_openspec/specs/arquitectura-limpia.md`
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

#### Secciones a agregar:
- [x] **2.1.1** Diagrama ASCII de las 3 capas
  - [x] Domain (centro, sin dependencias)
  - [x] Application (usa Domain)
  - [x] Infrastructure (usa Application y Domain)
  - [x] Flechas de dependencia
- [x] **2.1.2** Estructura completa de carpetas del tema
  - [x] Árbol completo roi-theme/
  - [x] Explicación de cada carpeta
  - [x] Cuándo crear nuevas carpetas
- [x] **2.1.3** Reglas de anidamiento
  - [x] Profundidad máxima: 4 niveles
  - [x] Regla de 3 archivos para subcarpetas
  - [x] Ejemplos de estructuras válidas e inválidas
- [x] **2.1.4** Diferencia entre niveles de Shared
  - [x] Shared/ (raíz) - código global
  - [x] Admin/Shared/ - compartido solo en Admin
  - [x] Public/Shared/ - compartido solo en Public
  - [x] Cuándo usar cada uno
- [x] **2.1.5** Ejemplos de código PHP por capa
  - [x] Domain: Entidad correcta vs incorrecta
  - [x] Domain: Interface correcta vs incorrecta
  - [x] Application: UseCase correcto vs incorrecto
  - [x] Infrastructure: Repository correcto vs incorrecto
  - [x] Infrastructure: Renderer correcto vs incorrecto
- [x] **2.1.6** Patrones de herencia
  - [x] Herencia para Renderers (si aplica)
  - [x] Herencia para FormBuilders (si aplica)
  - [x] Composición vs Herencia
  - [x] Profundidad máxima de herencia
- [x] **2.1.7** Mapeo de terminología
  - [x] Tabla: Clean Architecture estándar → ROI Theme
  - [x] Entity → Component/Entity
  - [x] UseCase → UseCase
  - [x] Gateway → Repository
  - [x] Presenter → Renderer
- [x] **2.1.8** Validación de arquitectura
  - [x] Script validate-architecture.php
  - [x] Qué valida
  - [x] Cómo ejecutarlo
  - [x] Cómo interpretar errores

---

### 2.2 estandares-codigo.md (+877 líneas)
**Ubicación:** `_openspec/specs/estandares-codigo.md`
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

#### Secciones a agregar:
- [x] **2.2.1** Ejemplos de código PHP para SOLID
  - [x] SRP: Ejemplo correcto vs incorrecto
  - [x] OCP: Ejemplo correcto vs incorrecto
  - [x] LSP: Ejemplo correcto vs incorrecto
  - [x] ISP: Ejemplo correcto vs incorrecto
  - [x] DIP: Ejemplo correcto vs incorrecto
- [x] **2.2.2** Manejo de errores WordPress
  - [x] Cuándo usar wp_die()
  - [x] Cuándo usar WP_Error
  - [x] Cuándo usar excepciones
  - [x] Ejemplos de cada caso
- [x] **2.2.3** Sanitización y validación
  - [x] sanitize_text_field()
  - [x] sanitize_email()
  - [x] absint()
  - [x] wp_kses()
  - [x] Tabla de funciones por tipo de dato
- [x] **2.2.4** Escaping para output
  - [x] esc_html()
  - [x] esc_attr()
  - [x] esc_url()
  - [x] esc_textarea()
  - [x] wp_kses_post()
  - [x] Tabla de funciones por contexto
- [x] **2.2.5** Hooks WordPress
  - [x] add_action() - cuándo y cómo
  - [x] add_filter() - cuándo y cómo
  - [x] Prioridades
  - [x] Número de argumentos
  - [x] Ejemplos correctos
- [x] **2.2.6** Recursos y cleanup
  - [x] Transients (set, get, delete)
  - [x] Object cache
  - [x] Cuándo limpiar recursos
  - [x] Ejemplos
- [x] **2.2.7** Checklist pre-commit detallado
  - [x] Verificaciones de sintaxis
  - [x] Verificaciones de estilo
  - [x] Verificaciones de seguridad
  - [x] Verificaciones de arquitectura
  - [x] Verificaciones de nomenclatura

---

## FASE 3: ACTUALIZAR REFERENCIAS

### 3.1 Actualizar project.md
**Ubicación:** `_openspec/project.md`
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

- [x] **3.1.1** Agregar referencia a WORKFLOW-ROI-THEME.md
- [x] **3.1.2** Agregar referencia a nomenclatura/spec.md
- [x] **3.1.3** Actualizar índice de specs
- [x] **3.1.4** Verificar que links funcionan

### 3.2 Cross-references entre specs
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

- [x] **3.2.1** arquitectura-limpia → nomenclatura (referencias a nombres)
- [x] **3.2.2** estandares-codigo → arquitectura-limpia (referencias a capas)
- [x] **3.2.3** nomenclatura → estandares-codigo (referencias a convenciones)
- [x] **3.2.4** WORKFLOW → todas las specs (referencias a cada fase)

### 3.3 Verificación final
**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

- [x] **3.3.1** Consistencia de ejemplos entre archivos
- [x] **3.3.2** Todos los links funcionan
- [x] **3.3.3** No hay contradicciones entre specs
- [x] **3.3.4** Todos los archivos tienen fecha de actualización

---

## CASO PILOTO: ANTI-SPAM

### Implementación usando nuevo sistema de specs
**Estado:** [ ] NO INICIADO | [ ] EN PROGRESO | [ ] COMPLETADO

- [ ] **P.1** Crear spec para AntiSpamValidator siguiendo WORKFLOW
- [ ] **P.2** Validar que spec cumple nomenclatura
- [ ] **P.3** Validar que spec cumple arquitectura-limpia
- [ ] **P.4** Validar que spec cumple estandares-codigo
- [ ] **P.5** Implementar AntiSpamValidator
- [ ] **P.6** Aplicar a Newsletter Footer
- [ ] **P.7** Aplicar a Contact Form
- [ ] **P.8** Probar que spam es rechazado
- [ ] **P.9** Documentar lecciones aprendidas en WORKFLOW

---

## RESUMEN DE ARCHIVOS A CREAR/MODIFICAR

| # | Archivo | Acción | Líneas | Estado |
|---|---------|--------|--------|--------|
| 1 | `_openspec/WORKFLOW-ROI-THEME.md` | CREAR | ~438 | [x] COMPLETADO |
| 2 | `_openspec/specs/nomenclatura.md` | CREAR | ~687 | [x] COMPLETADO |
| 3 | `_openspec/specs/arquitectura-limpia.md` | EXPANDIR | ~770 | [x] COMPLETADO |
| 4 | `_openspec/specs/estandares-codigo.md` | EXPANDIR | ~1228 | [x] COMPLETADO |
| 5 | `_openspec/project.md` | ACTUALIZAR | ~107 | [x] COMPLETADO |

### Estructura Final
```
_openspec/
├── AGENTS.md
├── WORKFLOW-ROI-THEME.md
├── project.md
├── specs/                    # Solo specs BASE
│   ├── arquitectura-limpia.md
│   ├── estandares-codigo.md
│   └── nomenclatura.md
└── changes/                  # Features/cambios específicos
    ├── add-advanced-incontent-ads/
    ├── adsense-auto-ads-toggle/
    ├── adsense-cache-unified-visibility/
    ├── adsense-javascript-first/
    ├── cache-first-architecture/
    ├── flujo-componentes/
    ├── patrones-wordpress/
    ├── post-grid-shortcode/
    ├── refactor-adsense-lazy-loading/
    └── templates-unificados/
```

---

## MÉTRICAS DE PROGRESO

### Contadores actuales:
- **Tareas FASE 1:** 32/32 completadas
- **Tareas FASE 2:** 23/23 completadas
- **Tareas FASE 3:** 11/11 completadas
- **Tareas PILOTO:** 0/9 completadas
- **TOTAL:** 66/75 tareas completadas

### Al completar:
| Métrica | Antes | Después |
|---------|-------|---------|
| Total líneas specs | ~1021 | ~2200 |
| Archivos fundamentales | 3/5 | 5/5 |
| Diagramas ASCII | 0 | 3+ |
| Ejemplos código | ~5 | ~30 |
| Checklists | 1 parcial | 3 completos |

---

**Fin del documento**