danielsegg/code-review-checklist

Revisar código

Realizar revisiones basadas en evidencia y en el contexto del proyecto. Priorizar comportamiento incorrecto, riesgo real y regresiones; no generar observaciones solo para llenar un checklist.

Respetar el alcance y la seguridad

• Tratar la revisión como solo lectura. No editar código, cambiar de rama, instalar o actualizar dependencias, aplicar correcciones, hacer commit, publicar comentarios ni ejecutar despliegues sin solicitud explícita.
• Poder ejecutar verificaciones locales no mutables cuando sean seguras y relevantes. Antes de ejecutar código proveniente de un cambio no confiable, evaluar el comando y sus efectos.
• No enviar código, secretos ni metadatos a servicios externos sin autorización.
• Diferenciar revisión de implementación: cuando el pedido sea solo revisar, reportar los hallazgos sin corregirlos.
• Preservar cambios existentes del usuario y evitar comandos destructivos.

Construir el contexto

1. Leer íntegramente AGENTS.md y las instrucciones aplicables al directorio revisado.
2. Identificar el objetivo, los requisitos y el límite del cambio mediante el pedido, issue, descripción del PR, diff e historial relevante.
3. Inspeccionar todos los archivos modificados y el código directamente relacionado antes de concluir que algo es un defecto.
4. Verificar configuraciones, versiones, arquitectura y convenciones reales del proyecto. No aplicar patrones de otro lenguaje o framework por analogía.
5. Investigar información disponible localmente antes de pedir aclaraciones. Preguntar solo cuando una laguna impida una conclusión responsable.
6. Registrar limitaciones del análisis, como pruebas no ejecutadas, dependencias no disponibles o ausencia de requisitos.

Ejecutar la revisión

Evaluar cada cambio en las dimensiones aplicables:

Funcionalidad y regresiones

• Confirmar que la implementación cumple el comportamiento solicitado y preserva flujos existentes.
• Examinar condiciones de borde, valores vacíos o nulos, fallos parciales, repetición de la operación, concurrencia y transiciones de estado.
• Revisar manejo de errores, rollback, idempotencia y efectos secundarios.
• Verificar contratos públicos, compatibilidad hacia atrás, migraciones e impacto en consumidores.

Seguridad y privacidad

• Verificar validación de entrada y codificación de salida en los límites correctos.
• Buscar fallos de autorización, autenticación, CSRF, XSS, inyección, path traversal, SSRF, subida insegura y mass assignment.
• Revisar exposición de secretos o datos personales en código, respuestas, URLs y logs.
• Evaluar permisos según el caso de uso y el recurso; la autenticación aislada no sustituye la autorización.
• Tratar alertas de dependencias como evidencia a confirmar, considerando explotabilidad y compatibilidad de la corrección.

Datos, rendimiento y confiabilidad

• Identificar N+1, consultas repetidas, carga excesiva, bucles costosos y algoritmos inadecuados para el volumen esperado.
• Revisar transacciones, locks, restricciones, índices e integridad referencial cuando el cambio afecte persistencia.
• Verificar paginación, límites, timeouts, reintentos y consumo de memoria en caminos relevantes.
• Recomendar optimización o caché solo cuando exista un cuello de botella plausible; considerar invalidación y consistencia.
• En cálculos monetarios, verificar precisión decimal, redondeo y atomicidad.

Diseño y mantenibilidad

• Evaluar cohesión, separación de responsabilidades, dirección de dependencias y lenguaje del dominio.
• Preferir código simple y explícito. No exigir funciones arbitrariamente pequeñas ni abstracciones prematuras para eliminar toda repetición.
• Verificar nombres, contratos, manejo de tipos y comentarios que expliquen decisiones no obvias.
• Dejar el estilo mecánico a los formateadores y linters del proyecto, salvo cuando afecte corrección o comprensión.

Pruebas y documentación

• Verificar pruebas proporcionales al riesgo, cubriendo comportamiento principal, límites, errores y regresiones relevantes.
• Evaluar la calidad de las aserciones, el aislamiento y la capacidad de la prueba para fallar ante el defecto previsto; no usar solo porcentaje de cobertura.
• Revisar documentación, contratos de API e instrucciones operativas cuando el comportamiento público cambie.
• Antes de ejecutar verificaciones, seguir los comandos y el entorno prescritos por el repositorio. Reportar con precisión qué se ejecutó o no.

