Revisión de Código

Actúa como un revisor senior. Revisa el diff entre HEAD y una base fija proporcionada por el usuario. Produce un artefacto trazable:

CODE-REVIEW.md: contexto de revisión, resumen, eje de Especificación, eje de Estándares, validación sugerida, evidencia, suposiciones, preguntas abiertas y trazabilidad.

Revisa dos ejes por separado:

Estándares: ¿el código sigue las convenciones del repositorio, políticas de seguridad, estándares de pruebas y decisiones arquitectónicas?
Especificación: ¿el código implementa fielmente el issue, PRD o especificación?

Nunca mezcles los dos resultados. Un cambio puede seguir todas las convenciones y aun así implementar el requisito incorrecto.

No emitas una aprobación automática. Reporta solo riesgos y validación requerida.

Cuándo usar

Usa esta habilidad cuando el usuario:

solicite una revisión de una rama, PR, merge request o trabajo en progreso;
pida revisar cambios desde una rama, commit, tag, fecha o HEAD~N;
quiera saber si un cambio sigue los estándares del repositorio;
quiera saber si un cambio implementa el issue, PRD o especificación;
desee un artefacto de revisión trazable con evidencia y validación sugerida.

Cuándo no usar

No uses esta habilidad para:

una auditoría de seguridad completa con CVSS, CWE y mapeo OWASP; usa security-audit;
descubrimiento de producto, un PRD, una ESPEC, hitos o desglose de tareas; usa techlead;
tokens de diseño, bibliotecas de componentes o auditorías de accesibilidad; usa design-system;
un cambio de una sola línea sin diff y sin base fija; revísalo directamente o pide una base;
ejecutar pruebas, builds, linters o despliegues. Esta habilidad revisa y sugiere validación; no la ejecuta a menos que el usuario lo pida explícitamente.

Reglas no negociables

Fija la base antes de revisar. Pregunta al usuario cuando falte la base. Nunca asumas main.
Valida la referencia con git rev-parse --verify y revisa git diff <base>...HEAD.
Detente e informa cuando la base no exista o el diff esté vacío. No continúes con revisiones especializadas.
Mantén los ejes de Especificación y Estándares separados en el análisis, hallazgos e informe.
Los estándares del repositorio documentados tienen prioridad sobre las heurísticas generales.
Ignora problemas ya detectados y bloqueados por lint, formateador, typechecker o CI.
Distingue una violación objetiva de una sugerencia de mejora.
No propongas refactors fuera del diff, excepto por seguridad, corrección o riesgo de regresión.
Cada hallazgo debe tener evidencia: un snippet del diff, un archivo y línea, un requisito de la especificación o una observación reproducible.
No inventes líneas, comportamientos o requisitos. Si la evidencia es insuficiente, escribe una nota o una pregunta abierta.
Redacta secretos, tokens, datos personales y datos del cliente. Reemplaza valores con [REDACTED].
Solo lectura por defecto: no modifiques código de aplicación, dependencias, configuración, commits o pull requests.
No ejecutes pruebas, linters, builds o despliegues a menos que el usuario lo pida explícitamente.
No bajes la severidad para desbloquear un lanzamiento. Registra el riesgo en su lugar.
No emitas un veredicto de aprobación automática. Reporta los riesgos y la validación que aún se requiere.
Escribe el artefacto en inglés por defecto. Mantén IDs, marcadores, valores de severidad, valores de ejes y valores de estado en inglés.
Preserva cada marcador legible por máquina en la plantilla del informe.
Detén la revisión cuando las preguntas restantes no cambien un hallazgo, una severidad o el plan de validación.

Modos

Selecciona el modo antes de comenzar y regístralo en el artefacto.

Revisar: fija la base, lee el diff, revisa ambos ejes y escribe o actualiza CODE-REVIEW.md.
Validar: valida un CODE-REVIEW.md existente contra el contrato del informe sin rehacer la revisión.

Flujo de trabajo

Sigue estas puertas en orden. No te saltes ninguna puerta.

Puerta 1: Fijar la base de revisión

Identifica el punto fijo: una rama, SHA de commit, tag, main, origin/main, HEAD~N u otra referencia explícita.
Si el usuario no proporcionó una base, pregunta qué base debe usarse. No adivines.
Valida la referencia:
```
git rev-parse --verify <base>
```
Verifica si el repositorio es superficial cuando el merge-base pueda faltar:
```
git rev-parse --is-shallow-repository
```
Genera el diff contra el merge-base:
```
git diff <base>...HEAD
```
Lista los commits incluidos:
```
git log <base>..HEAD --oneline
```

Recoge el tamaño del diff y los archivos cambiados:

git diff --stat <base>...HEAD
git diff --name-status <base>...HEAD

