steve-swanson/review-work

Revisión de Trabajo

Esta habilidad revisa código, muestra los hallazgos en una página web local, y solo corrige lo que el usuario aprueba. Todas las correcciones aprobadas se consolidan en una rama y se envían en una sola solicitud de extracción (PR).

El agente principal (el chat que ejecuta esta habilidad) está a cargo. Establece el alcance, elige el modelo para cada agente auxiliar, guarda todos los registros y verifica todos los resultados. Los agentes auxiliares realizan la tarea asignada y reportan.

Esta habilidad funciona junto a plan-work y execute-work. No los llama ni los modifica.

Términos utilizados aquí

• Rama revisada: la rama bajo revisión. La PR se integra de vuelta en esta rama. No siempre es develop.
• Commit revisado: el SHA exacto del commit que se revisó. Cada hallazgo lo referencia.
• Hallazgo: un problema o pregunta de la revisión, con un ID como R001.
• Página: la página web local donde el usuario elige Corregir, No corregir o Aclarar para cada hallazgo.
• Lote: las elecciones enviadas con un solo clic en Enviar.
• Árbol de trabajo: una copia adicional del mismo repositorio en su propia carpeta.
• Rama coordinadora: la rama única (con su propio árbol de trabajo) que recopila todas las correcciones. Se convierte en la PR. Nómbrala al estilo de Rama Convencional, <tipo>/<descripción-corta>, en minúsculas con guiones. Las correcciones de revisión suelen ser fix/, como fix/recuperación-sesión; usa refactor/, perf/, docs/, test/ o chore/ cuando sea más apropiado para todas las correcciones. Si el usuario o el repositorio nombran una convención diferente (por ejemplo, en AGENTS.md), síguela. Nunca pongas integration en el nombre.
• Rama de tarea: una rama de corta duración y su árbol de trabajo donde un agente auxiliar realiza una corrección.
• Fusión fast-forward: una fusión que solo avanza la rama sin agregar un commit de fusión (git merge --ff-only).
• Propiedad de la ejecución: creado por esta ejecución de revisión. La limpieza solo afecta a ramas y árboles de trabajo propiedad de la ejecución. Un nombre coincidente no es prueba de propiedad.

Lo que el usuario ha permitido

• Al iniciar esta habilidad, se permiten los registros de revisión y el servicio de página local.
• Al elegir mostrar la página en otra máquina enlazada, se permite un hilo de alojamiento de página en esa máquina, dentro de un proyecto T3 llamado Review-work pages (creado si no existe). Solo ejecuta el CLI de review-work. Nunca toca código allí. Cuando la revisión esté completa, se permite cerrar ese hilo y eliminar el proyecto Review-work pages (lo que elimina sus chats), como se describe en remote-page.md. Nunca elimines ningún otro proyecto. Este chat de revisión nunca está en ese proyecto: permanece, y recibe el informe final.
• Al enviar Corregir (desde la página, o un claro "corrígelo" en el chat), se permiten árboles de trabajo de tarea, commits, fusiones en la rama coordinadora, limpieza segura, push y una PR lista para revisión. También permite observar esa PR hasta su fusión, y luego eliminar el árbol de trabajo de la rama coordinadora fusionada sin cambios y la rama local en la máquina de revisión.
• Si el usuario dice "solo local" o "sin PR", sigue esa instrucción.
• Nunca fusiones la PR, actives la auto-fusión o despliegues.

Paso 1: Definir qué revisar

1. Lee las instrucciones, requisitos, estado, ramas y árboles de trabajo del repositorio. Deja las ediciones sin confirmar y otras ejecuciones intactas.
2. Registra la ruta del repositorio, la carpeta Git compartida, la rama, la base, el SHA del commit revisado, el host (nombre de la máquina) y el ID del chat.
3. Revisa solo el código confirmado, usa git show, diferencias o un checkout gestionado limpio. Los archivos sin confirmar no forman parte de la revisión.
4. Elige el alcance:
   • Rama de característica: revisa su diferencia con respecto a su base. Obtén la base del usuario, las reglas del proyecto o los metadatos de la PR. Si aún no está claro, pregunta.
   • develop: revisa todo el código actual. No inventes una fecha de inicio o un commit de inicio.
