requesting-code-review

Visión general de la skill requesting-code-review

La skill requesting-code-review es un flujo de trabajo ligero para lanzar una revisión de código enfocada en el momento adecuado, con el diff correcto y con suficiente contexto de implementación para que un agente revisor pueda dar feedback útil. En lugar de pedir algo vago como “por favor revisa mi código”, te obliga a pasar un rango de commits, un resumen de lo que cambió y los requisitos previstos.

Qué hace realmente la skill requesting-code-review

En esencia, requesting-code-review te indica que llames al subagente superpowers:code-reviewer usando una plantilla preparada en code-reviewer.md. Lo que la diferencia no es una automatización sofisticada, sino cómo encuadra la revisión. El revisor ve el entregable y el plan, no todo el historial de tu sesión, lo que mantiene la revisión más acotada y más fácil de convertir en acciones concretas.

Quién debería instalar requesting-code-review

Esta skill encaja mejor para desarrolladores y usuarios de agentes de IA que:

• trabajan con flujos basados en commits
• entregan funcionalidades por etapas
• quieren un checkpoint repetible de “revisar antes de seguir”
• usan subagentes y necesitan un traspaso más limpio que un prompt genérico

Resulta especialmente útil si sueles pedir revisión demasiado tarde, cuando ya se acumularon varias tareas en un único diff grande.

El verdadero trabajo que resuelve

Los usuarios no instalan requesting-code-review solo para “obtener una revisión”. La instalan para reducir retrabajo evitable:

• detectar problemas antes del merge
• validar contra el plan original
• recibir feedback priorizado por severidad
• conservar el contexto de la tarea principal mientras un agente revisor inspecciona el código por separado

Por qué esta skill es más útil que un prompt de revisión genérico

La requesting-code-review skill añade estructura práctica que muchos prompts improvisados no tienen:

• guía sobre cuándo revisar: después de cada tarea, tras funcionalidades importantes, antes del merge
• entradas explícitas BASE_SHA y HEAD_SHA
• una plantilla de revisión con comprobaciones de calidad de código, arquitectura, testing, requisitos y preparación para producción
• niveles de severidad que facilitan el seguimiento

Eso hace que la salida sea más accionable que un simple “revisa mis últimos cambios”.

Qué importa más antes de adoptarla

La gran pregunta de adopción es el encaje: esta skill funciona mejor cuando tu trabajo puede representarse como un rango de git limpio y cuando puedes describir brevemente el comportamiento esperado. Si tu rama está desordenada, tu plan no está claro o tus cambios están mezclados con ediciones no relacionadas, la calidad de la revisión va a caer.

Limitación importante que conviene conocer desde el principio

requesting-code-review for Code Review no es, por sí sola, un sistema completo de revisión. No incluye scripts, reglas de enforcement ni verificadores específicos del repositorio. Es un patrón disciplinado de prompting y handoff. Eso aporta valor, pero debes asumir que la calidad dependerá en gran medida del rango de commits y de la claridad de tus requisitos.

Cómo usar la skill requesting-code-review

Instala requesting-code-review en tu configuración de skills

Si estás usando el patrón de Skills CLI que se usa en todo el repositorio, instálala con:

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

Si tu entorno ya tiene disponible la colección obra/superpowers, simplemente habilita o referencia la skill requesting-code-review desde ese pack.

Lee primero estos archivos

Para evaluarla rápido, empieza por:

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

SKILL.md explica cuándo conviene invocar la revisión. code-reviewer.md es el archivo más importante si te importa la calidad de la salida, porque muestra exactamente qué se le pide al revisor que evalúe.

Entiende los puntos de activación previstos

La skill está pensada para usarse:

• después de cada tarea en un desarrollo guiado por subagentes
• después de una funcionalidad importante
• antes de hacer merge a main

Momentos opcionales pero de mucho valor incluyen:

• cuando estás atascado y quieres una mirada fresca
• antes de un refactor arriesgado
• después de corregir un bug complejo

Si solo la usas al final de una rama grande, pierdes buena parte de su ventaja.

Reúne los datos mínimos antes de invocarla

La skill funciona mejor cuando aportas:

• qué se implementó
• el plan o los requisitos
• BASE_SHA
• HEAD_SHA
• una breve descripción del cambio

Comandos git típicos:

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

En ramas de funcionalidad, origin/main puede ser una mejor base que HEAD~1 si quieres una ventana de revisión más amplia.

Usa un rango de diff limpio, no un “último trabajo” ambiguo

Esta es la parte de mayor impacto en el patrón de requesting-code-review usage. Una revisión ligada a BASE_SHA..HEAD_SHA es mucho mejor que pedirle a un agente que deduzca qué cambió a partir de tu working tree o del historial del chat.

Bien:

• “Review commits from feature start to current head against the signup flow requirements.”

