/pr-review-lead hace de Tech Lead sobre el pull request de un compañero, en este repo o en otro que le señales. Lee la doctrina que ese código realmente documenta, lee el diff, y cada hallazgo apunta a una línea de código, a una sección de doctrina, o dice en voz alta que es una opinión. Nada sale a GitHub sin tu OK explícito sobre el borrador final.
Flexible, Standard o Strict. Después, la doctrina del repo destino.
El diff real, no la descripción. Cada hallazgo con su cita.
Tabla, puntos fuertes y puntaje. Tú reclasificas lo que haga falta.
Sándwich de feedback. Se postea solo cuando dices que sí, a ESE borrador.
La skill tiene vecinos que también "revisan". Cada uno responde a alguien distinto, y tiene su propia puerta.
| Necesitas | Usa |
|---|---|
| Feedback sobre el PR terminado de un compañero (de este repo o de otro), con puntaje y evidencia, posteado solo después de tu OK | /pr-review-lead |
| La pasada de review dentro del pipeline de una historia: un agente adversarial independiente, hallazgos adjudicados por el orquestador, vuelta a la etapa 2 | /sprint-development etapa 3, references/review-pr.md |
| Revisar tus propios cambios sin commitear antes de abrir el PR | El flujo de code review del harness |
| Abrir el PR, resolver conflictos, manejar ramas, mergear | /git-flow-master |
No tiene modos: una sola corrida, del paso 0 al 7. Hasta el paso 6 todo queda en la conversación. Recién el paso 7 escribe algo que otros ven.
| Paso | La IA hace | Tú decides | Sale |
|---|---|---|---|
| 0 · Rigor | Pregunta una vez, con el prompt del harness, y confirma el alcance | Flexible, Standard o Strict; qué PR; si es de este repo o de otro | El lente para todo lo que sigue |
| 1 · Doctrina | Carga la doctrina del repo destino, o avisa que usa la de este | Si aceptas un chequeo que el repo destino no documenta | El estándar contra el que se mide |
| 2 · Leer el PR | Lee los diffs reales; separa ruido de trabajo | Nada: te avisa qué es ruido | Los parches que importan |
| 3 · Analizar | Recorre el checklist y cita cada hallazgo | Nada todavía | Hallazgos en Real, Pattern o Positive |
| 4 · Checkpoint | Presenta tabla, puntos fuertes y puntaje sobre 10 | Lees antes de que salga algo | Una tabla en la conversación |
| 5 · Triage | Re-clasifica exactamente como le pides, sin defender la primera pasada | Qué hallazgos van, con qué severidad, qué puntaje aceptas | El conjunto que se redacta |
| 6 · Borrador | Redacta el comentario en forma de sándwich | El tono, si no hay preferencia previa | Un borrador en inglés |
| 7 · Postear | Postea con gh y lee el comentario de vuelta | El OK explícito sobre este borrador | Un comentario en el PR, con su URL |
Es obligatorio en cada corrida. Se saltea solo cuando el pedido ya lo dijo ("revísalo estricto", "sé flexible con los patrones"), y nunca se vuelve a preguntar lo que ya se dio.
| Nivel | Qué se reporta | Hallazgos Pattern | Peso de un Pattern en el puntaje |
|---|---|---|---|
| Flexible | Solo lo evidentemente roto o lo que pone en riesgo corrección, seguridad o datos | No aparecen, salvo que también sean un riesgo de corrección o seguridad | Ninguno |
| Standard (recomendado) | La misma vara de Flexible, más las desviaciones de patrón | Observaciones livianas, como comparación: "el patrón documentado hace X, este PR hace Y" | Ninguno: son informativos, nunca restan |
| Strict | Pasada literal contra cada archivo de doctrina que aplique | Hallazgo etiquetado, aunque funcione bien | Chico, con tope: nunca domina como un Real |
Viene de una sesión real en el boilerplate hermano de QA: una desviación de arquitectura que no rompía nada se puntuó con la severidad máxima, y el usuario la corrigió. Casi nadie implementa una arquitectura al pie de la letra, y una desviación que no rompe nada no es un error como lo es un bug.
Nunca se revisa contra convenciones recordadas ni contra "buenas prácticas" genéricas que no se verificaron documentadas. La doctrina se lee fresca en cada corrida, nunca de memoria de una sesión anterior.
# el sondeo (references/evidence-and-doctrine-lookup.md §"External repo") gh api "repos/<owner>/<repo>/contents/AGENTS.md" -q '.content' | base64 -d gh api "repos/<owner>/<repo>/contents/.agents/skills" -q '.[].name' gh api "repos/<owner>/<repo>/contents/.context" -q '.[].name'
Para un arreglo de tres líneas no se carga todo. La tabla completa vive en references/evidence-and-doctrine-lookup.md §"Doctrine map".
| Si el PR toca | Se lee |
|---|---|
| Cualquier código | typescript-patterns.md, code-standards.md, el checklist de review-pr.md |
| Rutas de error, handlers de API | error-handling.md |
| Estructura de backend, módulos nuevos | project-bootstrap, regla B1 (capas api/ / schemas/ / db/) |
| Funciones de Postgres, RLS, migraciones | rpc-authorization.md; el mapa de datos (bun run context:map business-data-context) si existe |
| UI | DESIGN.md, .context/design/master-design-plan.md, Critical Rule #14, data-testid-standards.md |
| Una decisión de arquitectura | Los ADR Accepted de .context/ADR/, adr-doctrine.md |
| Tests unitarios | unit-testing, su ## Compact Rules |
| Deploy, entorno, CI | pre-deploy-checklist.md, environment-config.md, ci-cd-setup.md |
Un diff grande a veces es casi todo ruido. La skill lo separa antes de leer línea por línea, y te avisa qué apartó.
Primero los titulares de los commits: un lockfile, tipos de Supabase regenerados, una sincronización de tipos de OpenAPI o un commit de sync del template no se revisan línea por línea. Se nombran.
Por una sola cosa: que coincida con lo que lo generó. Un archivo generado editado a mano es un hallazgo.
gh pr diff falla con PullRequest.diff too_large. La salida es paginar los parches por archivo, nunca hojear la descripción.
No se traen todos los diffs al contexto propio: se despacha por archivo o por grupo (UI, API, DB, tests) con un briefing de 7 componentes. Pocos archivos se leen en línea.
Apunta a una línea de código, apunta a una línea de doctrina, o se rotula como opinión. No hay cuarta opción.
<file>:<line> del diff, con la línea citada.
Sin checkout local, se cita tal como aparece en el parche.
<archivo> §<Sección> o Critical Rule #N, con la oración que respalda el claim.
Siempre un título de sección, nunca un número de línea: los números se mueven con cada edición (Critical Rule #17).
Dicha con esas palabras: "esto es una opinión general de buenas prácticas, no está en la documentación de este repo".
Disfrazarla de regla erosiona la confianza en todas las demás citas.
Recorre review-pr.md §"CHECKLIST DE REVIEW" en su orden (criterios de aceptación primero) y suma tres frentes que un revisor de historia puede no alcanzar.
api/ / schemas/ / db/ en el backend y la estructura del design system en el frontend son arquitectura del framework (project-bootstrap B1). Colapsarlas es un hallazgo, no una simplificación.
La referencia es la UI viva actual más los tokens de DESIGN.md; el mockup es inspiración. Es defecto un cambio que no coincide ni con la UI viva ni con el design system y no tiene ratificación spec-only en §5 de master-design-plan.md.
Seguir la UI viva mejorada donde el mockup difiere no es un hallazgo.
Una elección difícil de revertir (modelo de auth, de acceso a datos o de tenancy, lock-in de framework) sin ADR, o que contradice uno Accepted en .context/ADR/, es un hallazgo.
El balde, no la etiqueta de severidad, es lo que mueve el puntaje. Dentro de Real y Pattern la severidad usa la escala compartida, en tu idioma en la conversación (Bloqueante, Mayor, Menor, Nit) y en inglés en lo posteado.
| Balde | Qué es | Ejemplos |
|---|---|---|
| Real | Algo evidentemente mal, o un riesgo para corrección, seguridad o datos, más allá del gusto arquitectónico de nadie. Pesa en todos los niveles | Criterio no cumplido, credencial hardcodeada (Rule #1), RPC que confía en la identidad que le pasan, migración destructiva sin camino de vuelta, divergencia de UI sin ratificar |
| Pattern | Funciona, no rompe nada, pero se aparta de una convención documentada. Es una comparación, no un veredicto. Su peso depende del paso 0 | Más de dos parámetros posicionales, un import relativo profundo, lógica de dominio en una utilidad compartida, un desliz de nombres |
| Positive | Lo bien hecho, con la misma vara de evidencia. No es opcional ni una cortesía: se llena siempre | Tests que fijan comportamiento y no implementación, una migración con su down path, un ADR limpio, un componente reutilizado, evidencia de UI viva adjunta |
La tabla agrupa por balde y severidad, siempre con la columna de evidencia, y cierra con los puntos fuertes y un puntaje sobre 10 con su razón en una línea.
# forma del checkpoint (references/output-and-posting-flow.md, paso 4) | # | Bucket | Severidad | Ubicación | Observación (con evidencia) | | 1 | Real | BLOCKER | <file>:<line> | ... rpc-authorization.md §"Actor bind" | | 2 | Pattern | MINOR | <file>:<line> | ... comparación, no error. review-pr.md | Puntos fuertes: - <positive con su propia evidencia> Score: X.X / 10: <razón atada a los baldes que lo movieron>
Arranca en 10 y resta. La rúbrica completa está en references/severity-and-scoring.md §"Scoring rubric".
| Hallazgo | Resta |
|---|---|
| Real BLOCKER | De 1.5 a 2.5, según el radio de impacto: una anon key filtrada en un demo pesa menos que una lectura entre tenants con datos reales |
| Real MAJOR | De 0.5 a 1 |
| Real MINOR | De 0.1 a 0.3 |
| NIT | Nada |
| Pattern | Nada en Flexible y Standard. En Strict, de 0.1 a 0.2 cada uno, con tope: diez nitpicks de patrón sobre un PR sin defectos reales lo dejan holgado arriba de la mitad |
| Positive | No suma. Un PR con un bloqueante y positivos excelentes sigue siendo un PR con un bloqueante: se dicen las dos cosas |
Tu contexto (las normas del equipo, lo que consideras que vale la pena levantar) decide qué sale. La skill re-clasifica como le pides y no defiende la primera pasada.
Elogio, constructivo, elogio. Con una fortaleza real en cada punta, no un cumplido de relleno envolviendo una lista de quejas.
Redacta en inglés (Critical Rule #12), salvo que pidas otro idioma para ESE comentario. Cada punto constructivo lleva la cita de la tabla.
Pasa la prosa por la skill humanizer si está instalada: lo va a leer una persona. Código, rutas y citas quedan intactos.
El tono, si no hay una preferencia ya establecida.
El OK, sobre este borrador. "Se ve bien" mientras todavía se discute la severidad no es "postéalo" cuando se muestra el final.
Un comentario simple en el PR, posteado desde un archivo temporal.
Su URL, confirmada leyendo el PR de vuelta.
# el borrador confirmado, a un archivo del scratch de la sesión gh pr comment <N> [--repo <owner>/<repo>] --body-file <scratch>/pr<N>_review.md # leerlo de vuelta: el comentario tiene que estar en el PR gh pr view <N> [--repo <owner>/<repo>] --json comments -q '.comments[-1].url'
Viven en ## Compact Rules y en ## Rules de la skill; las compactas viajan a los subagentes por .agents/skills/REGISTRY.md.
.agents/instructions/agent-tool-resolution.md §6.5).
No tiene modos. Alcanza con nombrarla y el PR, o con frases como "revisa este PR", "actúa de tech lead" o "review this PR". Si ya dices el rigor ("revísalo estricto"), el paso 0 no pregunta.
La barra de la skill, con el PR que quieres revisar.
Sin barra: nombras la skill y el PR en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
Es chica a propósito: el checklist y la escala son de sprint-development, y el transporte de gh es de git-flow-master.
Su etapa 3 es el revisor dentro del pipeline de una historia. Es dueña de review-pr.md, que esta skill lee por referencia.
Se carga antes de cualquier llamada a gh. Abrir, mergear o arreglar el PR es trabajo suyo, nunca de esta skill.
Cómo se le pregunta al humano y cómo se reporta. El paso 0 es una pregunta de tres opciones por el prompt del harness, como pide AGENTS.md §2.