jzjizhe/revisión-investigación

Revisión de Investigación (Compuertas de Revisión Modulares y Combinadas)

Plan, Código y Prueba pueden ejecutarse de forma independiente o combinada:

• Si solo planificaste, ejecuta el Modo A (Revisión de Plan).
• Si escribiste código e inmediatamente escribiste/ejecutaste pruebas (el flujo natural), ejecuta el Modo B+C Combinado (Revisión Conjunta de Código y Prueba) en una sola ronda de revisión paralela; no pierdas tiempo lanzando dos rondas de revisión separadas consecutivas.
• Si solo escribiste código sin pruebas, o solo escribiste/ejecutaste pruebas para código existente, ejecuta el Modo B o el Modo C de forma independiente.

1. Despacho de Subagentes Revisores (spawn_subagent)

• Revisores por Defecto (channel=mcli): Llama a spawn_subagent concurrentemente para lanzar dos revisores paralelos y espera a ambos mediante get_command_or_subagent_output:
  • Subagente 1: model: "deepseek-v4.1-flash" (canal mcli)
  • Subagente 2: model: "glm-5.3" (canal mcli)
• Anulación por Usuario: Si el usuario especifica otros modelos (por ejemplo, kimi-k3.1-pro, MiniMax-M3.1-Flash, deepseek-v4-pro, o slugs friday/* / catpaw-ide/*), pasa los slugs de modelo especificados por el usuario a spawn_subagent.
• Cierre Incremental (resume_from):
  • Descubrimiento (Ronda 1): Genera subagentes nuevos con solo el artefacto mínimo (Plan, git diff, código de prueba + salida estándar stdout/stderr) y rutas de archivo clave; nunca pases tu historial de conversación.
  • Cierre (Ronda 2+, si se necesitaron correcciones o pruebas adicionales): Llama a spawn_subagent con resume_from: "<subagent_id>" para cada revisor, pasando solo los hallazgos activos y el delta de corrección/prueba para que verifiquen la actualización sin releer archivos sin cambios.

2. Límites Centrales de los Roles

1. El Agente Principal Ejecuta Validación Primero: Se recomienda realizar una prueba rápida de sintaxis/humo antes de despachar a los revisores para que estos no desperdicien esfuerzo en sintaxis rota. Pasa tu comando de prueba exacto y su salida como Main-agent validation evidence (evidencia de validación del agente principal).
2. Revisores Estrictamente de Solo Lectura: Instruye a los subagentes revisores para que solo lean/hagan grep de archivos, reporten hallazgos ordenados por severidad con evidencia de archivo:línea, y emitan - Validation request: <verificación exacta> cuando un caso límite no probado necesite prueba en tiempo de ejecución. Los revisores nunca editan archivos ni ejecutan comandos.
3. Adjudicación por el Agente Principal: Espera a que todos los revisores lanzados terminen antes de editar. Reproduce los errores candidatos de forma independiente, ejecuta las Validation requests válidas y adjudica (accepted / rejected) con evidencia concreta de código o matemáticas.

---

Modo A: Revisión de Plan (Independiente)

1. Prepara: Indica el objetivo, los archivos a tocar, las formas de los tensores / flujo de datos y las suposiciones explícitas (cualquier elección no declarada que afecte la semántica del entrenamiento, la escala de recompensa o la imparcialidad de la línea base).
2. Indica a los Revisores:

   "Revisión de solo lectura de este plan de investigación. No edites archivos ni ejecutes comandos. Cuestiona suposiciones no declaradas, verifica fugas de datos/etiquetas, injusticia en la línea base y cuellos de botella distribuidos/de rollout. Indica Review coverage: FULL|PARTIAL - <archivos inspeccionados> y termina con Review verdict: APPROVED|FINDINGS. [Insertar Plan y Rutas de Archivos Clave]"

Modo B: Revisión de Código (Independiente — cuando aún no se escribió ninguna prueba)

1. Prepara: Reúne el resumen de requisitos/plan y el git diff.
2. Indica a los Revisores: Indícales que inspeccionen los archivos modificados y los llamadores de un salto, solo lectura, en busca de errores silenciosos de investigación:
   • Enmascaramiento y Alineación: Errores de desplazamiento de uno en la máscara de tokens prompt vs. respuesta de SFT/RL, discrepancias en el lado de relleno (padding) o manejo de EOS/truncamiento.
   • Formas de Tensores y Broadcasting: Broadcasting no intencionado (por ejemplo, (B, 1) vs (B,)), errores en la dimensión de reducción (mean/sum sobre secuencia vs. lote).
   • Higiene de Gradientes y Estado: detach()/no_grad() mal ubicados, dirección de KL, alcance de normalización de ventaja, o estado del agente/entorno no reiniciado entre rollouts.
   • Exigen Review coverage y Review verdict: APPROVED|FINDINGS.

Modo C: Revisión de Pruebas (Independiente — cuando se agregan/auditan pruebas para código existente)

1. Prepara: Reúne la ruta del archivo de prueba, la ruta del módulo objetivo y la salida estándar stdout/stderr de la ejecución real de la prueba.
2. Indica a los Revisores:

   "Auditoría de solo lectura de esta prueba y su salida de ejecución. No edites archivos ni ejecutes comandos. ¿Verificó genuinamente los invariantes matemáticos/de tensores centrales y los casos límite, o simuló (mock) la lógica real/debilitó las aserciones para pasar? Emite - Validation request: ... si un caso límite no está probado. Indica Review coverage y termina con Review verdict: APPROVED|FINDINGS."

Modo B+C: Revisión Conjunta de Código y Prueba (Cuando el Agente Principal código y se autoprobó en una sola pasada)

1. Prepara: Empaqueta el resumen de requisitos/plan, el git diff de implementación + prueba, y la Main-agent validation evidence (comando de prueba exacto ejecutado y su stdout/stderr).
2. Indica a los Revisores:

   "Revisión conjunta de solo lectura del diff de implementación y la autoprueba del Agente Principal. No edites archivos ni ejecutes comandos.

   1. Verificación de Código: Busca errores silenciosos de investigación en los archivos modificados y en los llamadores de un salto (desplazamiento de uno en la máscara de tokens, alineación de relleno/EOS, broadcasting no intencionado de tensores (B,1) vs (B,), dimensión de reducción incorrecta, detach()/no_grad() mal ubicados, matemáticas de KL/ventaja, estado de rollout no reiniciado).
   2. Auditoría de Autoprueba: Verifica si la prueba del Agente Principal realmente verifica estos invariantes y casos límite, o si sufre de sesgo de confirmación (solo probar caminos felices, simular la lógica central, o aserciones débiles). Emite - Validation request: <verificación exacta> para cualquier prueba de caso límite faltante. Indica Review coverage: FULL|PARTIAL - <archivos inspeccionados> y termina con Review verdict: APPROVED|FINDINGS."

3. Adjudicación y Cierre: Corrige los errores de código aceptados y satisface las Validation requests válidas; si se realizaron cambios no triviales, usa resume_from en ambos revisores para verificar el delta.

---

3. Registro Ligero (docs/review-log.md)

Después de que cada puerta de revisión se complete, añade una entrada concisa de 5 a 10 líneas en inglés al archivo docs/review-log.md en el proyecto actual (crea el archivo si no existe). Esto preserva los identificadores de subagentes (subagent_id) a través de la compactación de contexto y mantiene un rastro de auditoría experimental:

## [AAAA-MM-DD] <Título Corto de la Tarea> (<Modo A / B / C / B+C>)
- **Suposiciones / Alcance**: <resumen de 1 línea de las suposiciones de diseño clave y archivos tocados>
- **Revisores**: `deepseek-v4.1-flash` (`id: <subagent_id>`), `glm-5.3` (`id: <subagent_id>`)
- **Adjudicación**:
  - `[ACEPTADO]` `<archivo:línea>` — <error/defecto conciso y cómo se corrigió>
  - `[RECHAZADO]` `<archivo:línea>` — <por qué el hallazgo del revisor fue un falso positivo, con evidencia matemática/de código>
- **Veredicto y Prueba**: `APROBADO` (<resultado de 1 línea de prueba/verificación de humo>)