Specialized Reviews Proposal

<!-- FILE: drafts/specialized_reviews_proposal.md -->Specialized Reviews Proposal

Estado

Draft para revisión por Coordinator.

Objetivo

Proponer la incorporación en AVANZIRA_DEV de ciclos PDCA especializados para mejorar la calidad estructural del sistema antes de fases relevantes como deploy, migraciones, refactors grandes o cambios de arquitectura.

El objetivo no es generar más documentación, sino mejorar:

- mantenibilidad

- migrabilidad

- optimización

- orden del repo

- calidad del contexto para agentes IA

- reducción de consumo de tokens

- trazabilidad de decisiones

- preparación para deploy

---

1. Decisión principal

Se propone añadir tres ciclos PDCA especializados:

PDCA_REPO_5S

PDCA_KNOWLEDGE_CONSOLIDATION

PDCA_TECHNICAL_DESIGN_REVIEW

Estos ciclos no sustituyen al "PDCA_STANDARD".

Tampoco forman parte obligatoria de cada ciclo normal.

Deben ser invocados por el "Coordinator" según contexto, riesgo, coste y beneficio esperado.

---

2. Principio rector

Los ciclos especializados deben usarse solo cuando aporten valor claro.

Regla propuesta:

No ejecutar revisiones pesadas por rutina.

Ejecutarlas cuando reduzcan riesgo, deuda técnica, desorden documental o coste futuro.

---

3. Ubicación propuesta en AVANZIRA_DEV

MANUAL

└── Governance

    └── Continuous Improvement Reviews

PROCEDURES

└── PDCA_STANDARD

SPECIALIZED_REVIEWS

├── PDCA_REPO_5S

├── PDCA_KNOWLEDGE_CONSOLIDATION

└── PDCA_TECHNICAL_DESIGN_REVIEW

---

4. Responsabilidad del Coordinator

El "Coordinator" debe evaluar si procede lanzar ciclos especializados antes de:

- deploy relevante

- migración tecnológica

- refactor grande

- reestructuración del repo

- creación de una nueva versión en otro lenguaje

- acumulación visible de documentación

- pérdida de claridad en fuentes de verdad

- caída de métricas de calidad, deploy o mantenibilidad

El Coordinator no debe lanzar estos ciclos automáticamente si el coste supera el beneficio.

---

5. Ciclo PDCA_REPO_5S

Objetivo

Mantener el repo ordenado, limpio, navegable y apto para trabajo multiagente.

Pregunta central

¿Está el repo suficientemente ordenado para que humanos y agentes trabajen con bajo ruido?

Revisión

Aplicar 5S al repo:

5S| Aplicación en software

Seiri| separar útil, obsoleto, duplicado, experimental

Seiton| ordenar carpetas, módulos, nombres y responsabilidades

Seiso| limpiar ruido, imports, archivos muertos, duplicidades

Seiketsu| estandarizar estructura, plantillas y convenciones

Shitsuke| mantener disciplina mediante checks y gates

Frecuencia

Alta o media.

Puede ejecutarse antes que el Technical Design Review.

---

6. Ciclo PDCA_KNOWLEDGE_CONSOLIDATION

Objetivo

Reducir contexto, tokens y documentación redundante.

Pregunta central

¿Tenemos demasiadas fuentes de verdad o demasiado contexto para los agentes?

Revisión

Detectar:

- documentación duplicada

- documentos obsoletos

- solapamiento entre manuales

- decisiones repetidas

- instrucciones contradictorias

- exceso de artefactos

- contexto innecesario para minions

- archivos largos que deberían resumirse o dividirse

Resultado esperado

Consolidar conocimiento en fuentes de verdad mínimas.

Este ciclo debe proteger a AVANZIRA_DEV contra el crecimiento descontrolado de ".md".

---

7. Ciclo PDCA_TECHNICAL_DESIGN_REVIEW

Objetivo

Evaluar arquitectura, patrones, SOLID, estructuras de datos, migrabilidad y capacidad de optimización.

Pregunta central