5. Pregunta "¿En línea o con subagentes en paralelo?" a menos que el usuario ya lo haya indicado.
   • En línea: el agente principal revisa por sí mismo. Las correcciones aún usan ayudantes.
   • En paralelo: los ayudantes revisan en paralelo. Pide la mayor cantidad de ayudantes a la vez y sugiere un número basado en las áreas independientes útiles. Ofrece Auto: tantos ayudantes útiles como la capacidad lo permita. Si la capacidad es desconocida, indica que el límite es 4. Pon en cola el resto.
6. Antes de crear cualquier árbol de trabajo, guarda una instantánea de los árboles de trabajo actuales, las ramas locales y los archivos adjuntos gestionados. Mantén una lista de cada árbol de trabajo que esta ejecución crea: revisores, correctores, ayudantes, reintentos y sus hijos, también los que quedan sin cambios o abandonados. Consulta cleanup.md.

Paso 2: Iniciar los registros de revisión

• Usa Node 24+ y scripts/review.mjs de esta habilidad. Los comandos están en runtime.md.
• Ejecuta init una vez, con un archivo de entrada JSON guardado fuera del proyecto. Guarda la ruta de la carpeta de revisión devuelta y reutilízala. Al reanudar, nunca crees una nueva ejecución.
• Los registros se almacenan en <home>/.agents/state/review-work/. El runtime crea su .gitignore antes de cualquier otro archivo allí, para que Git nunca los recoja.
• La identidad de un repositorio es su URL remota limpiada más su carpeta Git compartida real. Los árboles de trabajo enlazados de un clon comparten una identidad; los clones separados no. Cada ejecución también tiene su propio ID, por lo que las revisiones que se ejecutan al mismo tiempo no se mezclan.
• Solo el agente principal y su servicio de página escriben los registros. Nunca copies la base de datos, el servicio o el estado en un árbol de trabajo o .worktreeinclude. Los ayudantes devuelven resultados y el agente principal los guarda. Los ayudantes colocan archivos grandes en su propia carpeta temporal; el agente principal los importa.

Paso 3: Elegir modelos, luego revisar

Lee routing.md primero.

