Revisión en dos ejes del diff entre HEAD y un punto fijo que el usuario proporcione:
- Estándares: ¿el código cumple con los estándares de codificación documentados del repositorio?
- Especificación: ¿el código implementa fielmente el issue/especificación original?
Ambos ejes se ejecutan como subagentes paralelos para que no contaminen su contexto mutuamente, y luego esta habilidad agrega sus hallazgos.
El rastreador de issues debería habérsele proporcionado. Si no, dígale al usuario que ejecute /setup-matt-pocock-skills.
Proceso
1. Fijar el punto fijo
Lo que sea que el usuario haya dicho que es el punto fijo (un SHA de commit, nombre de rama, tag, main, HEAD~5, etc.). Si no especificó uno, pídalo.
Capture el comando diff una vez: git diff <punto-fijo>...HEAD (tres puntos, para que la comparación sea contra la base común). También anote la lista de commits mediante git log <punto-fijo>..HEAD --oneline.
Antes de continuar, confirme que el punto fijo resuelva (git rev-parse <punto-fijo>) y que el diff no esté vacío. Una referencia incorrecta o un diff vacío deben fallar aquí, no dentro de dos subagentes paralelos.
2. Identificar la fuente de especificación
Busque la especificación original, en este orden:
- Referencias a issues en los mensajes de commit (
#123,Closes #45, GitLab!67, etc.), obtenidas mediante el flujo de trabajo del documento del rastreador. - Una ruta que el usuario haya pasado como argumento.
- Un archivo de especificación en
docs/,specs/o.scratch/que coincida con el nombre de la rama o la característica. - Si no encuentra nada, pregúntele al usuario dónde está la especificación. Si dice que no hay, el subagente de Especificación omitirá e informará "no hay especificación disponible".
3. Identificar las fuentes de estándares
Busque en el repositorio todos los archivos que documentan cómo debe escribirse el código. Cuando existan CODING_STANDARDS.md o CONTRIBUTING.md, deben estar en la lista.
Además de lo que el repositorio documenta, el eje Estándares siempre incluye la línea base de malos olores (smell baseline) a continuación: un conjunto fijo de malos olores de código de Fowler (Refactoring, cap. 3) que se aplica incluso cuando el repositorio no documenta nada. Dos reglas lo vinculan:
- El repositorio anula. Un estándar documentado del repositorio siempre prevalece; donde aprueba algo que la línea base marcaría, suprima el olor.
- Siempre un juicio. Cada olor es una heurística etiquetada ("posible Feature Envy"), nunca una violación estricta. Como cualquier estándar aquí, omita lo que las herramientas ya aplican.
Cada olor dice qué es → cómo arreglarlo; compárelo con el diff:
- Mysterious Name: una función, variable o tipo cuyo nombre no revela lo que hace o contiene. → renómbrelo; si no encuentra un nombre honesto, el diseño es confuso.
- Duplicated Code: la misma forma lógica aparece en más de un bloque o archivo en el cambio. → extraiga la forma compartida, llámela desde ambos lugares.
- Feature Envy: un método que accede a los datos de otro objeto más que a los propios. → mueva el método al objeto que envidia.
- Data Clumps: los mismos pocos campos o parámetros viajan juntos repetidamente (un tipo que quiere nacer). → agrúpelos en un solo tipo, pase ese.
- Primitive Obsession: un primitivo o string que representa un concepto de dominio que merece su propio tipo. → dele al concepto su propio tipo pequeño.
- Repeated Switches: el mismo
switcho cascada deifsobre el mismo tipo se repite en el cambio. → reemplácelo con polimorfismo o un mapa compartido. - Shotgun Surgery: un cambio lógico obliga a ediciones dispersas en muchos archivos del diff. → reúna todo lo que cambia en un solo módulo.
- Divergent Change: un archivo o módulo se edita por varias razones no relacionadas. → divídalo para que cada módulo cambie por una sola razón.
- Speculative Generality: abstracciones, parámetros o enlaces añadidos para necesidades que la especificación no tiene. → elimínelos; simplifique hasta que surja una necesidad real.
- Message Chains: largas navegaciones
a.b().c().d()de las que el llamador no debería depender. → oculte el recorrido tras un método en el primer objeto. - Middle Man: una clase o función que principalmente delega hacia adelante. → elimínela, llame al destino real directamente.
- Refused Bequest: una subclase o implementador que ignora o sobrescribe la mayor parte de lo que hereda. → abandone la herencia, use composición.
4. Lanzar ambos subagentes en paralelo
Emita ambas llamadas a subagentes juntas, en primer plano, y agregue los informes que devuelvan.
Prompt del subagente Estándares debe incluir:
- El comando diff completo y la lista de commits.
- La lista de archivos fuente de estándares que encontró en el paso 3, más la línea base de malos olores del paso 3 pegada en su totalidad (el subagente no tiene otro acceso a ella).
- La instrucción: "Informe, por archivo/bloque donde corresponda, (a) cada lugar donde el diff viole un estándar documentado: cite el estándar (archivo + regla); y (b) cualquier olor base que detecte: menciónelo y cite el bloque. Distinga las violaciones estrictas de los juicios: las infracciones a estándares documentados pueden ser estrictas, pero los olores base son siempre juicios, y un estándar documentado del repositorio anula la línea base. Omita lo que las herramientas ya aplican. Menos de 400 palabras."
Prompt del subagente Especificación debe incluir:
- El comando diff y la lista de commits.
- La ruta o el contenido obtenido de la especificación.
- La instrucción: "Informe: (a) requisitos que la especificación pedía y que faltan o están parciales; (b) comportamiento en el diff que no fue solicitado (scope creep); (c) requisitos que parecen implementados pero cuya implementación parece incorrecta. Cite la línea de especificación para cada hallazgo. Menos de 400 palabras."
Si la especificación falta, omita el subagente de Especificación y anótelo en el informe final.
5. Agregar
Presente los dos informes bajo los encabezados ## Standards y ## Spec, textualmente o ligeramente limpios. No fusione ni reordene los hallazgos, porque los dos ejes están deliberadamente separados (ver Por qué dos ejes).
Termine con un resumen de una línea: total de hallazgos por eje y el peor problema dentro de cada eje (si lo hay). No elija un único ganador entre los ejes: ese reordenamiento es lo que la separación busca evitar.
Por qué dos ejes
Un cambio puede pasar un eje y fallar en el otro:
- Código que sigue todos los estándares pero implementa lo incorrecto → Estándares aprueban, Especificación falla.
- Código que hace exactamente lo que pedía el issue pero rompe las convenciones del proyecto → Especificación aprueba, Estándares fallan.
Reportarlos por separado evita que un eje enmascare al otro.