¿La arquitectura actual permite mantener, migrar, optimizar y escalar el sistema con bajo riesgo?

Revisión

Analizar:

- arquitectura general

- separación de responsabilidades

- acoplamiento

- cohesión

- duplicación lógica

- estructuras de datos

- contratos entre módulos

- patrones de diseño aplicables

- principios SOLID

- migrabilidad Python → Rust u otros escenarios

- readiness para deploy

- AI Readiness

Patrones iniciales a considerar

- Singleton

- Observer

- Factory

- Strategy

- Decorator

- Builder

Regla:

No proponer patrones por estética.

Cada patrón debe resolver un problema real detectado.

---

8. Relación entre ciclos

Orden recomendado cuando proceda una revisión completa:

1. PDCA_REPO_5S

2. PDCA_KNOWLEDGE_CONSOLIDATION

3. PDCA_TECHNICAL_DESIGN_REVIEW

4. PDCA_DEPLOY_REVIEW

5. Deploy

No siempre deben ejecutarse todos.

El Coordinator debe decidir.

---

9. Gestión de artefactos

Principio aprobado:

Los artefactos también son deuda técnica.

Regla propuesta:

Ningún ciclo puede crear nuevos tipos de artefactos sin justificar por qué los artefactos existentes no son suficientes.

Artefactos máximos recomendados por ciclo:

findings.yml

improvement_plan.md

decision_log.md

Los informes extensos deben ser temporales o resumidos.

---

10. Clasificación de hallazgos

Cada hallazgo debe incluir:

id:

title:

type:

scope:

severity:

impact:

effort:

roi:

risk:

confidence:

recommendation:

status:

Valores sugeridos:

low

medium

high

critical

Estados sugeridos:

discarded

backlog

proposed

approved

rejected

deferred

implemented

verified

---

11. Filtrado de hallazgos

Los hallazgos con puntuaciones bajas no deben pasar al gate humano.

Regla propuesta:

Si impact, roi o confidence son bajos, el hallazgo se descarta o queda en backlog.

Objetivo:

Evitar que el gate humano se llene de ruido.

---

12. Criterio anti-sobreingeniería

No aplicar patrones si la solución simple es mejor.

Ejemplos:

No usar Factory si solo hay dos variantes simples y estables.

No usar Singleton para estado mutable global salvo justificación fuerte.

No usar Strategy si un if simple es más claro y no hay crecimiento previsto.

No usar Decorator si el middleware existente ya resuelve el problema.

No usar Builder si la construcción del objeto sigue siendo clara.

---

13. AI Readiness

Añadir una dimensión específica de evaluación:

AI Readiness

Debe valorar:

- facilidad para entender el repo

- claridad de estructura

- fuentes de verdad

- tamaño del contexto necesario

- trazabilidad de decisiones

- facilidad para asignar tareas a minions

- separación entre documentación humana y contexto operativo para agentes

---

14. Propuesta para el Coordinator

El Coordinator debe revisar esta propuesta y producir:

1. Evaluación de compatibilidad con AVANZIRA_DEV actual.

2. Propuesta de ubicación exacta en manuales y procedimientos.

3. Cambios mínimos necesarios.

4. Definición inicial de los tres ciclos especializados.

5. Reglas de invocación.

6. Política de límite de artefactos.

7. Política de filtrado de hallazgos.

8. Propuesta para gate humano.

---

15. Pregunta abierta

Pendiente de decisión:

¿PDCA_KNOWLEDGE_CONSOLIDATION debe ser ciclo independiente

o variante especializada de PDCA_REPO_5S?

Recomendación inicial:

Mantenerlo como ciclo independiente,

pero permitir que PDCA_REPO_5S lo recomiende cuando detecte exceso documental.

---

16. Resultado esperado

Tras revisar este draft, el Coordinator debe entregar una propuesta concreta para integrar los ciclos especializados en AVANZIRA_DEV sin aumentar innecesariamente la carga documental ni el consumo de tokens.

<!-- END FILE: drafts/specialized_reviews_proposal.md -->