receiving-code-review

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

Para qué sirve la skill receiving-code-review

La receiving-code-review skill ayuda a una IA a responder a comentarios de code review con criterio técnico, en lugar de asentir automáticamente. Su función es sencilla pero muy valiosa: cuando una persona revisora propone cambios, el agente debe primero entender la petición, comprobarla contra el codebase real y solo entonces implementar o rebatir con fundamento.

Esto resulta especialmente útil cuando los comentarios de revisión son ambiguos, parcialmente incorrectos, contradictorios o arriesgados de aplicar a ciegas. La receiving-code-review skill no está pensada para sonar amable en un hilo de PR. Está pensada para evitar cambios malos causados por reflejos sociales como “tienes razón, lo arreglo” antes de validar el problema.

Para quién encaja mejor

Esta skill encaja especialmente bien para:

• desarrolladores que usan IA para ayudar a procesar comentarios de PR
• equipos que quieren menos acuerdo performativo y más precisión técnica
• agentes que trabajan en codebases maduros donde las sugerencias de revisión pueden no encajar con las restricciones locales
• usuarios que quieren un flujo repetible para responder revisiones, no solo un prompt más amable

Si tu problema principal es “el modelo implementa demasiado rápido el feedback del revisor y rompe cosas”, esta skill ataca directamente ese modo de fallo.

El trabajo real que resuelve

Normalmente, los usuarios no necesitan ayuda para leer un comentario. Lo que necesitan es ayuda para decidir:

• qué quiere decir realmente la persona revisora
• si la sugerencia es correcta para este repositorio
• si hace falta pedir aclaración antes de cambiar nada
• cómo responder si la persona revisora está equivocada o se queda corta
• cómo implementar de forma segura si el feedback es válido

Ese es el valor práctico de la receiving-code-review skill: convierte la entrada de comentarios de revisión en un flujo de verificación.

Qué diferencia a esta skill de un prompt genérico de revisión

Un prompt normal suele empujar al modelo hacia la complacencia: resumir el feedback, dar las gracias a la persona revisora y empezar a editar. En cambio, esta skill impone un patrón de respuesta:

1. leer todo el feedback
2. reformular el requisito
3. verificarlo contra la realidad del codebase
4. evaluar el encaje técnico
5. responder con acuse, preguntas o desacuerdo razonado
6. implementar un punto cada vez

Además, prohíbe explícitamente respuestas habituales de poco valor, como los elogios exagerados o el compromiso inmediato antes de validar.

Qué conviene saber antes de instalarla

Es una skill ligera y de propósito estrecho. No incluye scripts auxiliares, referencias ni reglas específicas de repositorio. Eso es positivo si buscas algo fácil de adoptar, pero también significa que la calidad de la salida depende mucho del comentario de revisión y del contexto de código que aportes.

Conviene leer esta skill como una guía de comportamiento para flujos de Code Review, no como un framework completo de automatización de revisiones.

Cómo usar la skill receiving-code-review

Cómo instalar la skill receiving-code-review

Instálala desde el repositorio obra/superpowers:

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

Si tu entorno usa otro cargador de skills, añade la skill desde:

https://github.com/obra/superpowers/tree/main/skills/receiving-code-review

Como este repositorio solo expone SKILL.md para esta skill, tanto la instalación como la inspección son directas.

Qué leer primero en el repositorio

Si estás valorando la receiving-code-review install, empieza por:

• skills/receiving-code-review/SKILL.md

Ese archivo concentra casi todo el comportamiento útil:

• el principio central
• el patrón de respuesta
• las respuestas prohibidas
• la regla para manejar feedback poco claro

No hay directorios extra como rules/, resources/ ni scripts de apoyo que debas aprender antes, así que el tiempo hasta entenderla es bajo.

Cuándo invocar receiving-code-review en la práctica

Usa la receiving-code-review skill justo cuando llega el feedback, antes de empezar a cambiar código.

Buenos casos de activación:

• “Please simplify this logic.”
• “This should use a transaction.”
• “Fix comments 1–6.”
• “Why not just cache this?”
• “Use pattern X instead.”

Conviene invocarla especialmente cuando:

• los comentarios llegan en lote
• algunos puntos no están claros
• la persona revisora puede no conocer las restricciones arquitectónicas locales
• la IA tiene la tentación de empezar a parchear de inmediato

Qué entrada necesita la skill

La skill funciona mejor cuando le das estas cuatro cosas:

1. el feedback exacto de la revisión
2. las rutas de archivo afectadas o el diff
3. las restricciones relevantes del codebase
4. el siguiente paso que quieres dar

Entradas útiles:

