branch-review-tracker

Branch review tracker (rastreador de revisión de rama)

Una revisión de una rama que se corrige a lo largo de varias rondas. Cada ronda vuelve a revisar la rama y actualiza una página: una lista numerada de incidencias, cada una con un estado y una ventana emergente de Detalles que muestra la evidencia, el commit responsable y los lugares donde buscar.

La página es un Artefacto de claude.ai y es el registro de la revisión. Es de solo lectura para los espectadores: solo Claude cambia un estado, a medida que la revisión y las correcciones avanzan. Una nueva sesión se reanuda desde el pequeño context.json de la página, no desde la conversación ni los archivos locales.

El rastreador contiene tres archivos:

• index.html: la página, una copia de assets/tracker.html;
• issues.json: cada incidencia y el registro de la sesión;
• context.json: las notas de reanudación y un índice de las incidencias para la próxima sesión, el prompt que la inicia y la breve lista de lo que espera al usuario, que es la única parte que la página muestra.

1. Preguntar qué revisar

Recopila primero los candidatos, luego pregunta todo en una sola llamada AskUserQuestion. Omite una pregunta cuya respuesta vino con la invocación, por ejemplo un número de PR o URL.

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # el valor predeterminado de base
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # o: glab mr list --source-branch <target>

Pregunta	Opciones
Rama objetivo	la rama head del PR si se proporcionó un PR; de lo contrario, las tres ramas locales actualizadas más recientemente, excepto la base
Rama base	la rama predeterminada del remoto (Recomendada), luego otras ramas de larga duración, si las hay
Ticket	identificadores encontrados en el nombre de la rama y los asuntos de sus commits; No ticket

El usuario siempre puede escribir otro valor. Pregunta sobre el ticket después de que se conozca la rama, o deriva sus opciones del objetivo más probable.

2. Verificar el entorno

Ejecuta el script de verificación previa y muestra su tabla al usuario:

<this skill>/scripts/preflight --target <branch> [--base <base>] [--ticket <id>]

Verifica el repositorio, ambas referencias, el checkout del usuario, si la rama local coincide con el head del PR, el PR en el host, los filtros de checkout que pueden detener git worktree, y las CLI que usa la revisión. El código de salida 2 significa un bloqueador; 1 significa solo advertencias. No verifica las herramientas de compilación del proyecto: esas pertenecen a las habilidades auxiliares del proyecto.

El script obtiene ambas ramas. Toma la base de origin, donde está actualizada, y el objetivo del clon, donde el autor puede haberlo enviado. Revisa contra las referencias que imprime. Si advierte que la rama local difiere del head del PR, revisa el head del PR: léelo con git show <sha>:<path> en lugar de hacer checkout.

Luego verifica las herramientas de esta sesión, que un script no puede ver, y agrégalas a la tabla:

Necesario para	Herramienta	Sin ella
la revisión	habilidad code-review, o la herramienta Agent	bloqueador
la página	herramienta Artifact	mantén los archivos en el bloc de notas y da al usuario sus rutas después de cada ronda; dícelo
el contexto del ticket y la publicación de tickets	Herramientas de Atlassian (getJiraIssue, createJiraIssue)	revisa sin ello; dícelo
los comentarios y comprobaciones del PR	gh o glab, autenticados	revisa solo la rama; dícelo

Luego busca las habilidades auxiliares del proyecto, como se describe en "Habilidades auxiliares" a continuación, y agrega una fila por cada ayuda a la tabla: encontrada, con su nombre, o faltante, con lo que la revisión carecerá.

Detente en un bloqueador y di qué falta. En caso de advertencias, di lo que la revisión no cubrirá y continúa.

Si se puede leer el ticket, obtén su resumen y estado. Escribe un estado entre paréntesis después del id: PROJ-123 (en progreso).

3. Primera ronda

1. Revisar. Invoca code-review en <target> contra <base>, o en el número de PR. Dile al revisor que lea otros commits con git show <rev>:<path>, y que nunca haga checkout de nada en el directorio del usuario.

2. Revisar la prosa, como se describe en "La revisión de prosa" a continuación. code-review busca defectos en el código y no la cubre.

3. Verificar cada hallazgo, como se describe en "Verificación de hallazgos" a continuación. Una incidencia va a la página solo después de este paso. Un hallazgo que no lo supera se descarta antes de listarse, o, una vez listado, se establece en dismissed con su motivo.