• El agente principal elige el modelo exacto y el esfuerzo para cada tarea de revisión y corrección. Verifica que el host los ofrezca, luego registra la elección antes de iniciar la tarea. Los ayudantes nunca llaman a Jev ni eligen rutas (modelo, esfuerzo u opciones). Nunca inician sus propios ayudantes a menos que el principal les asigne una tarea exacta y fija para hacerlo.
• Mantente en la familia de modelos del chat: modelos GPT en un chat GPT; Claude Opus, Sonnet o Haiku en un chat Claude.
• Siempre la versión más nueva. Los modelos se eligen por nombre de nivel (Astra, Sol, Terra, Opus, Sonnet, Haiku). Para cada nivel, el runtime solo mantiene la versión más nueva en la lista de modelos del host y rechaza las anteriores. Nunca elijas una versión de memoria. Confía en la lista de modelos del host sobre las conjeturas. Nunca inventes un ID de modelo ni cambies de proveedor en silencio. Si la familia es desconocida o falta un modelo necesario, pregunta.
• Jev puede elegir primero el modelo, luego un esfuerzo que ese modelo soporte. Necesita una clave. Encuéntrala con la detección de credenciales del runtime, nunca abriendo el archivo tú mismo. La detección verifica primero <home>/.config/jev/credentials.env (TYPESAFE_API_KEY es el nombre recomendado). Si no hay una clave de inicio útil, verifica el orden real de carga de variables de entorno del proyecto y sus adaptadores configurados, luego pasa esas rutas de archivos env. Nunca imprimas, guardes o ejecutes source de archivos de clave o valores de clave. El orden completo de búsqueda está en routing.md.
• Un adaptador Jev MCP configurado puede hacer las mismas dos elecciones. Lee primero su esquema de herramientas real; no asumas que existe una herramienta jev_route. Sin un adaptador, usa el transporte directo incorporado del runtime.
• Límites de esfuerzo, para cada modelo: las revisiones y la planificación llegan hasta extra-alto, nunca máximo o ultra. Las correcciones llegan hasta Alto. El runtime rechaza cualquier ruta por encima del límite, ya sea de Jev o del principal.
• Si Jev falta o da una respuesta inutilizable, el agente principal decide con las mismas reglas. No hay una tabla de respaldo fija.
  • Trabajo de listado solo lectura: Bajo está bien.
  • Algoritmos o razonamiento complejo: Alto o extra-alto.
  • Si no estás seguro: Alto.
  • Revisión de seguridad y planificación (inicio de sesión, permisos, secretos, criptografía, aislamiento de inquilinos, límites de confianza): el GPT Astra más nuevo o el Claude Opus más nuevo, en extra-alto. Si ese modelo no tiene extra-alto, usa el mismo modelo en su nivel más alto por debajo del límite (al menos Alto). No cambies a una versión anterior. Si un ayudante encuentra nuevo alcance de seguridad, detiene esa parte y reporta al principal. La implementación planificada usa las rutas de corrección a continuación, incluidas las correcciones de seguridad.
  • Revisión en línea cuando una parte necesita una ruta más alta: no le pidas al usuario que cambie el modelo o el esfuerzo de este chat. Este chat no puede confirmar ni establecer su propio esfuerzo. Entrega esa parte (por ejemplo, las verificaciones de seguridad) a un ayudante de revisión, y establece el modelo exacto y el esfuerzo del ayudante cuando lo inicies (en Claude Code, la herramienta Agent con model y effort; en T3, opciones de delegate_task). Registra la ruta primero. El ayudante devuelve hallazgos; el agente principal los guarda. Pregunta al usuario solo si el host no puede iniciar un ayudante con el modelo y esfuerzo requeridos: entonces explica la brecha y ofrece mantener el modelo de este chat. Registra esa elección una vez para esta revisión y no preguntes de nuevo. Esto nunca reduce la regla para los ayudantes en paralelo.
• Divide la revisión por comportamiento y por archivos. Sigue los flujos entre archivos. Busca formas en que el código se rompe: resultados incorrectos, reglas rotas, datos perdidos, verificaciones faltantes y rupturas de compatibilidad. Verifica cada preocupación contra los requisitos y el código que realmente se ejecuta. Combina duplicados.
• Registra la cobertura: lo que verificaste, omitiste y no pudiste terminar, con rutas, SHA, razón y prueba. "Sin hallazgos" no significa que todos los archivos fueron verificados. No des la revisión por completa mientras la cobertura importante no esté contabilizada (no registrada como verificada, omitida o no terminada).

Paso 4: Redactar hallazgos comprensibles

El usuario decide solo con el texto del hallazgo, por lo que el texto debe ser breve, exacto y claro. Lee writing-findings.md. Dale su ruta a cada ayudante de revisión y dile que lo siga.

Usa etiquetas de Comentarios Convencionales como issue, question, suggestion y nitpick. Marca cada hallazgo como blocking o non-blocking. Cada hallazgo tiene cuatro partes:

• Título: qué sale mal, como una oración simple de 80 caracteres o menos. "Reintentar un pago puede crear dos facturas", no "Ruta de creación de factura no idempotente".
• Por qué es importante (discussion): quién o qué se ve afectado, cuándo y con qué frecuencia.
• Prueba (evidence, más un excerpt de código opcional): ruta:línea, la ruta del código o los pasos, y cómo lo sabes.
• Idea de corrección (suggestion): comienza con Corrección pequeña, Corrección mediana o Corrección grande, luego dice qué cambiar.

