Revisión en dos ejes del diff entre HEAD y un punto fijo que el usuario proporciona:
- 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 de origen?
Ambos ejes se ejecutan como subagentes paralelos para que no contaminen el contexto del otro, luego este skill agrega sus hallazgos.
El rastreador de issues debería haberte sido proporcionado. Si no es así, dile al usuario que ejecute /setup-matt-pocock-skills.
Proceso
1. Fijar el punto fijo
Cualquiera que sea el punto fijo que el usuario haya indicado (un SHA de commit, nombre de rama, tag, main, HEAD~5, etc.). Si no especificó ninguno, pregúntalo.
Captura el comando diff una vez: git diff <punto-fijo>...HEAD (con tres puntos, para que la comparación sea contra el merge-base). También anota la lista de commits mediante git log <punto-fijo>..HEAD --oneline.
Antes de continuar, confirma que el punto fijo se resuelve (git rev-parse <punto-fijo>) y que el diff no está vacío. Una referencia incorrecta o un diff vacío debe fallar aquí, no dentro de dos subagentes paralelos.
2. Identificar la fuente de la especificación
Busca la especificación de origen, en este orden:
- Referencias a issues en los mensajes de commit (
#123,Closes #45, GitLab!67, etc.), obtenidas mediante el flujo de trabajo en el documento del rastreador. - Una ruta que el usuario pasó como argumento.
- Un archivo de especificación en
docs/,specs/, o.scratch/que coincida con el nombre de la rama o la funcionalidad. - Si no se encuentra nada, pregúntale al usuario dónde está la especificación. Si dice que no hay, el subagente de Especificación se omitirá y reportará "no hay especificación disponible".
3. Identificar las fuentes de estándares
Busca en el repositorio cada archivo que documente cómo se debe escribir el código. Cuando exista CODING_STANDARDS.md o CONTRIBUTING.md, deben estar en la lista.
Además de lo que documente el repositorio, el eje de Estándares siempre lleva la línea base de smells a continuación: un conjunto fijo de code smells de Fowler (Refactoring, cap. 3) que aplica incluso cuando un 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, suprime el smell.
- Siempre es un juicio. Cada smell es una heurística etiquetada ("posible Feature Envy"), nunca una violación estricta. Como cualquier estándar aquí, omite cualquier cosa que las herramientas ya impongan.
Cada smell describe qué es → cómo solucionarlo; compáralo con el diff:
- Mysterious Name: una función, variable o tipo cuyo nombre no revela lo que hace o contiene. → renómbralo; si no se te ocurre un nombre honesto, el diseño está turbio.
- Duplicated Code: la misma forma lógica aparece en más de un bloque o archivo en el cambio. → extrae la forma compartida, llámala desde ambos.
- Feature Envy: un método que accede más a los datos de otro objeto que a los suyos propios. → mueve el método al objeto cuyos datos envidia.
- Data Clumps: los mismos pocos campos o parámetros viajan juntos repetidamente (un tipo que pide nacer). → agrúpalos en un tipo, pásalo.
- Primitive Obsession: un primitivo o cadena que representa un concepto de dominio que merece su propio tipo. → dale al concepto su propio tipo pequeño.
- Repeated Switches: el mismo
switch/if-en cascada sobre el mismo tipo aparece repetido en el cambio. → reemplázalo con polimorfismo, o un mapa que ambos sitios compartan. - Shotgun Surgery: un cambio lógico obliga a editar dispersas en muchos archivos del diff. → reagrupa lo que cambia junto en un solo módulo.
- Divergent Change: un archivo o módulo se edita por varias razones no relacionadas. → divide para que cada módulo cambie por una sola razón.
- Speculative Generality: abstracción, parámetros o hooks añadidos para necesidades que la especificación no tiene. → bórralo; refactoriza hasta que surja una necesidad real.
- Message Chains: larga navegación
a.b().c().d()de la que el llamante no debería depender. → oculta el recorrido detrás de un método en el primer objeto. - Middle Man: una clase o función que principalmente delega hacia adelante. → elimínala, llama al objetivo real directamente.
- Refused Bequest: una subclase o implementador que ignora o sobrescribe la mayor parte de lo que hereda. → quita la herencia, usa composición.
4. Lanzar ambos subagentes en paralelo
Emite ambas llamadas de subagente juntas, en primer plano, y agrega los informes que devuelvan.
Indicación para el subagente de Estándares debe incluir:
- El comando diff completo y la lista de commits.
- La lista de archivos fuente de estándares que encontraste en el paso 3, más la línea base de smells del paso 3 pegada completa (el subagente no tiene otro acceso a ella).
- La instrucción: "Reporta, por archivo/bloque donde sea relevante: (a) cada lugar donde el diff viola un estándar documentado: cita el estándar (archivo + la regla); y (b) cualquier smell de la línea base que detectes: nómbralo y cita el bloque. Distingue violaciones estrictas de juicios: las infracciones a estándares documentados pueden ser estrictas, pero los smells de la línea base son siempre juicios, y un estándar documentado del repositorio anula la línea base. Omite cualquier cosa que las herramientas ya impongan. Menos de 400 palabras."
Indicación para el subagente de 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: "Reporta: (a) requisitos que la especificación pedía y que faltan o están parciales; (b) comportamiento en el diff que no fue solicitado (sobrealcance); (c) requisitos que parecen implementados pero donde la implementación parece incorrecta. Cita la línea de la especificación para cada hallazgo. Menos de 400 palabras."
Si falta la especificación, omite el subagente de Especificación y anótalo en el informe final.
5. Agregar
Presenta los dos informes bajo los encabezados ## Estándares y ## Especificación, textualmente o ligeramente limpiados. No combines ni reordene los hallazgos, porque los dos ejes están deliberadamente separados (ver Por qué dos ejes).
Termina con un resumen de una línea: total de hallazgos por eje y el peor problema dentro de cada eje (si lo hay). No elijas un único ganador entre ejes: eso es la reordenación que la separación existe para prevenir.
Por qué dos ejes
Un cambio puede pasar un eje y fallar el otro:
- Código que sigue cada estándar pero implementa lo incorrecto → Estándares pasa, Especificación falla.
- Código que hace exactamente lo que pedía el issue pero rompe las convenciones del proyecto → Especificación pasa, Estándares falla.
Reportarlos por separado evita que un eje opaque al otro.