requesting-code-review

Descripción general

Qué hace esta skill

La skill requesting-code-review define un flujo claro y repetible para pedir a un subagente de revisión de código con IA que inspeccione tus cambios antes de integrarlos. Está pensada para proyectos basados en Git y te ayuda a:

• Decidir cuándo pedir una revisión (después de tareas, funcionalidades y antes del merge)
• Empaquetar contexto preciso para la revisión usando Git SHAs y requisitos
• Mantener al revisor centrado en el diff de código, no en el historial privado de tu sesión
• Clasificar el feedback por gravedad para saber qué corregir ahora y qué dejar para más adelante

En esencia, requesting-code-review se basa en revisar pronto y revisar a menudo para detectar problemas antes de que se propaguen por tu base de código.

A quién va dirigida

Esta skill encaja bien si:

• Trabajas con Git y creas con frecuencia ramas de feature o PRs
• Quieres una forma estructurada y repetible de solicitar revisiones de código asistidas por IA
• Utilizas desarrollo guiado por subagentes (por ejemplo, un agente dedicado code-reviewer)
• Te importa la preparación para producción: corrección, arquitectura, pruebas y alineamiento con especificaciones

Es especialmente útil para:

• Desarrolladores individuales que quieren una red de seguridad fiable
• Equipos pequeños sin revisores de código dedicados
• Proyectos donde el historial de commits y los diffs son la principal fuente de verdad

Cuándo no es una buena opción

requesting-code-review puede no ser ideal si:

• No usas Git o no tienes acceso a los SHAs de los commits
• Buscas ayuda general de generación o refactorización de código, no revisión de cambios concretos
• No puedes proporcionar un plan, especificación o requisitos claros para los cambios que se van a revisar

En esos casos, probablemente te convenga más una skill general de programación o planificación que un flujo centrado en revisión.

Problemas que resuelve

Sin un proceso de revisión consistente, los desarrolladores a menudo:

• Se olvidan de pedir revisión en momentos clave
• Comparten muy poco contexto (o demasiado historial de sesión)
• Reciben feedback desestructurado y difícil de convertir en acciones

La skill requesting-code-review resuelve estos problemas mediante:

• Definir puntos de control obligatorios y opcionales para la revisión
• Estandarizar los inputs de la revisión (rango de Git, requisitos, resumen)
• Complementarse con un subagente code-reviewer dedicado que devuelve feedback ordenado por gravedad

Cómo usarla

Instalación

Para instalar la skill requesting-code-review desde el repositorio obra/superpowers, usa la Skills CLI:

npx skills add https://github.com/obra/superpowers --skill requesting-code-review
``

Esto descarga la definición de la skill y sus archivos de soporte, incluido la plantilla del subagente `code-reviewer`.

Después de la instalación, abre el directorio de la skill y revisa primero estos archivos:

- `SKILL.md` – descripción de alto nivel y pasos del flujo para solicitar revisión de código
- `code-reviewer.md` – el prompt/plantilla del agente que realiza realmente la revisión de código

### Flujo principal de un vistazo
El flujo de `requesting-code-review` tiene tres fases principales:

1. **Decidir cuándo revisar**
   - Después de cada tarea en un flujo guiado por subagentes
   - Cuando completes una funcionalidad importante
   - Antes de hacer merge a tu rama principal
2. **Preparar el contexto de la revisión**
   - Captura el rango de commits de Git con `BASE_SHA` y `HEAD_SHA`
   - Resume qué se implementó y qué debe hacer
   - Rellena los placeholders definidos en `code-reviewer.md`
3. **Ejecutar la revisión y actuar sobre el feedback**
   - Lanza el subagente `superpowers:code-reviewer`
   - Corrige los problemas Critical inmediatamente, los Important antes de seguir, y registra los Minor

### Paso 1: Identificar el momento adecuado para revisar
Según `SKILL.md`, usa `requesting-code-review` en:

**Puntos de control obligatorios:**

- **Después de cada tarea** en desarrollo guiado por subagentes
- **Tras completar una funcionalidad importante**
- **Antes de hacer merge** a tu rama principal (por ejemplo, `main`, `master`)