4. Clasificar cada incidencia.

   • El commit responsable: git log -S'<symbol>' <base>..<target>, o git blame -s <target> -- <path>.
   • Si la base también lo tiene: git show <base>:<path>. Una incidencia que la base ya tiene obtiene "commitRole": "Pre-existing on" y "commit": "<base>". No es una regresión de la rama, pero aún puede bloquear la fusión cuando la rama lo empeora, por ejemplo exponiendo más datos a través de él.
   • file:line para cada ubicación, en el commit revisado.

5. Escribir el rastreador en el bloc de notas de la sesión, en una carpeta nombrada después de la rama (/ reemplazado por -):

   • index.html: una copia de assets/tracker.html, con __TITLE__ reemplazado por el nombre de la página. El nombre es el tema de la rama en dos a cuatro palabras, seguido de "Revisión", como Revisión de Autorización de Clave API.
   • issues.json y context.json, como se describe en "Los archivos de datos" a continuación.

6. Validar ambos archivos. El validador verifica el esquema, que cada ubicación exista en el commit revisado, y que el índice en context.json coincida con las incidencias:

   python3 -I <this skill>/scripts/validate-issues.py <dir>/issues.json --repo <repo>
   

7. Publicar con la acción de publicación de la herramienta Artifact, file_path establecido en <dir>/index.html, files establecido en {"issues.json": "<dir>/issues.json", "context.json": "<dir>/context.json"}, icon: "checklist" y un description de una oración. Escribe la URL devuelta en ambos archivos ("artifact"), vuelve a publicar y da el enlace al usuario.

4. Rondas posteriores

Ejecuta una ronda cuando el usuario dice que la rama se actualizó, o pide una nueva revisión.

1. Confirmar que la rama se movió. Compara el head del PR, o la ref objetivo, con reviewed, y mira git reflog -3 --date=iso <target>. Un push puede llegar tarde y la rama local del usuario puede retrasarse respecto al PR. Si nada se movió, dícelo y detente.
2. Obtener la base (git fetch origin <base>). Si la base se movió, anótalo y compara la rama con git range-diff <old-base>..<old-tip> <new-base>..<new-tip>.
3. Ver qué cambió:
   • git range-diff <base>..<reviewed> <base>..<target> muestra qué commits fueron reescritos, agregados o eliminados;
   • git diff <reviewed> <target> muestra el cambio neto;
   • los nuevos comentarios, revisiones y comprobaciones del PR (gh pr view <n> --json comments,reviews, gh api repos/<owner>/<repo>/pulls/<n>/comments, gh pr checks <n>).
4. Evaluar cada corrección. Para cada incidencia que el cambio aborda, lee la corrección y registra en fix qué hace y cómo se comporta el código ahora. Establece fixed solo cuando la lectura lo confirma, y di en verified hasta qué punto se verificó.
5. Buscar problemas que causan las correcciones. Una corrección a menudo mueve el problema en lugar de eliminarlo. Verifica las entradas que el código antiguo manejaba por accidente:
   • un valor faltante, vacío o nulo, por ejemplo una propiedad que un cliente no establece, que solía producir un literal inofensivo y ahora significa "sin restricción";
   • valores predeterminados a los que un valor retrocede;
   • rutas de código que el cambio alcanza sin tocarlas, como llamadores, otros endpoints, clientes antiguos y el lado de importación de una exportación;
   • comportamiento que el cambio altera para solicitudes no objetivo. Agrega cada problema como una nueva incidencia y anota la corrección que lo causó en ambas incidencias. Ejecuta "La revisión de prosa" en el cambio neto.
6. Reevaluar cada incidencia que no esté corregida contra el nuevo código, y mira nuevamente las corregidas cuyo código cambió.
7. Ejecutar pruebas solo como permite "Reproducción con pruebas" a continuación.
8. Actualizar el rastreador, como se describe en "Mantener el rastreador actual" a continuación:
   • Establece reviewed en la nueva punta.
   • Reescribe commits con los nuevos hashes. Un commit reescrito obtiene su nuevo hash; uno eliminado deja el mapa; uno nuevo se agrega.
   • Cambia status, commit, commitRole, note, fix y detail de las incidencias que cambiaron.
   • Vuelve a encontrar la línea de cada ubicación en la nueva punta con git grep -n. No desplaces líneas mediante aritmética.
   • Agrega nuevas incidencias con el siguiente número libre. Nunca renumeres.