Si no estás seguro, escribe un question. Nunca presentes una conjetura como un issue confirmado. Dale a cada hallazgo un ID estable, la ruta y línea, y el SHA revisado.

Antes de cargar los hallazgos, ejecuta la verificación de claridad en writing-findings.md en cada uno. Reescribe los que fallen y conserva todos los hechos.

Paso 5: Mostrar la página y recopilar decisiones

1. Carga los hallazgos y la cobertura, luego inicia la página. Una página sirve para toda la revisión, incluidas rondas posteriores.

2. Para cada hallazgo, el usuario elige Corregir, No corregir o Aclarar, y puede agregar una nota a cualquiera de ellos. Las elecciones se guardan como borradores. Cambiar la elección conserva la nota.

3. Solo Enviar envía un lote. Los lotes parciales están bien; los hallazgos no decididos permanecen abiertos. Las elecciones enviadas se bloquean en la página. Los cambios ocurren en el chat.

4. Verifica el arnés primero. Este chat se ejecuta en T3 Code cuando su shell tiene configurado T3CODE_THREAD_ID o T3CODE_CLI_PATH, o cuando herramientas T3 como t3_environment_links están disponibles. Si no:

   • Muestra la página en esta máquina, con deliveryMode: "terminal".
   • Salta la elección de alojamiento de página a continuación y no ofrezcas otra máquina. No leas remote-page.md.
   • Usa la redacción de terminal simple en el elemento 5.

   En T3, elige dónde mostrar la página desde el origen del chat. Mantén esto separado de la elección en línea/en paralelo.

   • Respeta una elección explícita de alojamiento de página ya hecha en este chat. Al reanudar, reutilízala; pregunta de nuevo solo si el usuario la cambia o ese host no está disponible.
   • Si el chat se inició localmente en la máquina de revisión, muestra la página en esa máquina sin preguntar. Establece esto a partir de la declaración del usuario o de los metadatos de origen del cliente proporcionados por el host que identifican el dispositivo iniciador. El nombre de host del agente, el directorio de trabajo, el entorno de ejecución o creationSource (web, mobile o mcp) por sí solo no prueba dónde inició el usuario el chat.
   • Si el chat se inició de forma remota, o su origen es incierto, pregunta una vez dónde mostrar la página. Pregunta directamente por el host de la página, sin una pregunta separada sobre si el usuario es local. Llama a t3_environment_links y ofrece esta máquina más cada máquina enlazada alcanzable con acceso completo, usando sus etiquetas reales. No excluyas ninguna máquina debido a su sistema operativo. Explica un bloqueo de capacidad/acceso conocido en lugar de ocultar silenciosamente un host. Si la herramienta de preguntas no puede contener todas las opciones, enumera todos los hosts elegibles en la pregunta y acepta un nombre de host.
   • Recomienda la máquina del usuario cuando sea conocida y elegible. Explica la limitación de bloqueo de pantalla solo cuando afecte la elección: el navegador transmitido de T3 se detiene cuando la pantalla de la máquina de revisión está bloqueada. Guarda el host seleccionado y la evidencia de origen (o unknown) en las notas de revisión.
   • En otra máquina: sigue remote-page.md. La página se abre en el navegador del usuario allí, y Enviar devuelve las elecciones a este chat. Necesita enlaces T3 de acceso completo. Funciona mientras esta máquina está bloqueada.

5. Siempre proporciona el host y el enlace de la página.

   • En T3, en esta máquina: el navegador T3 puede abrir la página. Di "Enviar reanuda esta conversación automáticamente." La página usa el comando local t3 thread send. No se necesita webhook público ni túnel.
   • En T3, en otra máquina: di qué máquina muestra la página, y "Enviar devuelve tus elecciones a este chat."
   • En una terminal simple, di:
     1. Abre la página de revisión.
     2. Elige una opción para cada hallazgo, agrega notas si lo deseas, y haz clic en Enviar.
     3. Vuelve a este chat y...

[truncado para traducción]