Bucle de Revisión
Ciclo iterativo trabajador-revisor dentro de una misma sesión. Tú haces el trabajo, lanzas un subagente revisor para que lo critique, revisas basándote en la retroalimentación, repites hasta cumplir el umbral de calidad.
Principio fundamental: Los primeros borradores nunca son definitivos. La crítica iterativa produce mejores resultados que un único intento.
Nota sobre la plataforma: Este skill funciona mejor con agentes que soportan lanzamiento de subagentes. En plataformas sin esa capacidad, simula el paso de revisor abriendo un nuevo contexto de chat, pegando solo el producto del trabajo (sin razonamiento previo) y pidiéndole que puntúe del 1 al 10 con retroalimentación específica.
Inicio Rápido
- Di:
"implementa X, usa bucle-de-revisión"o"ejecuta bucle-de-revisión en el archivo que acabo de escribir" - El agente realiza el trabajo (o lee el trabajo existente)
- Un subagente crítico separado lo puntúa del 1 al 10 con retroalimentación específica
- El agente revisa y repite hasta que la puntuación sea >= 8 (umbral de calidad por defecto)
- Se entrega un resumen del bucle con el resultado final
Cuándo Usarlo
- El usuario dice "usa bucle-de-revisión", "pule esto", "itera sobre esto", "/bucle-de-revisión"
- Implementaciones complejas donde la calidad importa más que la velocidad
- Documentos de diseño, especificaciones o escritura técnica
- Código que debe ser robusto (seguridad, pipelines de datos, lógica financiera)
- Cuando el usuario quiere una crítica adversarial integrada en el proceso
Cuándo NO Usarlo
- Correcciones simples, ediciones rápidas, cambios de una línea
- Tareas donde las pruebas son el umbral de calidad (usa TDD + CI en su lugar)
- Cuando el usuario solo quiere que se haga rápido
- Trabajo exploratorio/de prueba donde el objetivo es aprender, no entregar
- Tareas sin criterios de aceptación claros — defínelos primero, luego usa bucle-de-revisión
Valores por Defecto
| Configuración | Valor por Defecto |
|---|---|
| Mínimo de bucles | 2 |
| Máximo de bucles | 4 |
| Umbral de calidad | 8/10 |
| Modelo trabajador | (tu modelo actual) |
| Modelo revisor | (tu modelo actual o alternativa rápida/equilibrada) |
Selección del Modelo
La tarea del revisor evalúa la lógica y las restricciones. La tarea del trabajador escribe y modifica código. Elige las capacidades del subagente en consecuencia.
REGLAS CRÍTICAS: El revisor debe ser SIEMPRE IGUAL o MÁS POTENTE que el trabajador. Si el revisor es más débil que el trabajador, no podrá criticar adecuadamente la lógica compleja ni detectar regresiones sutiles.
| Complejidad de la Tarea | Capacidad del Trabajador | Capacidad del Revisor | Razón |
|---|---|---|---|
| Simple/mecánica (CRUD, formato, plantillas) | Rápido / Ligero | Equilibrado | El trabajador ligero es rápido, el revisor equilibrado detecta problemas fácilmente |
| Estándar (funcionalidades, refactorizaciones, documentación) | Equilibrado | Equilibrado | Buen equilibrio entre coste, velocidad y calidad |
| Compleja (multifile, integración, diseño) | Equilibrado | Avanzado / Razonamiento | El revisor avanzado detecta problemas de arquitectura sutiles, el trabajador equilibrado los implementa |
| Muy compleja (seguridad, cuantitativa, sistemas distribuidos) | Avanzado / Razonamiento | Avanzado / Razonamiento | Ambos necesitan contexto completo y capacidad de razonamiento. El revisor DEBE igualar la potencia del trabajador. |
La regla de oro: El trabajador debe ser lo suficientemente inteligente para ACTUAR según la retroalimentación del revisor. Si el revisor dice "arregla la condición de carrera con un semáforo basado en canales" y el trabajador no puede razonar sobre concurrencia, el bucle no convergerá.
Señal de escalada: Si la puntuación no mejora después de 2 bucles consecutivos con la misma retroalimentación, el modelo trabajador es demasiado débil. Escala:
- Opción A: Pide al usuario que cambie a un modelo más capaz
- Opción B: Baja temporalmente el umbral de calidad y notifica la diferencia al usuario
- Opción C: Divide la tarea en subtareas más pequeñas y ejecuta bucle-de-revisión en cada una
Comportamiento por defecto: Dado que tú (el agente principal) ERES el trabajador, lanza un subagente revisor que iguale o supere tu capacidad actual según la tarea:
- La mayoría de las tareas → Revisor Estándar/Equilibrado
- Tareas especializadas/difíciles → Revisor Avanzado/Razonamiento
- Verificaciones rápidas → Revisor Rápido/Ligero (solo si también actúas como trabajador ligero)
Anulaciones del Usuario
Los usuarios pueden anular cualquier valor por defecto en línea con su solicitud. Analízalos de forma natural:
"implementa X con bucle-de-revisión, umbral de calidad 9, usa modelo avanzado para revisión, máximo 5 bucles"
"pule esto, mínimo 2 bucles, umbral en 8"
"ejecuta bucle-de-revisión con revisor rápido, máximo 2 bucles"
"usa bucle-de-revisión, revisor de razonamiento, umbral de calidad 9, mínimo 3 máximo 6"
Reglas de análisis:
- "umbral de calidad N" o "gate N" → quality_gate = N
- "revisor [modelo]" o "revisa con [modelo]" → anulación del modelo revisor
- "máximo N bucles" → max_loops = N
- "mínimo N bucles" → min_loops = N
- Si el usuario no especifica, usa los valores por defecto
- Si el usuario dice "exhaustivo" o "estricto" → interpreta como quality_gate 8, min_loops 2
- Si el usuario dice "rápido" o "rápido" → interpreta como max_loops 2, quality_gate 6
El Proceso
flowchart TD
A[Haz el trabajo] --> B[Lanza subagente revisor]
B --> C{¿Mínimo de bucles cumplido?}
C -- no, siempre continuar --> E[Revisa según retroalimentación]
C -- sí --> D{¿Puntuación >= umbral de calidad?}
D -- sí --> F[Paso final de pulido]
D -- no --> G{¿Máximo de bucles alcanzado?}
G -- sí, detener de todas formas --> F
G -- no --> E
E --> B
F --> H([Listo])
Paso a Paso
Paso 1: Haz el Trabajo
Completa la tarea como lo harías normalmente. Escribe el código, crea la especificación, implementa la funcionalidad. No te contengas: produce tu mejor primer intento.
Paso 2: Lanza el Subagente Revisor
Usa la herramienta Agente para enviar un revisor. El revisor debe:
- Ser un subagente separado (contexto nuevo, sin anclaje a tu razonamiento)
- Recibir solo el producto del trabajo (archivos, diferencias) — no tu proceso de pensamiento
- Puntuar del 1 al 10 con retroalimentación específica y procesable
- Usar un modelo equilibrado/estándar por defecto (o un modelo de razonamiento avanzado para tareas complejas/especializadas)
Plantilla de mensaje para el revisor:
Eres un revisor crítico. Puntúa el siguiente trabajo del 1 al 10 y proporciona retroalimentación específica y procesable.
## Qué se hizo
{breve descripción de la tarea}
## Criterios de revisión
{criterios específicos de la tarea — qué importa para ESTA tarea}
Ejemplos de criterios bien escritos:
Para un endpoint de API REST:
- Códigos de estado HTTP correctos utilizados
- Validación de entrada presente en todos los parámetros
- Autenticación aplicada; sin acceso no autenticado
- Sin patrones de consulta N+1
Para un documento de diseño:
- La declaración del problema no es ambigua
- Alternativas consideradas con concesiones
- Sin simplificaciones excesivas sobre la complejidad de la implementación
- Las métricas de éxito son medibles
Para un pipeline de datos:
- Idempotente — seguro de re-ejecutar
- Los cambios de esquema se manejan con gracilidad
- Modos de fallo documentados
- Tratamiento de PII abordado
## Instrucciones
1. Lee el trabajo cuidadosamente
2. Puntúa del 1 al 10 donde:
- 1-3: Fundamentalmente roto o faltan requisitos importantes
- 4-6: Funciona pero tiene problemas significativos
- 7-8: Bueno, solo problemas menores
- 9-10: Excelente, listo para enviar
3. Enumera problemas específicos con referencias de archivo:línea cuando sea aplicable
4. Para cada problema, explica POR QUÉ importa y QUÉ corregir
5. No seas educado — sé honesto y directo
6. Indica tu puntuación claramente como "Puntuación: N/10"
## Archivos a revisar
{pega el contenido de los archivos o lista las rutas de archivos con extractos relevantes}
Paso 3: Analiza la Retroalimentación
De la respuesta del revisor, extrae:
- Puntuación (el número)
- Problemas (categorizados como Críticos / Importantes / Menores)
- Correcciones específicas (qué cambiar)
Informa al usuario:
Bucle {N}/{máx}: Puntuación {X}/10
- {resumen de los puntos clave de retroalimentación}
Paso 4: Verifica las Condiciones de Parada
En este orden:
- Si los bucles completados < bucles_mínimos → continuar (siempre)
- Si puntuación >= umbral_de_calidad → detener, ir al pulido final
- Si bucles completados >= bucles_máximos → detener, ir al pulido final
- De lo contrario → revisar y repetir
Paso 5: Revisa
Aborda la retroalimentación del revisor. Corrige los problemas Críticos e Importantes. Los problemas Menores son opcionales. Luego vuelve al Paso 2.
Importante: Cada revisión debe ser específica. No reescribas todo — corrige lo que el revisor señaló. Mantén una lista mental de TODA la retroalimentación anterior para evitar regresiones.
Paso 6: Pulido Final
Una vez que el bucle salga (se cumpla el umbral de calidad o se alcance el máximo de bucles):
- Aborda cualquier problema menor restante si es trivial
- Verifica que el resultado final sea coherente (sin artefactos de los ciclos de revisión)
- Informa la puntuación final y el conteo de bucles al usuario
Adaptación de los Criterios del Revisor por Tipo de Tarea
| Tipo de Tarea | El Revisor Debe Centrarse En |
|---|---|
| Código | Corrección, casos límite, manejo de errores, legibilidad, sin problemas de seguridad |
| Especificación/Diseño | Completitud, viabilidad, sin simplificaciones excesivas, implementabilidad |
| Refactorización | Sin cambios de comportamiento, sin regresiones, más limpio que antes |
| Escritura | Claridad, estructura, adecuado para la audiencia, sin relleno |
| Corrección de errores | Causa raíz abordada, existe prueba de regresión, sin efectos secundarios |
| Infraestructura / IaC | Idempotencia, mínimo privilegio, sin secretos hardcodeados, seguridad de destrucción |
| Migración de base de datos | Reversibilidad, estrategia de índices, riesgo de pérdida de datos, rendimiento a escala |
| Diseño de API | Compatibilidad hacia atrás, autenticación, versionado, contrato de errores |
| Suite de pruebas | Cobertura de casos límite, sin interdependencia de pruebas, aserciones significativas |
Dos Modos de Operación
Modo A: "Hacer y Revisar" (ciclo completo)
El usuario da una tarea + dice que use bucle-de-revisión. Tú haces el trabajo Y ejecutas el bucle de revisión.
Usuario: "Implementa la capa de caché. Usa bucle-de-revisión, umbral de calidad 8."
Tú:
1. Implementas la capa de caché
2. Lanzas revisor → Puntuación 6, retroalimentación: falta desalojo, sin TTL
3. Revisas: añades desalojo + TTL
4. Lanzas revisor → Puntuación 8, retroalimentación: pequeño detalle de nombres
5. Pulido final, listo
Modo B: "Revisar Existente" (solo revisión)
El usuario ya hizo el trabajo o tú ya lo hiciste. Simplemente ejecuta el bucle de revisión sobre lo que existe.
Usuario: "Ejecuta bucle-de-revisión en el módulo de autenticación que acabo de escribir"
Tú:
1. Lees el módulo de autenticación
2. Lanzas revisor → Puntuación 5, retroalimentación: inyección SQL, sin limitación de tasa
3. Corriges: parametrizas consultas, añades limitador de tasa
4. Lanzas revisor → Puntuación 8, aprobado
5. Listo
Señales de Alarma
Nunca:
- Auto-revisarte en lugar de lanzar un subagente (sesgo de anclaje)
- Saltarte un ciclo de revisión porque "la retroalimentación es incorrecta" sin justificación
- Inflar tu propia puntuación ("Creo que esto es en realidad un 9")
- Continuar más allá del máximo de bucles sin el consentimiento del usuario
- Lanzar al revisor con todo tu razonamiento/historial (deben revisar el TRABAJO, no tu intención)
Si el revisor está equivocado:
- Contradice con evidencia (muestra código/pruebas que refuten la retroalimentación)
- Sáltate ese punto específico en la revisión
- Anótalo en tu informe al usuario
- NO bajes el listón de calidad para compensar
Ejemplo de Formato de Informe
--- Bucle de Revisión: {nombre de la tarea} ---
Bucle 1/4: Puntuación 6/10
Revisor: Falta validación de entrada, sin manejo de errores para timeout de red,
función demasiado larga (80 líneas).
Acción: Corrigiendo los tres problemas.
Bucle 2/4: Puntuación 8/10
Revisor: Limpio. Menor: el nombre de variable `d` podría ser más descriptivo.
Acción: Umbral de calidad cumplido (8 >= 8). Pulido final.
Resultado: 8/10 en 2 bucles. Listo.
Limitaciones Conocidas
- El subagente revisor no tiene memoria de bucles anteriores — incluye explícitamente el contexto de retroalimentación anterior en cada mensaje del revisor para evitar repetir problemas resueltos
- Es posible la inflación de puntuaciones si los criterios del mensaje del revisor son demasiado vagos — invierte tiempo en escribir criterios específicos y medibles
- Este skill no reemplaza la revisión de código humana para código crítico de seguridad o sensible al cumplimiento; trata el resultado como un primer paso sólido
- La convergencia del bucle no está garantizada si la tarea está poco especificada — define criterios de aceptación claros antes de comenzar
Coste y Velocidad
- Cada bucle = 1 llamada al subagente revisor
- Presupuesta aproximadamente 1–2 veces el tiempo de un único pase de implementación para un ciclo completo de 3 bucles
- Esto es barato en comparación con enviar código con errores, especificaciones vagas o desencadenar un ciclo de revisión tardío
- Usa tu modelo por defecto/estándar para la mayoría de las revisiones; solo actualiza a modelos de razonamiento avanzado para dominios especializados (auditorías de seguridad, sistemas distribuidos, finanzas cuantitativas)
Licencia
MIT — libre de usar, adaptar y redistribuir con cualquier herramienta o plataforma de IA. Se agradece la atribución. Las contribuciones son bienvenidas.