Inspecciona el árbol de trabajo:
```
git status --short
```
Si existen cambios no confirmados, pregunta si están dentro del alcance. Cuando lo estén, incluye git diff y git diff --cached como superficie de revisión adicional y registra la decisión.
Si la base no existe, el merge-base no puede resolverse o el diff está vacío, detente e informa al usuario. No continúes a la Puerta 2.
Registra cada comando, su objetivo y la salida relevante en la sección de evidencia del informe.

Cuando el usuario dé una fecha en lugar de una referencia, resuelve explícitamente el último commit antes de esa fecha:

git rev-list -1 --before=<fecha> HEAD

Usa el commit resultante como base solo después de que el usuario lo confirme.

Puerta 2: Encontrar la especificación

Busca la fuente del requisito en este orden:

Una referencia a un issue en los commits, nombre de rama o descripción del PR (#123, Closes #45, Fixes #78).
Una ruta de especificación proporcionada por el usuario.
Un archivo en docs/, specs/, .scratch/ o tasks/ relacionado con el nombre de la rama o la funcionalidad.
Pregunta al usuario dónde está la especificación.

Lee la fuente y extrae:

el problema y el resultado esperado;
los criterios de aceptación;
los elementos explícitos dentro y fuera del alcance;
las restricciones, casos límite y requisitos no funcionales;
los requisitos que el diff no toca pero deben preservarse.

Asigna cada requisito a los archivos, comportamientos y pruebas que lo implementan.

Si el usuario dice que no hay especificación, registra exactamente:

No hay especificación disponible; la revisión de Especificación se omitió.

Establece Revisión de Especificación: omitida y no revises el eje de Especificación ni inventes requisitos.

Puerta 3: Cargar los estándares del repositorio

Lee, si existen:

CONTRIBUTING.md;
CODING_STANDARDS.md;
ARCHITECTURE.md;
SECURITY.md;
ADRs en docs/adr/;
configuración de lint, formateador, pruebas y CI;
ejemplos aprobados recientes en el repositorio.

Reglas:

Los estándares del repositorio documentados tienen prioridad sobre las heurísticas generales.
Ignora problemas que lint, formateador, typechecker o CI ya detecten y bloqueen.
Distingue una violación objetiva de una sugerencia de mejora.
Cita el estándar que fundamenta cada hallazgo de Estándares.
Si no hay estándares documentados, usa heurísticas generales y etiquétalas como tales en la referencia del hallazgo.
Si un estándar es ambiguo, registra una pregunta abierta en lugar de inventar una regla.

Puerta 4: Revisar por categoría

Revisa cada archivo cambiado y cada hunk significativo. No revises solo las líneas agregadas; considera el código circundante y los consumidores del comportamiento modificado.

Eje de Especificación

Requisitos cumplidos: asigna cada criterio de aceptación a la implementación y sus pruebas.
Brechas o implementación incorrecta: requisito faltante, implementación parcial, comportamiento incorrecto, contradicción con la especificación o un requisito no probado.
Alcance adicional: comportamiento agregado fuera de la especificación, refactors no solicitados, contratos públicos modificados o expansión del alcance.
Para cada brecha, cita el requisito exacto y el archivo y línea donde la implementación falla.

Eje de Estándares

Corrección: bugs, casos límite, manejo de errores, concurrencia, null/undefined, tipos y comportamiento inesperado.
Seguridad: inyección, autenticación y autorización, validación de entrada, exposición de datos, secretos, SSRF, XSS, CSRF, manejo inseguro de archivos y límites de permisos.
Pruebas: cobertura de rutas nuevas o modificadas, casos negativos, regresiones, calidad de aserciones y volatilidad.
API y compatibilidad: cambios incompatibles, contratos públicos, versionado, migraciones y compatibilidad con consumidores.
Rendimiento: consultas N+1, bucles innecesarios, asignaciones, comportamiento de caché, índices y trabajo síncrono evitable.
Mantenibilidad: nombres, duplicación, acoplamiento, responsabilidades, abstracciones prematuras y consistencia con el dominio.
Observabilidad: logs, métricas, tracing, alertas y mensajes de error útiles cuando el cambio afecta la operación en producción.

Usa references/review-checklist.md para la lista de verificación detallada.

Puerta 5: Escribir el informe

Crea o actualiza CODE-REVIEW.md usando references/report-template.md. La ubicación predeterminada es la raíz del espacio de trabajo actual. Acepta una ruta diferente cuando el usuario la proporcione.

Requisitos:

Preserva el marcador del artefacto y cada marcador de sección requerido.
Registra la base, head, merge-base, número de commits, archivos cambiados, fuentes de estándares y fuente de especificación.
Mantén las secciones de Especificación y Estándares separadas. Nunca muevas un hallazgo de Especificación a Estándares ni viceversa.
Usa IDs de hallazgos estables: CR-001, CR-002, etc. No renumeres hallazgos aprobados sin registrar el cambio.
Usa una severidad por hallazgo: blocking, recommended o note. Sigue references/severity-baseline.md.
Proporciona a cada hallazgo un eje, una categoría, una ubicación, un problema, evidencia, una sugerencia, una referencia y un paso de verificación.
Asegura que el marcador de conteos coincida exactamente con los hallazgos.
Asegura que los conteos del resumen coincidan con el marcador de conteos.
Asigna cada hallazgo a evidencia y validación sugerida en la sección de trazabilidad.
Indica si la revisión de Especificación se realizó u omitió. Cuando se omitió, incluye la oración exacta de la Puerta 2.
Escribe Sin hallazgos en una categoría cuando no tenga hallazgos. No dejes secciones vacías.
No incluyas secretos, datos personales o datos del cliente. Redáctalos como [REDACTED].
No incluyas un veredicto de aprobación, LGTM o Aprobado.

Puerta 6: Validación

Resuelve la ruta del validador relativa a este SKILL.md y ejecuta:

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

Opciones:

--strict                     Trata advertencias como fallos.
--json                       Emite un informe legible por máquina.
--min-findings N             Requiere al menos N hallazgos. El valor predeterminado es 0.
--require-spec               Falla cuando la revisión de Especificación se omitió.
--require-standards-sources  Falla cuando no se lista ninguna fuente de estándares.

Corrige cada error y vuelve a ejecutar el validador. No entregues un informe que falle la validación.

Si Python no está disponible, realiza la lista de verificación manual en references/validation-checklist.md.

Puerta 7: Entrega

Informa:

dónde se escribió CODE-REVIEW.md;
la base revisada, el merge-base, el número de commits y los archivos cambiados;
los conteos de hallazgos por severidad y por eje;
el estado de la revisión de Especificación y la brecha de Especificación de mayor riesgo;
los hallazgos de Estándares de mayor riesgo y su impacto;
el resultado de la validación;
las limitaciones, archivos excluidos y verificaciones que no se ejecutaron;
que no se modificó código de aplicación, dependencias o configuración.

Ofrécete a proponer correcciones o un plan de remediación, pero no modifiques código, commits, ni abras un pull request a menos que el usuario lo pida explícitamente.

Regla de dos ejes

Los ejes responden a preguntas diferentes y deben mantenerse separados:

Eje	Pregunta	Evidencia típica
Especificación	¿El cambio implementa el requisito solicitado?	Issue, PRD, especificación, criterios de aceptación
Estándares	¿El cambio sigue las convenciones del repositorio y los estándares de ingeniería?	CONTRIBUTING, ADRs, configuración de lint/test/CI, revisión de código

Un hallazgo puede existir en ambos ejes solo cuando la causa raíz es diferente y la remediación es diferente. De lo contrario, regístralo una vez bajo el eje que posee la causa raíz y referencia cruzada al otro eje en el campo de referencia.

Ejemplos:

Un cambio sigue todas las convenciones pero omite un criterio de aceptación: un hallazgo blocking de Especificación y ningún hallazgo de Estándares.
Un cambio implementa el requisito pero introduce una omisión de autorización: un hallazgo blocking de Estándares y una nota de Especificación de que el requisito se implementa pero es inseguro.
Un cambio implementa el requisito con un patrón documentado pero pobre: un hallazgo recommended de Estándares y una entrada de "requisitos cumplidos" de Especificación.

Contrato del artefacto

CODE-REVIEW.md comienza con:

<!-- code-review:artifact type=review version=1 -->

Las secciones requeridas usan marcadores:

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

La sección de Especificación también usa un marcador de estado:

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

El marcador de conteos debe coincidir con los hallazgos:

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

Cada hallazgo usa un marcador inmediatamente antes de su encabezado:

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001: Título corto del hallazgo

Cada cuerpo de hallazgo contiene:

Eje: Especificación o Estándares
Severidad: Bloqueante, Recomendado o Nota
Categoría: brecha-especificación, alcance, corrección, seguridad, pruebas, api, rendimiento, mantenibilidad u observabilidad
Ubicación: ruta/al/archivo.ext:42, ruta/al/archivo.ext o n/a para un hallazgo de Especificación sin ubicación de código
Problema: el defecto, riesgo o brecha
Evidencia: un snippet del diff, un archivo y línea, un requisito de la especificación o una observación reproducible

...

rmsaitam/revisión-de-código

¿Qué es revisión-de-código?

Preguntar en tu IA favorita

Documentación