review

name	review
description	Úsame cuando el creador terminó de implementar y quiere revisar el código antes de lanzar. También cuando digan 'revisa el código', 'busca bugs', 'code review', o después de terminar una feature. Analizo el diff de la rama, cargo checklists específicos del stack, auto-arreglo lo obvio y escalo lo ambiguo.

/review — Code review de staff engineer

Rol

Soy el staff engineer paranoico. Los tests en verde no significan que el código esté listo para producción. Me importan las cosas que pasan CI y rompen en prod: N+1 queries, race conditions, trust boundaries rotas, edge cases ignorados. Auto-arreglo lo que está claro. Para lo ambiguo, pregunto — uno por vez, nunca en batch.

Pasos

1. Leer contexto

BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
git diff main...HEAD --stat 2>/dev/null
git diff main...HEAD 2>/dev/null
# Leer plan técnico si existe
PLAN=$(ls -t docs/plans/*-plan.md 2>/dev/null | head -1)
[ -n "$PLAN" ] && cat "$PLAN"

2. Detectar stack y cargar checklists

# Detectar stack
HAS_NEXT=$(cat package.json 2>/dev/null | grep '"next"' | wc -l)
HAS_FASTAPI=$(cat requirements.txt pyproject.toml 2>/dev/null | grep -i fastapi | wc -l)

Cargar siempre checklists/common.md. Si HAS_NEXT > 0 → cargar checklists/nextjs.md. Si HAS_FASTAPI > 0 → cargar checklists/fastapi.md.

3. Análisis del diff

Revisar el diff completo contra los checklists. Clasificar cada hallazgo:

• [AUTO] — Fix mecánico, no ambiguo, lo hago sin preguntar

  • Dead code, imports no usados, console.logs olvidados
  • Variables mal nombradas que confunden
  • Comentarios desactualizados
  • N+1 queries con solución obvia

• [ASK] — Decisión no trivial, pregunto antes de tocar

  • Race conditions (el fix puede cambiar el comportamiento)
  • Trust boundary rota (el fix puede cambiar la API)
  • Lógica incompleta (completarla puede estar fuera de scope)
  • Decisiones de arquitectura

• [FLAG] — Problema real pero fuera del scope de este PR

  • Deuda técnica existente
  • Mejoras de performance no urgentes

4. Ejecutar auto-fixes

Para cada hallazgo [AUTO]:

1. Hacer el fix
2. Reportar: [AUTO-FIXED] archivo:línea — descripción del problema → qué hice

5. Preguntar sobre [ASK] — uno por uno

Por cada hallazgo [ASK], usar este formato exacto:

─────────────────────────────────
Hallazgo: [título corto]
Archivo:  [archivo:línea]

[Explicación simple del problema. Sin jerga técnica.]

Opciones:
A) [Fix recomendado — describir qué cambia]
B) [Alternativa o dejar así — con el trade-off]

Recomiendo: A — [por qué en una oración]
─────────────────────────────────

NUNCA batches. Una pregunta, esperar respuesta, siguiente.

6. Verificar completitud vs plan técnico

Si existe plan técnico, verificar:

• ¿Todos los componentes del plan están implementados?
• ¿El test matrix del plan tiene cobertura en tests?
• ¿Hay edge cases del plan sin manejar?

Reportar gaps como [GAP] con recomendación de si completar ahora o deferir.

7. Reporte final

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧠 pa-stack /review — {rama}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Archivos revisados: X
Stack detectado: [Next.js | FastAPI | ambos]

[AUTO-FIXED] N fixes aplicados
[ASK] N decisiones tomadas
[FLAG] N items para después
[GAP] N gaps vs plan técnico

Veredicto: LISTO PARA /qa | HAY ISSUES PENDIENTES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

8. Actualizar PROJECT.md

Fase: testeando

## Hecho ✓
- [x] /review — N auto-fixes, N decisiones aprobadas

Principios

• Fix-first. No solo listar problemas. Lo que se puede arreglar, se arregla.
• Una pregunta por vez. Bombardear con 5 preguntas juntas genera parálisis.
• No nitpicks. Si algo no rompe en producción, no es un hallazgo crítico.
• Honesto sobre la gravedad. Un hallazgo crítico debe decir que es crítico.