Débil:

• “Can you review my recent auth changes?”

La versión más sólida acota el alcance y reduce las suposiciones del revisor.

Convierte un objetivo difuso en una solicitud de revisión sólida

Una petición poco trabajada como esta se queda corta:

Please review my new feature.

Una solicitud más sólida basada en la skill se vería así:

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

Eso le da al revisor suficiente contexto para juzgar la corrección, no solo el estilo.

Lanza el subagente revisor como espera la skill requesting-code-review

La guía del repositorio indica usar la herramienta Task con el tipo superpowers:code-reviewer y completar la plantilla de code-reviewer.md. Esa plantilla pide al revisor que:

• compare la implementación frente al plan
• inspeccione el git diff
• revise calidad, arquitectura, testing y preparación para producción
• devuelva hallazgos por severidad

Si tu plataforma de agentes soporta subagentes, mantén la revisión aislada en lugar de mezclarla en la misma conversación de trabajo.

Qué está optimizada para detectar la plantilla del revisor

La checklist incluida funciona especialmente bien para sacar a la luz:

• requisitos ausentes
• huecos evidentes de preparación para producción
• problemas de cobertura de pruebas
• preocupaciones de arquitectura
• casos límite peligrosos
• omisiones de compatibilidad hacia atrás o de migraciones

Es menos especializada para compliance de dominio, convenciones específicas del repo o verificación profunda en runtime, salvo que añadas eso de forma explícita.

Flujo de trabajo recomendado para proyectos reales

Una requesting-code-review guide práctica sería así:

1. termina una tarea bien acotada
2. identifica el rango exacto del diff
3. resume la intención y los criterios de aceptación
4. lanza el revisor con la plantilla
5. corrige los problemas críticos e importantes
6. vuelve a ejecutar la revisión si los cambios de corrección son sustanciales
7. continúa el desarrollo o haz merge

Esta skill es más efectiva como checkpoint entre pasos de implementación, no solo como puerta final.

Consejos que mejoran de verdad la calidad de la salida

Para obtener mejores revisiones:

• usa un rango de diff que contenga un solo cambio lógico
• incluye criterios de aceptación, no solo el nombre de la funcionalidad
• menciona áreas de riesgo como migraciones, auth, concurrencia, caché o contratos de API
• indica si se añadieron pruebas y de qué tipo
• aclara si se esperan breaking changes o si están prohibidos

Estos detalles ayudan al revisor a distinguir entre decisiones deliberadas y omisiones accidentales.

Uso incorrecto habitual que reduce su valor

La decisión de requesting-code-review install tiene menos sentido si tu equipo hace esto de forma habitual:

• mete muchos cambios no relacionados en un mismo rango
• no tiene requisitos por escrito
• no usa límites de git con sentido
• espera que la skill reemplace la aprobación humana o CI

En esos casos, conviene ordenar primero el flujo de trabajo o asumir revisiones más ruidosas.

Preguntas frecuentes sobre la skill requesting-code-review

¿requesting-code-review es buena para principiantes?

Sí, si ya entiendes conceptos básicos de git como commits y SHAs. La skill es simple, pero da por hecho que puedes definir qué cambió y qué se suponía que debía hacer. Los principiantes que omiten ese contexto seguirán recibiendo feedback, pero será menos fiable.

¿Esta skill revisa cambios no committeados?

No por diseño. El flujo está construido alrededor de BASE_SHA y HEAD_SHA, así que funciona mejor con trabajo ya committeado. Puedes adaptarla para cambios sin staging o sin commit, pero eso se aleja de la estructura central de la skill y normalmente hace que la revisión sea menos reproducible.

¿En qué se diferencia requesting-code-review de pedirle a una IA que revise mi código?

Un prompt normal suele producir una revisión genérica porque el modelo tiene que inferir el alcance, la intención y los criterios de aceptación. requesting-code-review mejora esto al exigir:

• un diff explícito
• un resumen claro de la implementación
• el plan original o los requisitos
• un formato de salida basado en severidad

El resultado suele ser más fácil de confiar y más fácil de convertir en acciones.

¿Cuándo no debería usar requesting-code-review?

Sáltatela cuando:

• tu cambio está demasiado incompleto para evaluarlo
• el diff mezcla varias funcionalidades no relacionadas
• aún no sabes cuál es el comportamiento esperado
• necesitas más checks estáticos específicos del repo que una revisión basada en criterio

También encaja mal si tu equipo nunca trabaja a partir de rangos de commits de git.

¿Reemplaza la revisión humana de código?

No. Su mejor uso es como pre-review o como control de calidad entre pasos. Puede detectar problemas pronto y hacer más fluida la revisión humana posterior, pero no sustituye la experiencia de dominio, las convenciones del equipo ni los requisitos de aprobación de la organización.

