theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/regresion-codigo-ia/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: regresion-codigo-ia
+description: Estrategias de testing de regresión para desarrollo asistido por IA. Testing de APIs en modo sandbox sin dependencia de base de datos, flujos automatizados de chequeo de bugs y patrones para atrapar los puntos ciegos de la IA cuando el mismo modelo escribe y revisa el código.
+---
+
+# Testing de regresión para código escrito por IA
+
+Patrones de testing diseñados específicamente para el desarrollo asistido por IA, donde el mismo modelo escribe el código y luego lo revisa — lo que crea puntos ciegos sistemáticos que solo los tests automatizados pueden atrapar.
+
+## Cuándo activarla
+
+- Un agente de IA modificó rutas de API o lógica de backend
+- Se encontró y corrigió un bug — hay que evitar que se reintroduzca
+- El proyecto tiene un modo sandbox/mock que puede aprovecharse para testing sin base de datos
+- Se ejecuta un comando de revisión de bugs (personalizado del proyecto) después de cambios de código
+- Existen múltiples rutas de código (sandbox vs producción, feature flags, etc.)
+
+## El problema de fondo
+
+Cuando una IA escribe código y luego revisa su propio trabajo, arrastra los mismos supuestos a ambos pasos. Esto crea un patrón de fallo predecible:
+
+```
+La IA escribe el fix → La IA revisa el fix → La IA dice "se ve correcto" → El bug sigue ahí
+```
+
+**Ejemplo real** (observado en producción):
+
+```
+Fix 1: Se agregó notification_settings a la respuesta de la API
+  → Se olvidó agregarlo a la consulta SELECT
+  → La IA lo revisó y no lo vio (mismo punto ciego)
+
+Fix 2: Se agregó a la consulta SELECT
+  → Error de build de TypeScript (la columna no estaba en los tipos generados)
+  → La IA revisó el Fix 1 pero no detectó el problema del SELECT
+
+Fix 3: Se cambió a SELECT *
+  → Arregló la ruta de producción, olvidó la ruta sandbox
+  → La IA lo revisó y OTRA VEZ no lo vio (4.ª ocurrencia)
+
+Fix 4: Un test lo atrapó al instante en la primera ejecución PASS:
+```
+
+El patrón: **la inconsistencia entre las rutas sandbox/producción** es la regresión número 1 introducida por IA.
+
+## Testing de APIs en modo sandbox
+
+La mayoría de los proyectos con arquitectura amigable para IA tienen un modo sandbox/mock. Esa es la clave para testear APIs de forma rápida y sin base de datos.
+
+### Configuración (Vitest + Next.js App Router)
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: true,
+    include: ["__tests__/**/*.test.ts"],
+    setupFiles: ["__tests__/setup.ts"],
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "."),
+    },
+  },
+});
+```
+
+```typescript
+// __tests__/setup.ts
+// Forzar el modo sandbox — no se necesita base de datos
+process.env.SANDBOX_MODE = "true";
+process.env.NEXT_PUBLIC_SUPABASE_URL = "";
+process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY = "";
+```
+
+### Helper de tests para rutas de API de Next.js
+
+```typescript
+// __tests__/helpers.ts
+import { NextRequest } from "next/server";
+
+export function createTestRequest(
+  url: string,
+  options?: {
+    method?: string;
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    sandboxUserId?: string;
+  },
+): NextRequest {
+  const { method = "GET", body, headers = {}, sandboxUserId } = options || {};
+  const fullUrl = url.startsWith("http") ? url : `http://localhost:3000${url}`;
+  const reqHeaders: Record<string, string> = { ...headers };
+
+  if (sandboxUserId) {
+    reqHeaders["x-sandbox-user-id"] = sandboxUserId;
+  }
+
+  const init: { method: string; headers: Record<string, string>; body?: string } = {
+    method,
+    headers: reqHeaders,
+  };
+
+  if (body) {
+    init.body = JSON.stringify(body);
+    reqHeaders["content-type"] = "application/json";
+  }
+
+  return new NextRequest(fullUrl, init);
+}
+
+export async function parseResponse(response: Response) {
+  const json = await response.json();
+  return { status: response.status, json };
+}
+```
+
+### Cómo escribir tests de regresión
+
+El principio clave: **escribe tests para los bugs que se encontraron, no para el código que funciona**.
+
+```typescript
+// __tests__/api/user/profile.test.ts
+import { describe, it, expect } from "vitest";
+import { createTestRequest, parseResponse } from "../../helpers";
+import { GET, PATCH } from "@/app/api/user/profile/route";
+
+// Definir el contrato — qué campos DEBEN estar en la respuesta
+const REQUIRED_FIELDS = [
+  "id",
+  "email",
+  "full_name",
+  "phone",
+  "role",
+  "created_at",
+  "avatar_url",
+  "notification_settings",  // ← Agregado después de que un bug reveló que faltaba
+];
+
+describe("GET /api/user/profile", () => {
+  it("devuelve todos los campos requeridos", async () => {
+    const req = createTestRequest("/api/user/profile");
+    const res = await GET(req);
+    const { status, json } = await parseResponse(res);
+
+    expect(status).toBe(200);
+    for (const field of REQUIRED_FIELDS) {
+      expect(json.data).toHaveProperty(field);
+    }
+  });
+
+  // Test de regresión — la IA introdujo este bug exacto 4 veces
+  it("notification_settings no es undefined (regresión BUG-R1)", async () => {
+    const req = createTestRequest("/api/user/profile");
+    const res = await GET(req);
+    const { json } = await parseResponse(res);
+
+    expect("notification_settings" in json.data).toBe(true);
+    const ns = json.data.notification_settings;
+    expect(ns === null || typeof ns === "object").toBe(true);
+  });
+});
+```
+
+### Testear la paridad sandbox/producción
+
+La regresión de IA más común: arreglar la ruta de producción y olvidar la ruta sandbox (o viceversa).
+
+```typescript
+// Verificar que las respuestas del sandbox cumplen el contrato esperado
+describe("GET /api/user/messages (lista de conversaciones)", () => {
+  it("incluye partner_name en modo sandbox", async () => {
+    const req = createTestRequest("/api/user/messages", {
+      sandboxUserId: "user-001",
+    });
+    const res = await GET(req);
+    const { json } = await parseResponse(res);
+
+    // Esto atrapó un bug donde partner_name se agregó
+    // a la ruta de producción pero no a la ruta sandbox
+    if (json.data.length > 0) {
+      for (const conv of json.data) {
+        expect("partner_name" in conv).toBe(true);
+      }
+    }
+  });
+});
+```
+
+## Integrar los tests en un flujo de chequeo de bugs
+
+### Definición de un comando personalizado
+
+Define en tu proyecto un comando personalizado de revisión de bugs (por ejemplo `/chequeo-bugs`):
+
+```markdown
+<!-- .theus/commands/chequeo-bugs.md -->
+# Chequeo de bugs
+
+## Paso 1: Tests automatizados (obligatorio, no se puede saltar)
+
+Ejecuta estos comandos PRIMERO, antes de cualquier revisión de código:
+
+    npm run test       # Suite de tests con Vitest
+    npm run build      # Chequeo de tipos de TypeScript + build
+
+- Si los tests fallan → reportar como el bug de mayor prioridad
+- Si el build falla → reportar los errores de tipos como máxima prioridad
+- Solo continuar al Paso 2 si ambos pasan
+
+## Paso 2: Revisión de código (revisión por IA)
+
+1. Consistencia entre las rutas sandbox / producción
+2. La forma de la respuesta de la API coincide con lo que espera el frontend
+3. Completitud de la cláusula SELECT
+4. Manejo de errores con rollback
+5. Condiciones de carrera en actualizaciones optimistas
+
+## Paso 3: Por cada bug corregido, proponer un test de regresión
+```
+
+### El flujo
+
+```
+Usuario: "Revisa si hay bugs" (o "/chequeo-bugs")
+  │
+  ├─ Paso 1: npm run test
+  │   ├─ FALLA → Bug encontrado mecánicamente (sin necesidad de juicio de la IA)
+  │   └─ PASA → Continuar
+  │
+  ├─ Paso 2: npm run build
+  │   ├─ FALLA → Error de tipos encontrado mecánicamente
+  │   └─ PASA → Continuar
+  │
+  ├─ Paso 3: Revisión de código por IA (con los puntos ciegos conocidos en mente)
+  │   └─ Reportar los hallazgos
+  │
+  └─ Paso 4: Por cada fix, escribir un test de regresión
+      └─ El siguiente chequeo lo atrapa si el fix se rompe
+```
+
+## Patrones comunes de regresión introducida por IA
+
+### Patrón 1: Desajuste entre las rutas sandbox/producción
+
+**Frecuencia**: el más común (observado en 3 de 4 regresiones)
+
+```typescript
+// FAIL: La IA agrega el campo solo a la ruta de producción
+if (isSandboxMode()) {
+  return { data: { id, email, name } };  // Falta el campo nuevo
+}
+// Ruta de producción
+return { data: { id, email, name, notification_settings } };
+
+// PASS: Ambas rutas deben devolver la misma forma
+if (isSandboxMode()) {
+  return { data: { id, email, name, notification_settings: null } };
+}
+return { data: { id, email, name, notification_settings } };
+```
+
+**Test para atraparlo**:
+
+```typescript
+it("sandbox y producción devuelven los mismos campos", async () => {
+  // En el entorno de tests, el modo sandbox está forzado a ON
+  const res = await GET(createTestRequest("/api/user/profile"));
+  const { json } = await parseResponse(res);
+
+  for (const field of REQUIRED_FIELDS) {
+    expect(json.data).toHaveProperty(field);
+  }
+});
+```
+
+### Patrón 2: Omisión en la cláusula SELECT
+
+**Frecuencia**: común con Supabase/Prisma al agregar columnas nuevas
+
+```typescript
+// FAIL: Columna nueva agregada a la respuesta pero no al SELECT
+const { data } = await supabase
+  .from("users")
+  .select("id, email, name")  // notification_settings no está aquí
+  .single();
+
+return { data: { ...data, notification_settings: data.notification_settings } };
+// → notification_settings siempre es undefined
+
+// PASS: Usar SELECT * o incluir explícitamente las columnas nuevas
+const { data } = await supabase
+  .from("users")
+  .select("*")
+  .single();
+```
+
+### Patrón 3: Fuga de estado en errores
+
+**Frecuencia**: moderada — al agregar manejo de errores a componentes existentes
+
+```typescript
+// FAIL: Se establece el estado de error pero no se limpian los datos viejos
+catch (err) {
+  setError("No se pudo cargar");
+  // ¡reservations sigue mostrando los datos de la pestaña anterior!
+}
+
+// PASS: Limpiar el estado relacionado al manejar el error
+catch (err) {
+  setReservations([]);  // Limpiar los datos obsoletos
+  setError("No se pudo cargar");
+}
+```
+
+### Patrón 4: Actualización optimista sin rollback adecuado
+
+```typescript
+// FAIL: Sin rollback en caso de fallo
+const handleRemove = async (id: string) => {
+  setItems(prev => prev.filter(i => i.id !== id));
+  await fetch(`/api/items/${id}`, { method: "DELETE" });
+  // Si la API falla, el ítem desaparece de la UI pero sigue en la BD
+};
+
+// PASS: Capturar el estado previo y hacer rollback si falla
+const handleRemove = async (id: string) => {
+  const prevItems = [...items];
+  setItems(prev => prev.filter(i => i.id !== id));
+  try {
+    const res = await fetch(`/api/items/${id}`, { method: "DELETE" });
+    if (!res.ok) throw new Error("API error");
+  } catch {
+    setItems(prevItems);  // Rollback
+    alert("No se pudo eliminar");
+  }
+};
+```
+
+## Estrategia: testea donde se encontraron los bugs
+
+No apuntes a una cobertura del 100 %. En su lugar:
+
+```
+Bug encontrado en /api/user/profile     → Escribir test para la API de perfil
+Bug encontrado en /api/user/messages    → Escribir test para la API de mensajes
+Bug encontrado en /api/user/favorites   → Escribir test para la API de favoritos
+Sin bugs en /api/user/notifications     → No escribir test (todavía)
+```
+
+**Por qué esto funciona en el desarrollo con IA:**
+
+1. La IA tiende a cometer **la misma categoría de error** repetidamente
+2. Los bugs se agrupan en las áreas complejas (auth, lógica multi-ruta, gestión de estado)
+3. Una vez testeada, esa regresión exacta **no puede volver a ocurrir**
+4. El número de tests crece orgánicamente con los fixes — sin esfuerzo desperdiciado
+
+## Referencia rápida
+
+| Patrón de regresión de IA | Estrategia de test | Prioridad |
+|---|---|---|
+| Desajuste sandbox/producción | Verificar la misma forma de respuesta en modo sandbox | Alta |
+| Omisión en la cláusula SELECT | Verificar todos los campos requeridos en la respuesta | Alta |
+| Fuga de estado en errores | Verificar la limpieza del estado ante un error | Media |
+| Rollback ausente | Verificar que el estado se restaura si la API falla | Media |
+| Cast de tipos que enmascara null | Verificar que el campo no es undefined | Media |
+
+## SÍ / NO
+
+**SÍ:**
+
+- Escribe los tests inmediatamente después de encontrar un bug (antes de arreglarlo, si es posible)
+- Testea la forma de la respuesta de la API, no la implementación
+- Ejecuta los tests como primer paso de cada chequeo de bugs
+- Mantén los tests rápidos (< 1 segundo en total con el modo sandbox)
+- Nombra los tests según el bug que previenen (p. ej. "regresión BUG-R1")
+
+**NO:**
+
+- No escribas tests para código que nunca ha tenido un bug
+- No confíes en la autorevisión de la IA como sustituto de los tests automatizados
+- No te saltes el testing de la ruta sandbox porque "solo son datos mock"
+- No escribas tests de integración cuando bastan tests unitarios
+- No apuntes a un porcentaje de cobertura — apunta a prevenir regresiones