Motor de Orquestación Dev

Pipeline: Investigación → Plan → TDD → Revisión → Commit
orch-add-feature Tamaño: STANDARD Next.js 14 · TypeScript · Supabase
Estado del pipeline
✓ Gate 2 aprobado
SaaSFlow Analytics · Alertas de retención
Solicitud — Paso 0: Intake
"Necesitamos un sistema de alertas automáticas: cuando la retención de usuarios de un plan cae más de un 10% semana-sobre-semana, que envíe un email al account manager con el resumen del cohort y un enlace directo al dashboard."
Pipeline de Ejecución
📋
Fase 0
Intake + Clasificación de Tamaño
code-explorer
  • Restatement: nueva capacidad de notificación → orch-add-feature
  • Módulo nuevo: /src/lib/notifications/ (actualmente vacío) + 1 API route
  • Nueva dependencia externa: proveedor de email (Resend) + cron Vercel
Trivial1 archivo, cambio obvio
Fases: 4→5→6
Small1 función, claro al leer
Fases: 1→4→5→6
Standard2–5 archivos, dep. interna
Fases: 1→2→4→5→6
▶ Esta tarea
LargeCross-cutting, dep. externa
Fases: 1→2→3→4→5→6
🔍
Fase 1
Research & Reuse
gh search + Context7
  • gh search repos "supabase pg_cron email alert typescript" → 3 repos relevantes encontrados
  • Context7: docs Resend SDK v3 — resend.emails.send() con React Email templates
  • Package registry: @react-email/components v0.0.22, resend v4.0.0
  • Decisión: adoptar React Email (probado, compatible) en lugar de plantilla custom
  • Cron: Vercel Cron Jobs (vercel.json) — sin dep. adicional
🗂️
Fase 2
Plan — Task List
planner agent
Slices verticales ordenados por dependencia:
task_list — pendiente GATE 1
T-1Definir tipos RetentionAlert y CohortSnapshot en src/types/alerts.tsS
T-2Función computeWeeklyRetentionDelta() en src/lib/analytics/cohorts.ts (amplía existente)S
T-3Servicio src/lib/notifications/emailAlerter.ts — env Resend, template React EmailM
T-4API route app/api/cron/retention-alerts/route.ts — orquesta T-2 + T-3, secret headerM
T-5Config vercel.json — cron 0 9 * * 1 (lunes 09:00 UTC)S
T-6Env vars: RESEND_API_KEY, CRON_SECRET — docs en .env.exampleS
🚦 GATE 1 — Aprobación del Plan / El usuario aprobó el task_list antes de iniciar implementación
🧪
Fase 4
Implement (TDD — Red → Green → Refactor)
tdd-guide agent
Ciclo por tarea: test en rojo primero, luego implementación mínima, luego refactor.
Vitest — suite retention-alerts ✓ 14 passed · 0 failed
✅computeWeeklyRetentionDelta › devuelve delta negativo cuando retención baja >10%12ms
✅computeWeeklyRetentionDelta › NO dispara alerta si delta < umbral8ms
✅computeWeeklyRetentionDelta › maneja cohort vacío sin lanzar excepción5ms
✅emailAlerter › llama a resend.emails.send() con destinatario correcto21ms
✅emailAlerter › incluye link con cohortId en el body del email14ms
✅emailAlerter › no envía email si no hay alertas activas6ms
✅API /cron › rechaza sin CRON_SECRET header (401)9ms
✅API /cron › responde 200 y count de alertas enviadas18ms
Cobertura global
82% ✓ (≥80%)
🔎
Fase 5
Review (Code + Security)
code-reviewer + security-reviewer
Security trigger activo: external API calls (Resend) + secrets/credentials (CRON_SECRET, RESEND_API_KEY)
Sev.HallazgoResolución
WARN CRON_SECRET comparado con === — susceptible a timing attack Reemplazado con crypto.timingSafeEqual() ✓
WARN RESEND_API_KEY loggeada en bloque catch en modo dev Reemplazada por [REDACTED] en logs ✓
INFO Tipo CohortSnapshot no exportado — inutilizable desde otros módulos Añadido export en alerts.ts ✓
OK Validación de input API route, manejo de errores Resend, env vars Sin hallazgos críticos ni altos
🚦 GATE 2 — Aprobación del Diff / El usuario revisó el resumen del diff y aprobó los mensajes de commit
📦
Fase 6
Commit (conventional commits)
git — 4 commits
a1b2c3d feat feat(alerts): add RetentionAlert and CohortSnapshot types
e4f5a6b feat feat(analytics): add computeWeeklyRetentionDelta() to cohorts
7c8d9e0 feat feat(notifications): add emailAlerter service with Resend + React Email
f1a2b3c feat feat(cron): add /api/cron/retention-alerts route + vercel.json schedule
d4e5f6a test test(alerts): add 14 unit tests, coverage 74%→82%
b7c8d9e fix fix(security): use timingSafeEqual for CRON_SECRET, redact key in logs
6
Fases ejecutadas
2
Gates humanos
82%
Cobertura tests
0
Hallazgos críticos
CULTIVA IA · Motor de Orquestación Dev · SaaSFlow Analytics · 2026