theus-cli 0.2.83 → 0.2.84

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

@@ -1,388 +0,0 @@
----
-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