9. Validar, luego volver a publicar en la misma URL.
10. Informar al usuario: qué corrigió esta ronda, qué sigue abierto y qué es nuevo, con file:line y qué se ejecutó. Termina con el enlace de la página.

Verificación de hallazgos

Lee el código tú mismo en el commit revisado antes de que una incidencia vaya a la página.

1. Rastrear el escenario de principio a fin. Sigue la entrada desde donde entra hasta donde ocurre el daño, y nombra cada paso con file:line. Un hallazgo que necesita un paso que el código no toma se descarta, con ese paso como motivo.
2. Verificar las precondiciones. Pregunta cómo puede surgir el estado desencadenante:
   • quién puede crear la entrada, por ejemplo a través de qué API, y si un validador o un valor predeterminado lo detiene;
   • si un valor predeterminado configurado, como una vida útil ilimitada o un rol asignado cuando no se da ninguno, hace que el escenario sea inalcanzable, o lo convierte en el caso normal;
   • si los datos existentes pueden contenerlo. Cuando solo los datos fuera del repositorio pueden responder, usa la ayuda de verificación de datos del proyecto; sin una, pregunta al usuario cómo averiguarlo. Registra la respuesta en verified y en el registro.
3. Separar "intencionado" de "aceptable". Un runbook, prueba o comentario de código que muestra un comportamiento deliberado no lo hace inofensivo. Verifica la compatibilidad hacia atrás por sí misma: clientes existentes y versiones desplegadas, datos existentes, y proveedores o usuarios que nunca usaron la nueva característica. Una ruptura deliberada de un flujo de trabajo existente es una incidencia, y un bloqueador a menos que el usuario lo acepte.
4. Decir cómo se verificó. Escríbelo en verified: "Reproducido por una prueba a nivel de controlador; la capa de servicio fue simulada", "Por lectura del código; no ejecutado", "Verificación de datos: no hay registros coincidentes". Informa qué prueba la evidencia y nombra qué no prueba. No afirmes un veredicto causal o comparativo que los datos no muestren.
5. Descartar con un registro. Un descarte establece status: "dismissed" y un dismissal con quién decidió, cuándo y por qué. Cuando Claude descarta, dícelo, y que ninguna persona lo aprobó; la página lo muestra.
6. Reabrir cuando se cuestione. Cuando el usuario cuestiona un descarte o un veredicto, vuelve a verificarlo desde el código en lugar de defenderlo. Si fue incorrecto, reabre la incidencia, elimina el descarte y di claramente en note qué obtuvo mal el veredicto anterior.

Reproducción con pruebas

Ejecuta compilaciones y pruebas solo cuando el usuario lo solicite, o cuando las instrucciones del repositorio y del usuario lo permitan sin preguntar. Cómo compilar y probar el proyecto, con qué cadena de herramientas y configuraciones, proviene de la ayuda de compilación y prueba del proyecto y sus instrucciones, no de esta habilidad.

1. Nunca usar el checkout del usuario. Pon el commit bajo prueba en un directorio separado:
   • git worktree add --detach <scratchpad>/<name>-wt <sha>;
   • si algo bloquea el worktree, exporta el commit en su lugar, omitiendo las rutas que lo bloquean: git archive <sha> -- . ':(exclude)<blocked-path>' | tar -x -C <dir>. Por ejemplo, un filtro smudge de git-crypt falla en rutas encriptadas cuando la clave no está disponible. El script de verificación previa nombra las rutas que tienen filtros de checkout.
