trailofbits/pr-improver

PR Improver (Mejorador de PR)

Mejora la rama actual ejecutando /code-improver:improve — un flujo de trabajo dinámico que itera un revisor de PR y un subagente corrector sobre los cambios de la rama hasta que una revisión reporte cero hallazgos críticos/mayores. El bucle, su registro y sus salvaguardas residen en el flujo de trabajo; este skill deriva el ámbito a partir del diff de la rama y transmite el resultado.

Iniciar el bucle

El usuario proporcionó: $ARGUMENTS (si está vacío, toma la rama base y las preferencias de la conversación).

1. Resolver la rama y su superficie de cambios

1. Raíz del repositorio: git rev-parse --show-toplevel. Fallar de forma explícita si no hay repositorio.
2. Base: el argumento si se proporciona, en caso contrario la rama por defecto del repositorio (git symbolic-ref refs/remotes/origin/HEAD → su nombre corto, con fallback a main). Rechazar ejecutarse cuando la rama actual ES la base — no hay diff que mejorar.
3. Archivos modificados: git diff --name-only <base>...HEAD. Si está vacío, informarlo y detenerse.
4. Ámbito: los directorios de los archivos modificados, ampliados — los globs por archivo son demasiado restrictivos (las correcciones del PR añaden legítimamente pruebas junto al código modificado). Mapear cada archivo modificado a su glob de directorio relativo al repositorio <dir>/** (** en la raíz solo si hay archivos modificados en la raíz), luego deduplicar y eliminar globs cubiertos por otro más amplio.

2. Resolver el script del bucle

El bucle es el flujo de trabajo dinámico workflows/improve.js en este plugin. Lanzarlo mediante ruta: scriptPath toma una ruta absoluta resuelta, y la herramienta Workflow con name resuelve flujos de trabajo integrados y del proyecto, por lo que uno instalado desde el mercado puede no responder a code-improver:improve. Intentar en orden, el primero que acierta gana — los directorios home tienen prioridad sobre . para que una copia instalada gane sobre una copia local de este mercado:

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (si esa variable está definida en su lugar)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Usar la ruta exacta tal como se imprime. Su directorio del plugin — la ruta sin /workflows/improve.js — es pluginRoot. Si los tres fallan, intentar una vez con {name: "code-improver:improve"}; si tampoco está disponible, detenerse e indicar que el bucle no pudo localizarse. No ensamblar una ruta manualmente y no improvisar el bucle.

3. Invocar el flujo de trabajo

Ejecutarlo con la herramienta Workflow, {scriptPath: "<la ruta del paso 2>", args: {...}}:

{
  "target": "<raíz del repositorio>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Revisar los cambios del árbol de trabajo contra <base> como si fuera un pull request: corrección, pruebas, manejo de errores y las dimensiones de revisión que prescribe el skill."
  },
  "scope": ["<globs-de-directorio-extraídos>/**"],
  "pluginRoot": "<el directorio del plugin del paso 2>",
  "maxRounds": 5
}

• reviewer — el valor por defecto requiere el plugin pr-review-toolkit. Cuando el usuario nombre un revisor de PR diferente (skill o agente), usarlo, con el tipo (kind) correspondiente.
• maxRounds solo si el usuario solicitó un límite diferente.
• pluginRoot permite que la ejecución encuentre su recolector de métricas; omitir la clave solo si el paso 2 falló y se usó el nombre del flujo de trabajo — entonces el flujo de trabajo se busca a sí mismo.
• finalize por defecto es adecuado para PRs: sin aumento de versión a menos que la rama esté dentro de un plugin, se omite la tira de narración y los documentos.
• decision solo en continuación (más abajo).

La instantánea de referencia del bucle es el árbol al inicio del bucle — su guarda de ámbito protege el trabajo no confirmado de la rama; los propios commits del PR son lo que revisa el revisor.

El flujo de trabajo se ejecuta en segundo plano y no necesita supervisión: revisa, corrige, vuelve a revisar, verifica el ámbito después de cada ronda de corrección, y solo puede completarse con una revisión limpia. Nunca hace commit; todos los cambios permanecen en el árbol de trabajo.

Si la herramienta Workflow no está disponible o está denegada, detenerse e informarlo. No improvisar el bucle en línea con ediciones directas — el registro, la guarda de ámbito y las garantías de escalado residen en el flujo de trabajo, y una imitación en línea no tiene ninguna de ellas.

Si el resultado es halted: "reviewer-unavailable", transmitirlo y detenerse. El revisor no está instalado en esta sesión; indicar al usuario qué plugin lo proporciona (el valor por defecto necesita pr-review-toolkit) y re-ejecutar después de instalarlo. No revisar la rama uno mismo.

No finalizar el turno mientras el bucle está en ejecución. La herramienta Workflow devuelve un id de tarea inmediatamente; el resultado llega después. En una sesión interactiva, la notificación de finalización te re-invoca — esperar por ella. En una ejecución no interactiva (scripteada, CI, evaluación) no hay un turno posterior: detenerse abandona el bucle a mitad de ronda, por lo que después de lanzarlo, sondear la tarea (TaskOutput con el id de tarea devuelto, o dormir y re-verificar) hasta que se complete, luego transmitir el resultado. Una sesión que responda "el bucle se está ejecutando, informaré más tarde" ha perdido la ejecución.

Transmitir el resultado

El flujo de trabajo devuelve un resultado estructurado. Reportarlo honestamente — las distinciones importan:

• converged: true — la última acción fue una revisión con cero hallazgos críticos/mayores. Reportar las rondas usadas, los hallazgos menores restantes (open_minor_count) y las rutas de los artefactos (ledger_path, metrics).
• capped: true — el presupuesto de correcciones se agotó y la revisión FINAL todavía encontró problemas bloqueantes. Decir claramente: limitado, NO convergido, y listar open_blocking. No presentar esto como éxito.
• escalation — el bucle detectó que no estaba convergiendo (hallazgos recurrentes, conteos no decrecientes, o una corrección que reubicó un problema). Transmitir el mensaje de escalado y los ids de hallazgos al usuario: esto necesita una decisión de diseño, no más rondas.
• halted — una guarda se disparó (violación de ámbito, nuevos archivos no registrados, un revisor muerto o no disponible, o una pasada de finalización cuyas propias ediciones fallaron la verificación que la sigue). Transmitir las rutas en violations/new_untracked_files, los sitios en finalize_regressions y las notas.
• notes siempre acompañan al resultado — mostrarlas; incluyen advertencias importantes como "se inicializó un repositorio git".

Continuar después de un escalado

El bucle se detiene por diseño al escalar. Cuando el usuario lo decida, iniciar una nueva ejecución con los mismos argumentos más:

{ "decision": "<la decisión del usuario, textual>" }

La nueva ejecución recarga el registro en disco, por lo que cada hallazgo, rechazo y veredicto se conserva — las rondas se reinician, la re-derivación no ocurre.

Para detener un bucle en ejecución, detener la tarea del flujo de trabajo (TaskStop); el registro en disco está actualizado hasta la última ronda y una re-ejecución continúa desde allí.

Cuándo NO usarlo

• Revisión única: ejecutar el skill de revisión de PR directamente; el valor del bucle es la iteración
• Un skill: usar la entrada skill-improver — ella conecta el revisor correcto
• Trabajo exploratorio no enviado: los bucles de revisión y corrección solidifican un diff; mientras la forma sea fluida, la iteración manual da más control