¿requesting-code-review es solo para funcionalidades grandes?

No. De hecho, brilla más con diffs pequeños. La skill fomenta explícitamente una revisión temprana y frecuente, que muchas veces es más eficaz que esperar a una única pasada final sobre un cambio grande.

¿Qué nivel de encaje con el ecosistema debería esperar?

Esta skill encaja mejor dentro del flujo de obra/superpowers, especialmente si ya usas subagentes. Es más ligera que un framework completo de revisión y más fácil de adoptar que montar automatización de revisión a medida, pero eso también implica menos guardrails.

Cómo mejorar la skill requesting-code-review

Dale al revisor mejores requisitos, no solo mejor código

El fallo más común es un contexto de plan débil. Si solo dices “implemented notifications”, el revisor no puede saber si una ruta de reintento ausente es un bug o algo que queda fuera de alcance. Añade expectativas concretas:

• condiciones de activación
• comportamiento ante errores
• expectativas de compatibilidad hacia atrás
• requisitos de rendimiento o seguridad

Mejores requisitos producen mejores criterios de revisión.

Usa la porción de revisión más pequeña que siga teniendo sentido

La requesting-code-review skill rinde mejor con una sola tarea o un conjunto de cambios estrechamente relacionados. Si el diff incluye trabajo de esquema, cambios de API, actualizaciones de UI y limpieza no relacionada, los hallazgos se vuelven más amplios y menos accionables. Divide el trabajo en unidades revisables siempre que puedas.

Elige bien el commit base

Un BASE_SHA malo genera feedback engañoso. Si usas HEAD~1 pero la funcionalidad abarca seis commits, el revisor ve demasiado poco. Si usas una base muy antigua, verá demasiado ruido. Elige la base que corresponda a la unidad lógica de trabajo que quieres que se evalúe.

Sustituye los placeholders por detalles concretos que el revisor pueda comprobar mentalmente

La plantilla incluida usa placeholders como:

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

No los rellenes con resúmenes de una sola línea si el cambio tiene riesgo. Indica el comportamiento real esperado. Por ejemplo, “prevents user enumeration and invalidates token after first successful reset” es mucho más fuerte que “added password reset.”

Dile al revisor dónde está el riesgo

Si ya sabes cuáles son las superficies de riesgo, dilo:

• “Please pay special attention to race conditions around token reuse.”
• “Check backward compatibility for existing API consumers.”
• “Focus on whether tests cover the error path and expiry boundary.”

Eso concentra la atención y aumenta las probabilidades de obtener hallazgos útiles.

Refuerza la revisión después de la primera pasada

Después de la salida inicial:

1. corrige los problemas críticos que sean claramente válidos
2. cuestiona los hallazgos que parezcan erróneos
3. aclara los requisitos que falten
4. ejecuta una segunda revisión sobre el diff actualizado si los cambios son sustanciales

La propia skill anima a rebatir al revisor cuando se equivoca. Eso es buena señal: está pensada para apoyar el criterio, no para reemplazarlo.

Añade criterios de revisión específicos del repo cuando haga falta

El code-reviewer.md estándar cubre bien las dimensiones comunes de revisión, pero muchos equipos necesitan más. Mejora requesting-code-review for Code Review añadiendo checks específicos de tu proyecto, como:

• reglas de despliegue de migraciones
• requisitos de observabilidad
• expectativas de accesibilidad
• puntos de revisión de seguridad
• convenciones del lenguaje o del framework

Esta es la mejora más importante si quieres una salida menos genérica.

Vigila estos fallos recurrentes

Las caídas de calidad suelen venir de:

• requisitos ausentes o vagos
• rangos de commits ruidosos
• no mencionar el comportamiento no funcional esperado
• pedir revisión después de acumular demasiadas tareas
• tratar sugerencias menores como obligatorias mientras se escapan problemas críticos de diseño

Si la salida te parece superficial, revisa primero las entradas.

Mejora la salida pidiendo decisiones, no solo defectos

Un patrón de requesting-code-review usage más sólido es pedirle al revisor que también evalúe tradeoffs. Ejemplos:

• “Flag any unnecessary complexity.”
• “Call out if this should be split before merge.”
• “Assess whether current tests justify production readiness.”

Eso lleva la revisión más allá de comentarios tipo lint hacia una evaluación más cercana a la calidad de release.

Forma práctica de evolucionar la skill en tu propia configuración

Si vas a adoptar esta skill en serio, personaliza primero estas tres cosas:

1. tu regla preferida para seleccionar el base commit
2. un formato estándar para requisitos y criterios de aceptación
3. ítems extra de checklist para tu stack y tu proceso de release

Esas incorporaciones conservan la simplicidad de requesting-code-review y al mismo tiempo la vuelven mucho más útil en el trabajo diario de entrega.