2. Compilar y ejecutar como dice el proyecto. Una falla de herramienta, como una cadena de herramientas que el proyecto no soporta, no es un resultado de prueba: corrige el entorno como dice la ayuda o las instrucciones del proyecto, luego ejecuta de nuevo. Sin una ayuda, pregunta al usuario en lugar de adivinar, y anota lo aprendido para las notas del proyecto.
3. Escribir la prueba para que afirme el comportamiento correcto. Una falla entonces reproduce la incidencia, y la misma prueba se convierte en la prueba de regresión para la corrección. Conduce las clases reales a lo largo de la ruta, y simula solo lo que el escenario necesita. Haz que cada simulacro refleje lo que hace el código real, y nombra cada capa simulada o no ejercitada en verified, como HTTP, la cadena de seguridad o la base de datos.
4. Ejecutar el conjunto más reducido: la nueva prueba, más las pruebas que cubren el código cambiado.
5. Mantener el código fuente de la prueba en el rastreador. El bloc de notas puede borrarse entre sesiones. Publica la prueba como tests/<Nombre>.<ext> en files, con contentType: "text/plain", y nómbrala en la incidencia.
6. Limpiar. Elimina el worktree o la exportación, y cualquier salida de compilación que una ejecución haya dejado en el checkout del usuario, como clases de prueba compiladas, que una compilación posterior recogería. Luego verifica que git status y git worktree list muestren el checkout del usuario sin cambios.

Habilidades auxiliares

El flujo de revisión es el mismo para cada proyecto; lo que el proyecto sabe reside en sus propias habilidades. Úsalas cuando existan; esta habilidad nunca codifica herramientas de proyecto de forma fija.

Encuéntralas en la lista de habilidades disponibles de esta sesión, por sus descripciones. No adivines nombres. Carga una con la herramienta Skill cuando el paso la necesite.

Ayuda	Se usa para	Sin ella
lista de verificación de revisión	las áreas de riesgo del proyecto: modelo de seguridad, promesas de compatibilidad, contratos de API, migraciones	la revisión se basa en conocimiento general; di qué áreas puede pasar por alto
compilación y prueba	compilar y probar un commit de forma aislada: comandos, cadena de herramientas, configuraciones, bloqueadores conocidos	las pruebas se ejecutan solo después de preguntar al usuario cómo; los hallazgos permanecen "de la lectura del código"
verificaciones de datos	responder preguntas a partir de datos fuera del repositorio, de forma segura	se pregunta al usuario cómo averiguarlo
reglas de prosa	comentarios, docstrings, registros de cambios, mensajes de commit y texto de PR, como un gener

La revisión de prosa

Revisa la prosa del cambio, por separado de la revisión de código. La revisión de prosa verifica:

• Comentarios y docstrings en el código modificado y nuevo, para ver si son engañosos, están incompletos o desactualizados.
• Mensajes de commit: si describen lo que el commit hace, y si se refieren a incidencias o tickets.
• Registros de cambios, si el proyecto los mantiene.
• El texto del PR: descripción, sección de cambios, instrucciones de revisión.

Cada hallazgo de prosa es una incidencia separada, con el mismo formato y verificación que los hallazgos de código.

Mantener el rastreador actual

Después de cada ronda, el rastreador debe reflejar el nuevo estado de la rama.

1. Nunca reescribir el historial. Los números de incidencia son permanentes. Una incidencia descartada permanece descartada; no se reutiliza.
2. Agregar, no editar. Las nuevas incidencias obtienen el siguiente número libre. Las notas de las incidencias existentes se actualizan, pero su número y su historia no cambian.
3. Actualizar issues.json. Para cada incidencia que cambió, actualiza status, commit, commitRole, note, fix y detail según corresponda. Agrega nuevas incidencias al final de la lista. No elimines incidencias.
4. Actualizar context.json. El índice en context.json debe coincidir con la lista de incidencias. Agrega nuevas incidencias al índice, con su número y estado.
5. Validar. Ejecuta el script de validación después de cada actualización, antes de publicar.

Registro de la sesión

issues.json contiene un array log que registra cada ronda:

{"round": 2, "timestamp": "2024-01-15T10:30:00Z", "action": "review", "result": "3 fixes verified, 1 new issue found"}

Cada ronda agrega una entrada. El registro es de solo lectura para los espectadores; solo la habilidad lo escribe.

Notas del proyecto

Cuando preguntes al usuario cómo hacer algo (por ejemplo, cómo verificar datos o ejecutar pruebas), y la respuesta es reutilizable, anótala en las notas del proyecto. Las notas del proyecto se almacenan en context.json, bajo projectNotes, y se incluyen en el prompt de la próxima sesión.

El formato es libre: un array de objetos, cada uno con key, value y source. Ejemplo:

{"key": "data-check", "value": "Usar la API de administración en /admin/data/check con el ID del usuario", "source": "user"}