Cómo construir un AI code review state machine que no cierre comentarios por accidente

Paso 1 — Crea un objeto estable por hallazgo. No guardes la observación solo como comentario textual anclado a una línea. Crea un findingid y almacena regla, severidad, símbolo o comportamiento afectado, commit de detección, evidencia y ubicación actual. Si el código se mueve, intenta reconciliar el finding con símbolos, AST o pruebas en lugar de crear uno nuevo automáticamente. El comentario visible puede cambiar, pero la identidad del problema debe sobrevivir revisiones. Esa separación permite mostrar un historial consistente y evita duplicados cuando un agente vuelve a describir el mismo defecto con palabras diferentes.

Paso 2 — Define estados con semántica operacional. Un conjunto mínimo puede incluir open, fixed, acceptedrisk, incorrect, moved, expired y superseded. Para cada estado decide qué significa y quién puede asignarlo. Fixed requiere evidencia de que la condición ya no existe; incorrect significa que la detección estaba mal; acceptedrisk conserva el problema pero registra una decisión humana. No permitas que el modelo use un estado ambiguo como “resolved” para todo. Las categorías deben soportar reporting y acciones posteriores. Por ejemplo, acceptedrisk puede tener fecha de expiración y volver a open cuando cambie el contexto.

Paso 3 — Haz explícita la tabla de transiciones. Escribe reglas como open→fixed solo con diff compatible más validación; open→incorrect con decisión humana o evidencia determinista; fixed→open si una regresión reaparece. Evita transiciones silenciosas basadas en que el comentario ya no coincide con una línea. Cada cambio de estado registra actor, timestamp, versión y reasoncode. Si un usuario responde “mantener abierto”, crea una restricción que el agente debe respetar hasta nueva decisión autorizada. Esa tabla funciona como política independiente del modelo y puede probarse con fixtures antes de cambiar prompts o proveedores.

Paso 4 — Distingue aparición de introducción. Cuando un revisor encuentra un problema por primera vez en la tercera ejecución, compara el historial para determinar si el último commit lo creó o si existía desde antes. Si no puedes saberlo, marca detectiontime sin inventar introductiontime. Esta distinción evita culpar al commit equivocado y permite medir mejora del detector. También ayuda a los autores: un finding “previously missed” requiere atención, pero no implica que su cambio reciente lo haya causado. El sistema debe ser capaz de reconocer su propia limitación histórica en vez de reescribir la narrativa del PR.

Paso 5 — Diseña la experiencia humana alrededor de pendientes reales. La vista principal debería priorizar open y cambios nuevos de severidad, no repetir todo el historial en cada revisión. Permite filtrar acceptedrisk, incorrect y fixed para auditoría. Cuando el agente propone cerrar un comentario, muestra la evidencia que cambió desde la revisión anterior. Si una persona discrepa, esa respuesta se convierte en estado, no en texto olvidado. El objetivo es reducir carga cognitiva: el usuario necesita saber qué requiere decisión ahora y confiar en que lo ya resuelto no volverá a aparecer sin una razón nueva.

Paso 6 — Evalúa transiciones, no solo detecciones. Construye tests donde un defecto se corrige, se mueve, se acepta temporalmente, reaparece o recibe una respuesta humana que impide cerrarlo. Verifica que la máquina conserve el estado correcto en cada caso. Mide auto-resolutions incorrectas y reaperturas evitables como errores de producto. En Goatify, esta state machine puede reutilizarse para revisiones de campañas, documentos o automatizaciones. La idea central es la misma: una observación tiene ciclo de vida. La IA puede proponer la transición, pero una política verificable decide cuándo el estado realmente cambia.