• comentarios de PR copiados literalmente
• la implementación actual
• fallos de tests o restricciones de rendimiento
• reglas de arquitectura que puedan entrar en conflicto con la sugerencia
• si quieres un borrador de respuesta, una evaluación o ayuda de implementación

Sin contexto del codebase, la skill puede seguir ayudando a interpretar comentarios, pero no puede verificar bien el encaje técnico.

Cómo convertir un objetivo impreciso en un prompt sólido

Prompt débil:

Handle this review feedback.

Prompt más sólido:

Use the receiving-code-review skill.

Review feedback:
"Please combine these queries and move validation into the controller."

Context:
- Files: app/services/order_sync.rb, app/controllers/orders_controller.rb
- Current pattern: validation is intentionally kept out of controllers
- This code handles retry behavior and partial failures
- I want to know whether the suggestion is correct for this codebase

Please:
1. Restate what the reviewer is asking
2. Identify any ambiguity
3. Verify the suggestion against the current design
4. Recommend whether to implement, ask a question, or push back
5. If valid, propose the smallest safe change

Esto funciona mejor porque da a la skill material suficiente para ejecutar el paso clave: verificar, no solo parafrasear.

Un flujo práctico de receiving-code-review

Un flujo fiable de receiving-code-review usage se parece a esto:

1. pega el hilo completo de revisión o el lote de comentarios
2. pide al agente que separe los puntos claros de los no claros
3. exige que reformule cada cambio solicitado
4. haz que compruebe cada punto contra el codebase
5. pide una recomendación: implementar, aclarar o discrepar
6. solo entonces pasa a editar, un problema cada vez

Esto evita el error habitual de implementar parcialmente un lote de comentarios mientras todavía se entiende mal el resto.

Cómo manejar comentarios poco claros o agrupados con receiving-code-review

Una de las ideas más fuertes de la skill es esta: si algún punto no está claro, detente antes de implementar.

Eso importa en PRs reales porque los comentarios suelen depender unos de otros. Si una persona revisora dice “Fix points 1–6” y los puntos 4–5 no están claros, implementar 1–3 y 6 puede dejarte atrapado en una dirección equivocada.

Un prompt sólido en este caso es:

Use receiving-code-review. Group this feedback into:
- clear and ready to verify
- unclear and needs clarification
Do not recommend implementation until all linked items are understood.

Qué aspecto debe tener una buena salida de esta skill

Un buen resultado no es “Thanks, great catch.” Debería incluir:

• una reformulación clara de la petición técnica de la persona revisora
• cualquier supuesto o ambigüedad
• verificación contra el código real
• una decisión con su razonamiento
• o bien una pregunta de aclaración, una objeción respetuosa o un plan de implementación seguro

Si la salida salta directamente del comentario al cambio de código, la skill no se está usando bien.

Patrones de prompt recomendados para trabajo de Code Review

Usa estos patrones según tu objetivo.

Solo para evaluar:

Use the receiving-code-review skill to evaluate whether this review comment is technically correct for this repository. Do not implement yet.

Para redactar una respuesta:

Use the receiving-code-review skill to write a concise technical reply to this PR comment. Avoid praise language. Ask for clarification if needed.

Para implementar después de validar:

Use the receiving-code-review skill. First verify the reviewer's request against the codebase. If valid, propose the smallest testable change and list risks before editing.

Consejos prácticos que mejoran la calidad de salida

Pequeñas mejoras en la entrada marcan una gran diferencia:

• incluye las palabras exactas de la persona revisora, no tu paráfrasis
• incluye código cercano, no solo la función objetivo
• indica si la persona revisora está hablando de estilo, corrección, rendimiento o arquitectura
• dile al modelo qué aspectos no son negociables en tu codebase
• pídele que detecte dónde la persona revisora puede estar dando por ciertos hechos que no están demostrados

Esta skill mejora cuando el agente puede comparar el cambio solicitado con la realidad del repositorio.

Preguntas frecuentes sobre la skill receiving-code-review

¿receiving-code-review sirve solo para responder a personas en comentarios de PR?

No. Es igual de útil para una evaluación interna antes incluso de responder. En muchos casos, el mejor primer uso de receiving-code-review es privado: determinar si el comentario es correcto, incompleto o inseguro antes de redactar cualquier respuesta pública.

¿Es una skill apta para principiantes?

Sí, con una salvedad. El flujo es fácil de entender, pero a quienes están empezando puede seguir faltándoles el contexto técnico necesario para juzgar si el feedback encaja en el codebase. La skill mejora la disciplina; no sustituye el criterio de ingeniería.

¿En qué se diferencia de los prompts normales de “analiza este feedback de PR”?

