¿Qué hace shorts-ai?
Revisión en dos ejes del diff entre HEAD y un punto fijo que el usuario proporcione:
- Estándares: ¿el código cumple con las normas de codificación documentadas en este repositorio?
- Especificación: ¿el código implementa fielmente el issue o especificación de origen?
Ambos ejes se ejecutan como subagentes paralelos para no contaminar sus contextos, y luego esta habilidad agrega sus hallazgos.
El rastreador de issues debería haberse proporcionado. Si no es así, dile al usuario que ejecute /setup-matt-pocock-skills.
Proceso
1. Fijar el punto de referencia
Sea lo que sea que el usuario haya indicado como punto fijo (un SHA de commit, nombre de rama, etiqueta, main, HEAD~5, etc.). Si no especificó uno, pídelo.
Captura el comando diff una vez: git diff <punto-fijo>...HEAD (tres puntos, para que la comparación sea contra la base de fusión). También anota la lista de commits mediante git log <punto-fijo>..HEAD --oneline.
Antes de continuar, confirma que el punto fijo resuelve (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 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 haya pasado 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, pregunta al usuario dónde está la especificación. Si dice que no hay, el subagente de Especificación se saltará e informará "no hay especificación disponible".
3. Identificar las fuentes de estándares
Busca en el repositorio todos los archivos que documentan cómo se debe escribir el código. Cuando existan 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 olores a continuación: un conjunto fijo de olores de código de Fowler (Refactoring, cap. 3) que se aplica incluso cuando un repositorio no documenta nada. Dos reglas lo rigen:
- El repositorio anula. Un estándar documentado del repositorio siempre prevalece; donde apruebe algo que la línea base marcaría, se suprime el olor.
- Siempre es un juicio. Cada olor es una heurística etiquetada ("posible Envidia de Características"), nunca una violación estricta. Al igual que cualquier estándar aquí, sáltate cualquier cosa que las herramientas ya apliquen.
Cada olor describe qué es → cómo arreglarlo; compáralo con el diff:
- Nombre Misterioso: 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 es confuso.
- Código Duplicado: 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.
- Envidia de Características: un método que accede más a los datos de otro objeto que a los propios. → mueve el método al objeto que envidia.
- Grupos de Datos: los mismos pocos campos o parámetros viajan juntos repetidamente (un tipo que quiere nacer). → agrúpalos en un solo tipo y pásalo.
- Obsesión por Primitivos: un primitivo o cadena que representa un concepto de dominio que merece su propio tipo. → dale al concepto su propio tipo pequeño.
- Switches Repetidos: el mismo
switch/if-en cascada sobre el mismo tipo aparece repetido en el cambio. → reemplázalo con polimorfismo o un mapa compartido por ambos sitios. - Cirugía de Escopeta: un cambio lógico fuerza ediciones dispersas en muchos archivos del diff. → agrupa lo que cambia junto en un solo módulo.
- Cambio Divergente: un archivo o módulo se edita por varias razones no relacionadas. → divídelo para que cada módulo cambie por una sola razón.
- Generalidad Especulativa: abstracciones, parámetros o ganchos añadidos para necesidades que la especificación no tiene. → elimínalos; simplifica hasta que surja una necesidad real.
- Cadenas de Mensajes: larga navegación
a.b().c().d()de la que el llamador no debería depender. → oculta el recorrido detrás de un método en el primer objeto. - Hombre del Medio: una clase o función que principalmente delega hacia adelante. → elimínala, llama al destino real directamente.
- Herencia Rechazada: una subclase o implementador que ignora o sobrescribe la mayor parte de lo que hereda. → abandona la herencia, usa composición.
4. Lanzar ambos subagentes en paralelo
Emite ambas llamadas de subagentes 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 olores del paso 3 pegada completa (el subagente no tiene otro acceso a ella).
- La instrucción: "Informa, por archivo/bloque donde corresponda, (a) cada lugar donde el diff viola un estándar documentado: cita el estándar (archivo + la regla); y (b) cualquier olor de la línea base que detectes: nómbralo y cita el bloque. Distingue las violaciones estrictas de los juicios: las infracciones a estándares documentados pueden ser estrictas, pero los olores 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 apliquen. 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: "Informa: (a) requisitos que la especificación pedía y que faltan o están parciales; (b) comportamiento en el diff que no se solicitó (expansión del alcance); (c) requisitos que parecen implementados pero cuya 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 limpios. No fusiones ni reordenes 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 busca evitar.
Por qué dos ejes
Un cambio puede aprobar un eje y fallar el otro:
- Código que sigue todos los estándares pero implementa lo incorrecto → Estándares aprueba, 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 falla.
Informarlos por separado evita que un eje oculte al otro.