Aplicar verificaciones para PHP y CakePHP

Cuando la stack involucre PHP o CakePHP, también:

• Revisar compatibilidad con la versión de PHP y usar las herramientas configuradas por el proyecto, como PHPUnit, PHPCS, PHPStan, Psalm y composer audit.
• Mantener los Controllers enfocados en la entrada HTTP y la orquestación; ubicar las reglas de negocio en la capa adoptada por el proyecto, normalmente Services.
• Examinar Policies y comprobaciones de autorización para cada acción y recurso.
• Evaluar Validators, RulesChecker, patchEntity(), campos accesibles de la Entity y protección contra mass assignment.
• Preferir ORM, query builder y parámetros vinculados a SQL concatenado; revisar associations, contain(), selección de campos y riesgo de N+1.
• Verificar transacciones en operaciones con múltiples escrituras y distinguir fallo de persistencia de excepción inesperada.
• Revisar escapado en las plantillas, campos explícitamente no escapados, CSRF y respuestas que puedan filtrar detalles internos.
• Revisar migraciones en cuanto a reversibilidad práctica, valores existentes, locks, índices, foreign keys y compatibilidad con la base de datos soportada.
• Respetar composer.lock; no recomendar actualización indiscriminada de dependencias.

Para CakePHP en Núcleo Lavanderias, respetar especialmente el flujo Controller → Service → Table/Entity, el contrato de AbstractService::run(), las Policies por perfil, MariaDB, PHPUnit y la ejecución de comandos dentro de los contenedores, siempre sin -u root en las pruebas.

Aplicar verificaciones al frontend web

• Revisar escapado contextual, manipulación segura del DOM, CSRF, validación en el servidor y exposición de datos.
• Verificar estados de carga, error, peticiones concurrentes, cancelación y respuestas fuera de orden.
• Respetar la stack y las convenciones locales; en código nuevo de Núcleo Lavanderias, preferir StimulusJS y Axios y limitar jQuery al mantenimiento del legado.
• Evaluar accesibilidad y comportamiento responsivo cuando la alteración afecte la interfaz.

Validar los hallazgos

Antes de reportar un problema:

1. Confirmar que fue introducido o afectado por el alcance revisado.
2. Localizar la región de código más pequeña que demuestre el problema.
3. Describir un escenario concreto en el que ocurra el comportamiento.
4. Verificar si otra capa, configuración o prueba ya mitiga el riesgo.
5. Ajustar la severidad según la probabilidad y el impacto, no por el tipo abstracto de la regla.

Ausencia en el diff no es prueba de ausencia en el sistema. Si el repositorio está disponible, inspeccionar las capas relacionadas antes de reportar falta de autorización, validación, transacción o protección equivalente. Si solo hay un fragmento aislado, presentar el punto como riesgo condicional o duda, no como defecto confirmado.

No presentar una hipótesis remota como defecto confirmado. Cuando una incertidumbre relevante persista, identificarla explícitamente y decir qué evidencia resolvería la duda.

Producir el informe

Presentar primero los hallazgos, en orden de severidad:

• Bloqueante: corrupción de datos, vulnerabilidad explotable, indisponibilidad grave o comportamiento central inviable.
• Alta: defecto probable con impacto relevante o regresión importante.
• Media: problema real con impacto limitado, dependiente de una condición específica.
• Baja: mejora concreta y localizada, sin riesgo significativo inmediato.

Para cada hallazgo, incluir:

### [Severidad] Título objetivo

- Local: `ruta/archivo.ext:línea`
- Evidencia: comportamiento demostrable en el código.
- Impacto: escenario afectado y consecuencia.
- Recomendación: dirección de corrección proporcional, sin reescribir toda la solución.

Usar siempre la línea local del archivo, nunca la posición global del fragmento en un archivo de diff. Si el diff no proporciona numeración de hunk suficiente, citar el símbolo o método e informar que la línea no está disponible. Mantener el intervalo corto y directamente relacionado con el hallazgo. Agrupar ocurrencias equivalentes en lugar de repetir comentarios.

Después de los hallazgos, registrar brevemente:

• dudas o premisas que influyen en la conclusión;
• verificaciones ejecutadas y sus resultados;
• riesgos residuales o lagunas de prueba.

Si no hay hallazgos, declararlo claramente e informar también limitaciones y verificaciones realizadas. No sustituir hallazgos por un resumen genérico del cambio, salvo que el usuario también solicite el resumen.