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

• Análisis de especificaciones Aditec completado
• Comparación ROI Theme vs Aditec completado
• Validación código actual vs especificaciones propuestas
• FASE 1: Crear archivos faltantes (COMPLETADO)
• FASE 2: Expandir archivos existentes (COMPLETADO)
• 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:

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

• 1.2.0 Archivo plano en _openspec/specs/ (sin carpeta anidada)

Secciones a crear:

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

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

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

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

3.2 Cross-references entre specs

Estado: [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO

• 3.2.1 arquitectura-limpia → nomenclatura (referencias a nombres)
• 3.2.2 estandares-codigo → arquitectura-limpia (referencias a capas)
• 3.2.3 nomenclatura → estandares-codigo (referencias a convenciones)
• 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

• 3.3.1 Consistencia de ejemplos entre archivos
• 3.3.2 Todos los links funcionan
• 3.3.3 No hay contradicciones entre specs
• 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