**Puntos de control opcionales pero valiosos:**

- Cuando estés **bloqueado** y necesites una nueva perspectiva
- **Antes de refactorizar**, como chequeo de referencia del comportamiento actual
- Después de corregir un **bug complejo**, para asegurarte de que no hay regresiones ni problemas nuevos

Convierte en hábito activar esta skill en estos momentos para que las revisiones sean automáticas y no algo que se deja para el final.

### Paso 2: Capturar el rango de commits de Git
El revisor necesita un diff limpio y acotado. Usa los SHAs de Git para especificar el rango:

```bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA debe apuntar al commit que representa tu punto de partida, como el commit anterior o la punta de origin/main.
• HEAD_SHA debe ser el commit que incluye tu trabajo más reciente.

Puedes ajustar HEAD~1 o elegir una base distinta para adaptarte a tu estrategia de ramas, siempre que el rango capture con precisión los cambios que quieres revisar.

Paso 3: Preparar la plantilla de petición de revisión

El archivo code-reviewer.md define cómo comunicarse con el Code Review Agent. Utiliza placeholders que debes rellenar antes de lanzar el subagente.

Placeholders clave:

• {WHAT_WAS_IMPLEMENTED} – Descripción concisa de lo que acabas de construir o cambiar
• {PLAN_OR_REQUIREMENTS} – La especificación, ticket o requisitos de negocio que la implementación debe cumplir
• {BASE_SHA} – El SHA del commit inicial para el diff
• {HEAD_SHA} – El SHA del commit final para el diff
• {DESCRIPTION} – Resumen breve del conjunto de cambios (por ejemplo, "Add verification function and tests for user signups")
• {PLAN_REFERENCE} – Una referencia a tu documento de plan o requisitos

En tus propias herramientas, rellena estos placeholders antes de lanzar el subagente superpowers:code-reviewer con la Task tool.

Paso 4: Lanzar el subagente code-reviewer

Con tus SHAs de Git y la plantilla completada:

1. Usa la Task tool de tu entorno de orquestación (según lo descrito en el framework superpowers) con el tipo superpowers:code-reviewer.

2. Pasa el contenido de code-reviewer.md ya renderizado, con los placeholders sustituidos por tus valores reales.

3. Asegúrate de que el agente pueda acceder al diff de Git para el rango:

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   La plantilla indica estos comandos para que el revisor se centre estrictamente en los cambios entre BASE_SHA y HEAD_SHA.

El diseño de esta skill garantiza que el agente de revisión vea solo el producto del trabajo (commits y diff), no el historial más amplio de tu sesión ni contexto irrelevante.

Paso 5: Interpretar y actuar sobre el feedback

La plantilla code-reviewer.md instruye al agente para:

• Evaluar la calidad del código (separación de responsabilidades, manejo de errores, DRY, edge cases)
• Revisar la arquitectura (diseño, escalabilidad, rendimiento, seguridad)
• Comprobar las pruebas (cobertura, puntos de integración, calidad de los tests)
• Verificar los requisitos (alineamiento con la especificación, sin scope creep, cambios rompientes documentados)
• Valorar la preparación para producción (migraciones, compatibilidad hacia atrás, documentación)

El feedback se clasifica en:

• Critical (Must Fix) – Bugs, problemas de seguridad, riesgos de pérdida de datos, funcionalidad rota
• Important (Should Fix) – Problemas de arquitectura, funcionalidades ausentes, mal manejo de errores, huecos en las pruebas
• Minor (Nice to Have) – Estilo, optimizaciones, mejoras de documentación

El flujo correspondiente definido en SKILL.md es:

• Corregir los problemas Critical antes de continuar
• Corregir los problemas Important antes de seguir con más trabajo o hacer merge
• Anotar los problemas Minor para limpieza posterior o tareas de seguimiento
• Rebatir, con argumentos, si el revisor se equivoca o le falta contexto

Siguiendo esta priorización, conviertes el feedback de la IA en una lista de acciones concreta en lugar de un conjunto de sugerencias vagas.

Ejemplo de uso típico

Un uso habitual de requesting-code-review podría ser:

1. Terminas la "Task 2: Add verification function" en tu rama de feature.

2. Capturas los SHAs:

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. Rellenas los placeholders de code-reviewer.md con:

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = Enlace o resumen del ticket/requisitos
   • {BASE_SHA} y {HEAD_SHA} = Los valores obtenidos de Git
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. Lanzas el subagente superpowers:code-reviewer usando tu Task tool.

5. Recibes feedback estructurado agrupado en Critical, Important y Minor.

6. Atiendes los problemas Critical e Important y, si quieres, vuelves a ejecutar el proceso antes de hacer merge.

Preguntas frecuentes (FAQ)

¿requesting-code-review es solo para repositorios de GitHub?

No. La skill requesting-code-review está basada en Git, no es específica de GitHub. Se apoya en los SHAs de los commits y en comandos git diff, por lo que funciona con cualquier remoto Git (GitHub, GitLab, Bitbucket o self-hosted) siempre que puedas proporcionar BASE_SHA y HEAD_SHA.

¿Tengo que compartir todo el historial de mi sesión de desarrollo?

No. Un principio clave de diseño de requesting-code-review es que el revisor recibe solo contexto muy acotado: qué se implementó, los requisitos y el diff de Git. El historial general de tu sesión y tu proceso interno de pensamiento permanecen privados, mientras que el revisor se centra en los cambios reales de código.

¿Cuándo debo activar requesting-code-review en mi flujo de trabajo?

Usa requesting-code-review:

• Después de cada tarea en desarrollo guiado por subagentes
• Tras completar una funcionalidad importante
• Antes de hacer merge a tu rama principal

También puedes activarla cuando estés bloqueado, antes de grandes refactors o después de corregir bugs complejos, para detectar riesgos ocultos cuanto antes.

¿Cómo se integra esto con mis revisiones de pull request actuales?

requesting-code-review complementa, en lugar de sustituir, las revisiones de PR hechas por personas. Puedes:

• Ejecutar la skill antes de abrir un PR para detectar problemas obvios
• Usarla junto con revisores humanos para mejorar la cobertura y la consistencia
• Aplicar sus categorías de feedback estructurado (Critical/Important/Minor) a tus comentarios en PR

Como la skill se basa en rangos de Git, encaja de forma natural en flujos de trabajo basados en PR.

¿Puedo personalizar el comportamiento del agente code-reviewer?

Sí. El archivo code-reviewer.md es una plantilla que puedes adaptar:

• Ajusta las checklists de calidad de código, arquitectura, pruebas o seguridad
• Añade preocupaciones específicas de tu proyecto (por ejemplo, reglas de dominio, presupuestos de rendimiento)
• Refina el formato de salida si quieres niveles de gravedad distintos o secciones adicionales

Solo mantén la estructura básica (tarea clara, rango de Git y categorías de gravedad) para que la revisión siga siendo enfocada y accionable.

¿Qué pasa si el revisor sugiere algo incorrecto?

La skill te anima explícitamente a rebatir con argumentos cuando el revisor se equivoque o le falte contexto. Trata la revisión como una recomendación potente, no como un veredicto incuestionable. Aclara restricciones, explica trade-offs o actualiza tu plan para que las revisiones futuras estén mejor alineadas.

¿requesting-code-review genera tests o cambios de código por mí?

No. Esta skill trata de revisión, no de generación. Te ayuda a:

• Solicitar revisiones dirigidas sobre cambios específicos
• Recibir feedback estructurado sobre calidad, arquitectura y pruebas

Tú sigues siendo responsable de aplicar las correcciones y escribir tests, aunque puedes combinar esta skill con otras de generación de código o tests dentro de tu toolchain.

¿Cómo empiezo rápido?

1. Instala la skill:

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. Lee SKILL.md para entender los puntos de control de revisión.

3. Revisa code-reviewer.md para ver la checklist del agente y el formato de salida.

4. Ejecuta tu próxima tarea o feature, captura BASE_SHA y HEAD_SHA y lanza el subagente superpowers:code-reviewer.

A partir de ahí, ajusta la plantilla y el flujo hasta que requesting-code-review encaje con los hábitos y el nivel de calidad de tu equipo.