Revisión de cambio
Esta skill revisa un cambio, no una pantalla. Resuelve el alcance, expande los archivos modificados a las superficies que afectan, lee ambos lados del diff y clasifica cada hallazgo.
El alcance es todo lo que abarca. Las reglas de dominio pertenecen a las skills better-*. La severidad, la consolidación, la cobertura, el límite y el veredicto pertenecen a better-interface, a quien esta skill entrega la revisión.
La corrección, las pruebas, la seguridad y el rendimiento pertenecen a la revisión de código general del proyecto. Menciona la preocupación una vez y continúa.
El cambio, no el código base
El autor pregunta: "¿He empeorado esto?". Reporta lo que el cambio causó y mantente mayormente en silencio sobre lo que simplemente tocó. Tres hallazgos preexistentes es una cortesía; treinta es una revisión diferente y que nadie pidió.
Lee el cambio antes de formarte una opinión sobre él. La intención declarada decide qué se considera incompleto, y un diff leído por encima produce hallazgos sobre código que el siguiente fragmento ya corrigió.
Principios fundamentales
1. Resolver el alcance del cambio primero
La invocación completa es el objetivo, así que /interface-review pr 482 revisa el pull request 482. La resolución de alcance contiene los objetivos aceptados y cómo se resuelve cada uno.
Sin un objetivo proporcionado, resuelve en este orden y detente en la primera coincidencia:
HEADestá por delante degit merge-base origin/<rama-por-defecto> HEAD: ese rango más cualquier cambio sin commit, con el número de commits y el número de archivos sin commit indicados por separado.- El árbol de trabajo está sucio: los cambios sin commit.
- Ninguno: no hay ningún cambio para revisar. Detente y pregunta, según Sin cambio, pregunta en lugar de inventar uno.
El orden importa. Verifica el árbol de trabajo primero y una edición de formato aislada oculta una rama de doce commits, y el informe aún afirma cobertura completa.
Excluye archivos de bloqueo, instantáneas, salida generada, código externo y binarios, y nombra lo que excluiste. Un alcance vacío después de exclusiones llega al mismo lugar por una ruta diferente.
2. Sin cambio, pregunta en lugar de inventar uno
Un árbol limpio sin nada por delante del merge base significa que el usuario solicitó revisar un cambio que no existe. Nunca recurras a HEAD~1..HEAD por tu cuenta. El último commit es lo que sea que haya aterrizado, a menudo un merge, a menudo trabajo de otra persona, y un informe sobre él es indistinguible de un informe sobre lo que el usuario quiso decir.
Indica los hechos del repositorio que encontraste, luego ofrece las rutas y espera. Nada que revisar contiene los hechos a recopilar:
- El último commit,
HEAD~1..HEAD, nombrado por SHA corto y asunto, para que el usuario vea lo que obtendría antes de elegirlo. - Un objetivo que nombren:
pr <n>, una rama, una referencia, o un rango, resuelto según Resolver el alcance del cambio primero. - Una auditoría de interfaz de todo el repositorio, que no es una revisión de cambio. Entrégala a
better-interfacecomo una revisión de alcance de repositorio, sin el bloque de alcance de esta skill, estados ni sección de preexistentes. Sin cambio, cada hallazgo es preexistente y la clasificación no dice nada.
Verifica si hay un pull request abierto en la rama actual antes de preguntar, y ofrécelo primero. Una rama cuyos commits ya aterrizaron se resuelve como ningún cambio, mientras que su pull request sigue siendo exactamente lo que el usuario quiso decir.
Cuando el alcance se haya vaciado después de las exclusiones, indica qué archivos fueron excluidos y pregunta de la misma manera. Nunca informes una revisión de nada como Aprobar.
3. Un diff no es una superficie
Un archivo modificado es evidencia, no el sujeto de la revisión. Su radio de explosión es el conjunto de superficies en las que se renderiza; revisa esas.
Expande el radio de explosión un salto por defecto: los importadores y llamadores directos. Expande un segundo salto solo para tokens de diseño, valores de tema y primitivas compartidas, donde una línea alcanza todo el producto.
Revisa como máximo cinco consumidores, ordenados según la regla en Resolución de alcance, luego indica cuántos no expandiste. Un barrido sin límite no puede respaldar la cobertura que afirma, y un límite no declarado se lee como completitud.
4. Leer las líneas eliminadas
Las regresiones son invisibles en el estado posterior al cambio. Lee el lado - de cada fragmento según Señales eliminadas.
Una señal es una pista, no un hallazgo. Una eliminación es solo una regresión cuando nada en el cambio la reemplaza, y la skill de dominio es dueña de ese juicio. Enruta cada eliminación no emparejada a su propietario, reporta solo lo que esa skill confirma y asígnale el estado Regresión. Eso le dice al autor que rompieron algo que funcionaba en lugar de cometer un nuevo error.
5. Clasificar cada hallazgo
Asigna a cada hallazgo un estado:
Introducido: el cambio lo creó.Regresión: el cambio debilitó algo previamente correcto.Preexistente: presente en el código tocado pero no causado por este cambio.
Estado por lo que el diff tocó, no por el archivo en el que se encuentra: una línea que el cambio nunca tocó es Preexistente incluso a tres líneas de un fragmento. Confirma contra la referencia base cuando sea relevante:
git blame -L <línea>,<línea> "$BASE" -- ruta/al/archivo
Entrega cada hallazgo con su estado adjunto y permite que better-interface aplique sus reglas de límite y veredicto.
6. Sostener el cambio según su intención declarada
Lee el título y el cuerpo del pull request, el issue vinculado y los mensajes de commit, luego revisa si la interfaz cumple lo que afirman.
Esto es lo que saca a la luz el cambio incompleto. Una revisión de superficie no puede verlo, porque inspecciona los estados que están presentes, y aquí el punto son los que están ausentes:
- Una nueva variante, tamaño o tema aplicado a algunos estados pero no a todos: hover, focus, active, disabled, loading, selected.
- Una nueva cadena orientada al usuario sin entrada en el catálogo de traducción que mantiene el proyecto.
- Un nuevo componente sin estado vacío, de carga, de error, deshabilitado o de ancho estrecho.
- Un control añadido a una superficie pero no a las hermanas que ya llevan sus pares.
No reportes expansión del alcance. Si un cambio hace demasiado es una pregunta de proceso, no de interfaz.
7. Entregar la revisión a better-interface
Entrega a better-interface el bloque de alcance, las superficies afectadas y un estado en cada hallazgo. Se encarga de enrutar a las skills de dominio, aplicar severidad, consolidar, aplicar el límite y emitir el veredicto.
Si better-interface no está disponible, reporta el alcance resuelto y el inventario de archivos, nómbralo como la skill faltante y detente. No inventes una escala de severidad, un límite o un veredicto.
8. Nunca mutar el árbol de trabajo
Una revisión de cambio es de solo lectura, incluyendo el checkout. Obtén las referencias del pull request; nunca las descargues con checkout. git fetch escribe solo en .git y está permitido. gh pr checkout, git checkout, git switch y git stash reescriben los archivos que el autor tiene abiertos. Fracasan contra ediciones locales o las descartan, por lo que nunca están permitidos.
La verificación renderizada es optativa. Marca las afirmaciones visuales y de tiempo de ejecución como No verificado a menos que el proyecto exponga una vista previa barata o el usuario solicite una revisión renderizada. Cuando lo hagan, usa un árbol de trabajo aislado (git worktree add /tmp/review-<n> refs/remotes/pr/<n>) y elimínalo cuando termines.
Antes de terminar
| Error | Solución |
|---|---|
| Una edición aislada revisada en lugar de la rama | Verifica merge-base antes que el árbol de trabajo, e informa ambos recuentos |
| El último commit revisado porque no había cambio | Indica los hechos y ofrece el último commit, un objetivo nombrado, o una auditoría de repositorio |
| Fragmentos revisados sin sus consumidores | Expande un salto, dos para tokens y primitivas, y nombra lo que saltaste |
Solo se leyó el lado + del diff | Busca en el lado - señales eliminadas de accesibilidad, enfoque, movimiento y texto |
| Un reemplazo equivalente reportado como regresión | Enruta la eliminación a su propietario; reporta solo lo que confirma |
| Una eliminación reportada como un nuevo error | Asígnale el estado Regresión para que el autor sepa que solía funcionar |
Una línea cerca de un fragmento con estado Introducido | Estado por lo que el diff tocó, confirmado con git blame contra la referencia base |
| Un pull request descargado con checkout para revisarlo | Obtén la referencia y revísala en su lugar |
| Números de línea citados que no existen en la referencia revisada | Cita contra la referencia head nombrada en el bloque de alcance |
| La escala de severidad o el límite de hallazgos reafirmados aquí | Difiere a better-interface |
| Hallazgos de corrección, prueba o seguridad en el informe | Nombra la preocupación una vez, apunta a la revisión de código del proyecto y abandona |
Formato de salida de la revisión
Comienza con el bloque de alcance:
| Campo | Valor |
|---|---|
| Objetivo | branch, working, staged, pr 482, o el rango según lo ingresado |
| Ref base | origin/main en a1b2c3d |
| Ref head | refs/remotes/pr/482 en e4f5g6h |
| Commits | 7 committeados, 2 archivos sin commit |
| Archivos en alcance | 12 después de exclusiones |
| Excluidos | pnpm-lock.yaml, src/__snapshots__/: archivo de bloqueo e instantáneas |
| Superficies expandidas | CheckoutPage, SettingsPanel; 3 consumidores más de Button no expandidos |
La tabla de cobertura la sigue sin cambios. Un dominio sin evidencia en el alcance del cambio es No revisado: sin evidencia en el alcance del cambio, que es una declaración de cobertura en lugar de una brecha.
Luego los hallazgos, con una columna Estado según Clasificar cada hallazgo:
| Severidad | Dominio | Estado | Ubicación | Antes | Después | Por qué |
|---|---|---|---|---|---|---|
| ALTA | Accesibilidad | Regresión | src/Dialog.tsx:42 | aria-label="Close" eliminado en este cambio | Restaurar aria-label="Close" en el control solo de icono | El control de cierre tenía un nombre accesible antes de este cambio y ya no |
Sin hallazgos Introducido o Regresión, omite la tabla e indica "No hay hallazgos de interfaz procesables en este cambio".
Luego hallazgos Preexistentes, como máximo tres, primero la mayor severidad, indicados claramente como que no son responsabilidad de este cambio. Omite la sección cuando no haya ninguno.
| Severidad | Dominio | Ubicación | Problema |
|---|---|---|---|
| MEDIA | Tipografía | src/Toolbar.tsx:7 | Las insignias numéricas usan figuras proporcionales; precede a este cambio |
El límite y el veredicto cubren solo Introducido y Regresión. Los hallazgos Preexistentes quedan fuera del límite, por lo que tocar un archivo heredado no puede convertirse en una auditoría de archivo completo. Quedan fuera del veredicto también, por lo que un cambio cuyos únicos hallazgos son preexistentes es un Aprobar.
Termina con Bloquear cuando quede algún ALTA y Aprobar en caso contrario, dejando los hallazgos restantes en la tabla como trabajo por hacer. Cuando better-interface esté disponible, la escala de severidad y el límite provienen de ella.