La diferencia clave es que incorpora un rechazo explícito a estar de acuerdo al instante. La receiving-code-review guide en SKILL.md pone en el centro la verificación, la aclaración y la objeción justificada. Los prompts genéricos suelen optimizar más por una interacción social fluida que por la corrección.

¿Cuándo no debería usar la skill receiving-code-review?

Sáltatela cuando la tarea ya esté completamente especificada y sea mecánicamente segura, por ejemplo:

• aplicar una corrección tipográfica evidente
• renombrar un símbolo sin impacto en el comportamiento
• seguir una convención de equipo ya confirmada y documentada

Tampoco es la herramienta adecuada para hacer una revisión saliente completa del código de otra persona. Esta skill trata específicamente de recibir bien el feedback.

¿Puede receiving-code-review ayudar cuando la persona revisora se equivoca?

Sí. De hecho, ese es uno de sus casos de uso más fuertes. La skill fomenta una respuesta técnica razonada en lugar de un tono defensivo o de la obediencia automática. Si la sugerencia de la persona revisora entra en conflicto con el codebase, lo esperable es que el agente explique por qué y proponga una respuesta más clara.

¿Admite feedback de revisión en lote?

Sí, pero solo si proporcionas el lote completo y dejas que la skill separe los puntos claros de los ambiguos. La skill da a entender con fuerza que una comprensión parcial debe bloquear la implementación. Eso es especialmente útil en situaciones del tipo “arregla todos estos comentarios”.

Cómo mejorar la skill receiving-code-review

Dale a la skill la realidad del repositorio, no solo el texto del revisor

La forma más rápida de mejorar la salida de receiving-code-review es acompañar los comentarios con:

• rutas de archivo
• fragmentos de la implementación actual
• restricciones
• tests
• patrones de arquitectura relevantes

No se puede evaluar una sugerencia de revisión en abstracto si depende de decisiones de diseño locales.

Pide una decisión, no solo un resumen

Muchas ejecuciones flojas ocurren porque el prompt solo pide al agente que “procese” el feedback. Los mejores prompts fuerzan una elección:

• implementar
• hacer una pregunta de aclaración
• rebatir con razonamiento
• posponer a la espera de contexto que falta

Así la skill se vuelve operativa, no meramente descriptiva.

Evita el modo de fallo más común

El mayor modo de fallo es la implementación prematura. El modelo ve una sugerencia de la persona revisora y empieza a editar antes de comprobar:

• si la persona revisora entendió el código actual
• si las restricciones hacen inválida la sugerencia
• si otros comentarios cambian el sentido
• si el cambio pedido tiene efectos secundarios ocultos

Díselo explícitamente al agente: “Do not implement until verification is complete.”

Aporta mejores entradas para hilos de revisión ambiguos

Si el feedback es vago, añade tú mismo el marco que falta:

Use receiving-code-review.

The reviewer says: "This flow should be simplified."
Please identify at least 3 plausible interpretations, map each to the current code, and tell me what clarification question would unblock implementation safely.

Eso es mucho mejor que pedir al modelo que adivine un único significado y siga adelante.

Haz que la objeción sea técnica y concisa

Si la persona revisora se equivoca, la mejor salida es breve, específica y basada en evidencia. Pide:

• el supuesto que parece estar haciendo la persona revisora
• el hecho del codebase que entra en conflicto con ese supuesto
• la respuesta más breve y respetuosa que explique el desajuste

Así el flujo de receiving-code-review for Code Review sigue siendo útil en vez de volverse confrontativo.

Itera después de la primera respuesta

Tras la primera ejecución, mejora el resultado aportando la pieza que todavía falte:

• intención poco clara de la persona revisora
• fragmento de código ausente
• restricción arquitectónica
• evidencia de tests
• contexto del diff

Un buen prompt de segunda pasada es:

Re-run receiving-code-review with this added context. Update your recommendation and tell me whether the original review comment is now clear enough to implement.

Combina la skill con implementación solo después de validar

El mejor patrón de adopción es en dos fases:

1. usar receiving-code-review para evaluar el comentario
2. solo entonces pedir ediciones de código

Esta separación mejora la confianza porque puedes inspeccionar el razonamiento antes de que el modelo empiece a cambiar archivos.

Usa la skill como estándar de equipo

Si tu equipo quiere un comportamiento de IA consistente en flujos de PR, convierte la skill en una instrucción por defecto para gestionar feedback entrante de revisión:

• nada de respuestas que empiezan con elogios
• nada de implementación a ciegas
• preguntar cuando no esté claro
• verificar contra el código local
• rebatir cuando esté técnicamente justificado

Ahí es donde la receiving-code-review skill aporta más valor a largo plazo: no como un prompt puntual, sino como un hábito operativo repetible.