refacil-sdd-ai 2.0.9 → 2.1.0

package/README.md

@@ -49,10 +49,12 @@ refacil-sdd-ai update
 ## Comandos del CLI
 
 ```bash
-refacil-sdd-ai init      # Instalar skills y crear configs en el repo actual
-refacil-sdd-ai update    # Actualizar skills a la ultima version
-refacil-sdd-ai clean     # Eliminar skills del repo
-refacil-sdd-ai help      # Ver ayuda
+refacil-sdd-ai init          # Instalar skills, hooks y crear configs en el repo actual
+refacil-sdd-ai update        # Actualizar skills y hooks a la ultima version
+refacil-sdd-ai check-update  # Verifica si hay una version mas reciente en npm (usado por hook)
+refacil-sdd-ai check-review  # Verifica que el review se haya completado (usado por hook)
+refacil-sdd-ai clean         # Eliminar skills del repo
+refacil-sdd-ai help          # Ver ayuda
 ```
 
 ## Skills disponibles
@@ -95,11 +97,11 @@ Para mantener trazabilidad y calidad sin pasos innecesarios:
 2. `/refacil:apply`
 3. `/refacil:test`
 4. `/refacil:verify`
-5. `/refacil:review`
+5. `/refacil:review` (automatico si no se ejecuto — ver [Hooks automaticos](#hooks-automaticos))
 6. `/refacil:archive`
 7. `/refacil:up-code`
 
-Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar en `review -> up-code`.
+Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `up-code` (el review se ejecuta automaticamente si no se hizo).
 
 ## Flujos de trabajo
 
@@ -113,19 +115,23 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar en `review ->
 /refacil:verify
 # → Si hay correcciones: verify pregunta si aplicarlas automaticamente
 # → Si aprueba: aplica fixes y re-verifica (max 2 rondas)
-/refacil:review
+/refacil:review          # opcional — se ejecuta automaticamente en up-code si no se hizo
 /refacil:archive
-/refacil:up-code
+/refacil:up-code         # si falta review, lo ejecuta automaticamente antes del push
 ```
 
 ### Bug fix
 
 ```
 /refacil:bug "descripcion del error"
-/refacil:review
-/refacil:up-code
+# → Investiga, implementa fix, genera tests de regresion
+# → Crea trazabilidad en openspec/changes/fix-[ID]-[nombre]/summary.md
+# → Pregunta por ID de ticket (ej. REF-123) para nombrar la carpeta
+/refacil:up-code         # ejecuta review automaticamente si no se hizo
 ```
 
+> **Nota**: En una misma rama pueden corregirse multiples bugs. Cada uno genera su propia carpeta `fix-*` con su trazabilidad independiente.
+
 ### Explorar codigo
 
 ```
@@ -149,18 +155,61 @@ Antes de avanzar de etapa, valida estos estados:
 - `READY_FOR_APPLY`: artefactos SDD completos + aprobacion explicita
 - `READY_FOR_VERIFY`: implementacion terminada y enfocada al alcance
 - `READY_FOR_REVIEW`: verify ejecutado y bloqueantes tratados
-- `READY_FOR_ARCHIVE`: cambio funcionalmente cerrado
+- `READY_FOR_ARCHIVE`: cambio funcionalmente cerrado + review aprobado (`.review-passed`)
 - `READY_FOR_MERGE`: rama lista para PR
 
+### Hooks automaticos
+
+El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
+
+| Hook | Evento | Que hace |
+|------|--------|----------|
+| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm e informa al usuario |
+| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, ejecuta `/refacil:review` automaticamente |
+
+#### Flujo del hook de review
+
+```
+/refacil:up-code (o git push manual)
+  → Hook check-review se dispara
+  → Busca carpetas en openspec/changes/ (excluye archive/)
+  → ¿Todas tienen .review-passed?
+      SI → permite el push
+      NO → bloquea y ejecuta /refacil:review automaticamente
+            → Si APROBADO: crea .review-passed, reintenta push
+            → Si REQUIERE CORRECCIONES: informa al usuario, no pushea
+```
+
+#### Evidencia de review
+
+Cuando `/refacil:review` aprueba un cambio, crea el archivo `.review-passed` en la carpeta del cambio:
+
+```
+openspec/changes/mi-feature/
+├── proposal.md
+├── design.md
+├── tasks.md
+├── specs.md
+└── .review-passed        ← evidencia de review aprobado (JSON)
+
+openspec/changes/fix-REF-123-login-timeout/
+├── summary.md            ← trazabilidad del bug fix
+└── .review-passed        ← evidencia de review aprobado (JSON)
+```
+
+El archivo `.review-passed` contiene: veredicto, fecha, resumen, cantidad de hallazgos y si hubo blockers.
+
 ## Como funciona
 
-1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, y crea `CLAUDE.md` + `.cursorrules`
+1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, crea `CLAUDE.md` + `.cursorrules`, y configura hooks automaticos en `.claude/settings.json`
 2. **`/refacil:setup`** (en Claude Code o Cursor) instala OpenSpec, analiza el repo y genera un `AGENTS.md` personalizado
 3. Las demas skills (`propose`, `apply`, `test`, etc.) leen `AGENTS.md` para entender las convenciones del proyecto
+4. Los hooks garantizan calidad automaticamente: verificacion de version al iniciar sesion y review obligatorio antes de push
 
 ```
 refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
                                  CLAUDE.md y .cursorrules creados
+                                 Hooks configurados en .claude/settings.json
 
 /refacil:setup               →  OpenSpec instalado
                                  AGENTS.md generado (analisis automatico del repo)
@@ -169,15 +218,17 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 /refacil:apply               →  Codigo implementado
 /refacil:test                →  Tests generados
 /refacil:verify              →  Validacion PASS/FAIL (puede aplicar fixes con aprobacion)
-/refacil:review              →  Review con checklist
+/refacil:review              →  Review con checklist + .review-passed si aprueba
+/refacil:bug                 →  Fix + trazabilidad en openspec/changes/fix-*/summary.md
 /refacil:archive             →  Cambio archivado
-/refacil:up-code             →  Push a rama de desarrollo
+/refacil:up-code             →  Review automatico (si falta) + push a rama de desarrollo
 ```
 
 ## Que se instala en tu repo
 
 ```
 .claude/skills/refacil-*/    # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
+.claude/settings.json        # Hooks automaticos (check-update + check-review)
 .cursor/skills/refacil-*/    # Cursor — copia equivalente
 .../refacil-setup/           # troubleshooting.md si falla install/PATH
 CLAUDE.md                    # Claude Code — apunta a AGENTS.md

package/bin/cli.js

@@ -149,23 +149,48 @@ function installHook() {
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
 
-  // Skip if already installed (marked with _sdd)
-  const alreadyInstalled = settings.hooks.SessionStart.some(h => h._sdd === true);
-  if (alreadyInstalled) {
-    console.log('  Hook check-update ya configurado.');
-    return false;
+  let changed = false;
+
+  // SessionStart: check-update
+  const hasUpdateHook = settings.hooks.SessionStart.some(h => h._sdd === true);
+  if (!hasUpdateHook) {
+    settings.hooks.SessionStart.push({
+      _sdd: true,
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: 'refacil-sdd-ai check-update',
+        },
+      ],
+    });
+    changed = true;
   }
 
-  settings.hooks.SessionStart.push({
-    _sdd: true,
-    matcher: '',
-    hooks: [
-      {
-        type: 'command',
-        command: 'refacil-sdd-ai check-update',
-      },
-    ],
-  });
+  // PreToolUse: check-review
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const hasReviewHook = settings.hooks.PreToolUse.some(
+    (h) => h._sdd_review === true,
+  );
+  if (!hasReviewHook) {
+    settings.hooks.PreToolUse.push({
+      _sdd_review: true,
+      matcher: 'Bash',
+      hooks: [
+        {
+          type: 'command',
+          command: 'refacil-sdd-ai check-review',
+        },
+      ],
+    });
+    changed = true;
+  }
+
+  if (!changed) {
+    console.log('  Hooks SDD-AI ya configurados.');
+    return false;
+  }
 
   fs.mkdirSync(settingsDir, { recursive: true });
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -197,6 +222,55 @@ function checkUpdate() {
   }
 }
 
+// --- Check review (PreToolUse hook) ---
+
+function checkReview() {
+  // Read stdin (JSON from PreToolUse hook)
+  let input;
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    input = JSON.parse(stdin);
+  } catch (_) {
+    // If no stdin or invalid JSON, allow (not called from hook context)
+    return;
+  }
+
+  // Only block git push commands
+  const command = (input.tool_input && input.tool_input.command) || '';
+  if (!command.match(/git\s+push/)) return;
+
+  // Find active change in openspec/changes/ (exclude archive/)
+  const changesDir = path.join(projectRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) return; // No openspec, allow
+
+  const entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  const activeChanges = entries.filter(
+    (e) => e.isDirectory() && e.name !== 'archive',
+  );
+
+  if (activeChanges.length === 0) return; // No active changes, allow
+
+  // Check if any active change is missing .review-passed
+  const missing = activeChanges.filter(
+    (e) => !fs.existsSync(path.join(changesDir, e.name, '.review-passed')),
+  );
+
+  if (missing.length > 0) {
+    const names = missing.map((e) => e.name).join(', ');
+    console.log(
+      JSON.stringify({
+        decision: 'block',
+        reason:
+          `[refacil-sdd-ai] Review pendiente para: ${names}. ` +
+          'Ejecuta la skill /refacil:review automaticamente ahora sobre los cambios pendientes. ' +
+          'Informa al usuario que el review se esta ejecutando automaticamente antes de subir el codigo. ' +
+          'Si el review aprueba, reintenta el git push. ' +
+          'Si el review requiere correcciones, informa los hallazgos al usuario y NO reintentar el push.',
+      }),
+    );
+  }
+}
+
 // --- Commands ---
 
 function init() {
@@ -267,6 +341,7 @@ function help() {
     init          Instala skills en .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
     update        Re-copia skills (para actualizar a nueva version del paquete)
     check-update  Verifica si hay una version mas reciente en npm
+    check-review  Verifica que el review se haya completado (usado por hook PreToolUse)
     clean         Elimina skills de .claude/ y .cursor/
     help          Muestra esta ayuda
 
@@ -296,6 +371,9 @@ switch (command) {
   case 'check-update':
     checkUpdate();
     break;
+  case 'check-review':
+    checkReview();
+    break;
   case 'clean':
     clean();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/bug/SKILL.md

@@ -103,7 +103,32 @@ describe('Bug Fix: [descripcion corta]', () => {
 });
 ```
 
-### Paso 8: Verificar
+### Paso 8: Crear trazabilidad del fix (obligatorio)
+
+Pregunta al usuario: **"Tienes un ID de tarea o ticket para este bug? (ej. REF-123, JIRA-456)"**
+- Si responde con un ID → nombre de carpeta: `fix-[ID]-[descripcion-corta]` (ej. `fix-REF-123-login-timeout`)
+- Si no tiene o quiere continuar → genera un nombre descriptivo corto: `fix-[descripcion-corta]` (maximo 3-4 palabras en kebab-case, ej. `fix-null-pointer-payment`)
+
+**No uses el nombre de la rama** como nombre de carpeta — en una misma rama pueden corregirse multiples bugs, cada uno con su propia carpeta fix.
+
+Crea la carpeta en `openspec/changes/[nombre-fix]/` con un archivo `summary.md`:
+
+```markdown
+# Fix: [descripcion corta]
+
+- **Fecha**: [fecha ISO]
+- **Severidad**: [Critico|Alto|Medio|Bajo]
+- **Causa raiz**: [explicacion breve]
+- **Fix aplicado**: [que se cambio]
+- **Archivos modificados**: [lista]
+- **Tests de regresion**: [N] tests agregados
+```
+
+Este archivo es obligatorio para la trazabilidad del fix y permite que el hook de review (`check-review`) detecte el cambio activo. El archivo `.review-passed` sera creado por `/refacil:review` al aprobar.
+
+**Opcionalmente**, si el bug es significativo, el usuario puede pedir artefactos completos de OpenSpec (proposal.md, design.md, tasks.md, specs) en esta misma carpeta.
+
+### Paso 9: Verificar y siguientes pasos
 
 1. Resuelve el comando de tests segun `METHODOLOGY-CONTRACT.md` y ejecutalo — todos los tests deben pasar
 2. Muestra resumen del fix
@@ -115,25 +140,20 @@ describe('Bug Fix: [descripcion corta]', () => {
  Fix: [que se cambio]
  Archivos modificados: [lista]
  Tests de regresion: [N] tests agregados
+ Trazabilidad: openspec/changes/fix-[nombre]/summary.md
  [comando-test]: PASS
 
  Siguientes pasos:
- 1. /refacil:review — Review del fix (recomendado para bugs criticos)
+ 1. /refacil:review — Review del fix (obligatorio antes de push)
  2. /refacil:up-code — Subir los cambios a tu rama de desarrollo
 ```
 
-### Paso 9 (opcional): Crear artefactos OpenSpec
-
-Si el bug es significativo, preguntar al usuario si quiere documentarlo en OpenSpec:
-- Crear carpeta en `openspec/changes/fix-[nombre]/`
-- Generar `proposal.md`, `design.md`, `tasks.md` y especificacion (`specs.md` y/o `specs/**/*.md`, misma regla que `refacil:propose`)
-
 ## Reglas
 
 - SIEMPRE investigar antes de proponer una correccion
 - NUNCA implementar sin aprobacion del usuario
 - El fix debe ser MINIMO — no aprovechar para refactorizar
 - Los tests de regresion son OBLIGATORIOS
-- Si el bug es en produccion (critico), priorizar velocidad pero sin saltarse tests
+- Si el bug es en produccion (critico), priorizar velocidad pero sin saltarse tests ni trazabilidad
 - Responder en español con terminos tecnicos en ingles
 - Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)

package/skills/review/SKILL.md

@@ -12,7 +12,15 @@ Eres un reviewer exigente pero constructivo que evalua el codigo contra el check
 
 Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `agents`** antes de continuar.
 Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` y aplica el modo de salida definido ahi.
-Lee el archivo [checklist.md](checklist.md) para conocer los criterios de evaluacion.
+
+### Cargar checklists
+
+1. **Siempre** lee el checklist general: [checklist.md](checklist.md)
+2. **Detecta el tipo de proyecto** inspeccionando dependencias, `AGENTS.md`, o la estructura del repo:
+   - Si tiene frameworks de servidor, APIs, microservicios, acceso a BD, colas o workers → lee tambien [checklist-back.md](checklist-back.md)
+   - Si tiene estructura de componentes UI, manejo de estado en cliente, rutas/vistas o consume APIs para renderizar interfaces → lee tambien [checklist-front.md](checklist-front.md)
+   - Si es fullstack (tiene ambos) → lee ambos checklists especificos
+3. Evalua **solo** los items de los checklists que apliquen. Marca N/A en items que no correspondan al tipo de proyecto.
 
 ## Instrucciones
 
@@ -68,22 +76,71 @@ BLOCKERS: [si/no]
    - Evidencia: [archivo/rango o comportamiento]
    - Correccion sugerida: [accion concreta]
 
-## Checklist resumido
+## Checklist General
+- Alcance y foco: [PASS/FAIL/N/A]
 - Conformidad con Spec: [PASS/FAIL/N/A]
 - Calidad de Codigo: [PASS/FAIL/N/A]
 - Arquitectura: [PASS/FAIL/N/A]
+- Manejo de errores: [PASS/FAIL/N/A]
 - Testing: [PASS/FAIL/N/A]
 - Seguridad: [PASS/FAIL/N/A]
-- Performance: [PASS/FAIL/N/A]
-- Mantenibilidad: [PASS/FAIL/N/A]
+- Dependencias: [PASS/FAIL/N/A]
+- Mantenibilidad y observabilidad: [PASS/FAIL/N/A]
 - Git y Deploy: [PASS/FAIL/N/A]
 - Reglas del proyecto (AGENTS.md): [PASS/FAIL/N/A]
 
+## Checklist Backend (si aplica)
+- Validacion de entrada: [PASS/FAIL/N/A]
+- Contratos de API: [PASS/FAIL/N/A]
+- Manejo de errores: [PASS/FAIL/N/A]
+- Arquitectura y patrones: [PASS/FAIL/N/A]
+- Concurrencia y atomicidad: [PASS/FAIL/N/A]
+- Consultas a BD: [PASS/FAIL/N/A]
+- Caching: [PASS/FAIL/N/A]
+- Resiliencia y conexiones: [PASS/FAIL/N/A]
+- Colas y mensajeria: [PASS/FAIL/N/A]
+- Performance: [PASS/FAIL/N/A]
+- Logging: [PASS/FAIL/N/A]
+- Testing backend: [PASS/FAIL/N/A]
+
+## Checklist Frontend (si aplica)
+- Componentes y estructura: [PASS/FAIL/N/A]
+- Estado y datos: [PASS/FAIL/N/A]
+- Manejo de errores en UI: [PASS/FAIL/N/A]
+- Integracion con APIs: [PASS/FAIL/N/A]
+- Validacion de formularios: [PASS/FAIL/N/A]
+- Ruteo y navegacion: [PASS/FAIL/N/A]
+- Consistencia visual: [PASS/FAIL/N/A]
+- Performance frontend: [PASS/FAIL/N/A]
+- Accesibilidad: [PASS/FAIL/N/A]
+- Seguridad frontend: [PASS/FAIL/N/A]
+- Testing frontend: [PASS/FAIL/N/A]
+
 ## Correcciones minimas para aprobar
 1. [item accionable]
 2. [item accionable]
 ```
 
+### Paso 5: Marcador de review (obligatorio si APROBADO)
+
+Si el veredicto es **APROBADO** o **APROBADO CON OBSERVACIONES**, crea un archivo marcador en el directorio del cambio activo:
+
+**Ruta:** `openspec/changes/[nombre-cambio]/.review-passed`
+
+**Contenido (JSON):**
+```json
+{
+  "verdict": "APROBADO|APROBADO CON OBSERVACIONES",
+  "date": "<fecha ISO actual>",
+  "changeName": "<nombre-cambio>",
+  "summary": "<resumen de 1 linea del resultado>",
+  "failCount": <numero de FAILs encontrados>,
+  "blockers": false
+}
+```
+
+Este archivo es evidencia de que el review se completo y es requerido por el hook de `PreToolUse` antes de permitir `git push`. No lo crees si el veredicto es REQUIERE CORRECCIONES.
+
 ## Reglas
 
 - Ser constructivo: no solo decir que falla, sino como corregirlo

package/skills/review/checklist-back.md

@@ -0,0 +1,91 @@
+# Checklist Backend — Equipo Refacil
+
+> Complementa el [checklist general](checklist.md). Aplica a repositorios **backend** (APIs, microservicios, workers, colas).
+> Detectar tipo: si el proyecto tiene frameworks de servidor (HTTP, gRPC, mensajeria), estructura de microservicios, o acceso a base de datos, aplica este checklist.
+> Marcar N/A en secciones que no apliquen al cambio revisado (ej. colas si el cambio no toca mensajeria).
+
+## B1. Validacion de entrada
+- Los DTOs/objetos de entrada de endpoints usan el mecanismo de validacion automatica del framework
+- Cada campo declara tipo y restricciones (obligatorio, formato, rango)
+- Endpoints nombrados en kebab-case (`get-user-info`, `create-payment`)
+- No se confian datos del cliente sin validar (query params, headers, body)
+
+## B2. Contratos de API
+- Las respuestas usan una estructura consistente (no retornar formatos distintos segun el caso)
+- Los codigos HTTP son correctos y especificos (no todo es 200 o 500)
+- Los DTOs de respuesta no exponen campos internos (IDs de BD, campos de auditoria, relaciones internas)
+- Si el endpoint es consumido por otro servicio: verificar que no se introduzcan breaking changes en el contrato (campos renombrados, eliminados o con tipo diferente)
+- Los errores retornan un formato estandar con mensaje entendible para el consumidor
+
+## B3. Manejo de errores (estandar Refacil)
+- No hay bloques try/catch anidados o multiples en un mismo hilo de peticion
+- Los errores se capturan, loggean y devuelven respuestas formateadas
+- Modulos/servicios nuevos usan el filtro o middleware global de excepciones del proyecto (si existe)
+- Se distingue entre errores del cliente (4xx) y errores del servidor (5xx)
+- Los errores de dependencias externas (APIs, BD, colas) se manejan con mensajes propios, no se propagan tal cual al consumidor
+
+## B4. Arquitectura y patrones
+- **Responsabilidad por capas**: no hay logica de negocio en la capa de transporte (controllers/handlers) ni en la capa de infraestructura (repositorios/adaptadores)
+- Los DTOs estan en la capa correcta (entrada en transporte, salida en aplicacion)
+- Repository Pattern para acceso a datos (si el proyecto tiene un repositorio base, los nuevos lo extienden)
+- Si es un microservicio nuevo, sigue la estructura definida en AGENTS.md (hexagonal, clean architecture, etc.)
+- Las dependencias fluyen en la direccion correcta segun la arquitectura del proyecto
+
+## B5. Concurrencia y atomicidad
+- Las operaciones que modifican multiples registros o tablas usan transacciones de BD (todo o nada)
+- Los endpoints de escritura criticos (pagos, transferencias, creacion de ordenes) son **idempotentes**: si se reintentan, no duplican el efecto
+  ```
+  // Patron: verificar si la operacion ya se ejecuto antes de procesarla
+  SI existeOperacion(idempotencyKey) ENTONCES retornar resultado_existente
+  SINO ejecutar operacion Y guardar resultado con idempotencyKey
+  ```
+- Si multiples procesos pueden modificar el mismo recurso al mismo tiempo, se usan locks distribuidos o versionado optimista para evitar race conditions
+- Las operaciones de lectura-modificacion-escritura son atomicas (no leer, procesar en memoria y escribir sin proteccion)
+
+## B6. Consultas a BD
+- No hay bucles para traer informacion de distintas fuentes de datos
+- Si se necesitan datos cruzados, crear una funcion que use JOINs o consultas optimizadas internamente
+- Las consultas usan indices apropiados
+- No hay queries N+1
+- No hay inyeccion SQL/NoSQL posible (queries parametrizadas con el ORM/driver del proyecto)
+- Las migraciones (si hay) son reversibles y no rompen datos existentes
+
+## B7. Caching
+- Consultas repetitivas a BD usan cache **distribuido** (no cache local en memoria del proceso — evitar reinicios por falta de RAM)
+- El patron es: verificar cache -> si no hay, consultar BD -> guardar en cache con TTL
+- Las claves de cache son especificas y predecibles (incluyen los parametros que hacen unica la consulta)
+- Se invalida el cache cuando los datos subyacentes cambian (si aplica)
+- El TTL es apropiado para el tipo de dato (configuracion: largo, datos transaccionales: corto o sin cache)
+
+## B8. Resiliencia y conexiones
+- Todas las llamadas externas (HTTP, gRPC, BD, colas) tienen **timeout configurado** (no esperar indefinidamente)
+- Si una dependencia externa falla, la respuesta degrada de forma controlada (fallback, mensaje de error claro, reintento)
+- Connection pooling en BD y clientes HTTP (no abrir/cerrar conexion por cada peticion)
+- Las conexiones se liberan correctamente (en bloques finally o equivalente)
+- Si el proyecto usa circuit breaker, las llamadas a servicios inestables lo implementan
+
+## B9. Colas y mensajeria (si aplica)
+- Los consumers son **idempotentes**: procesar el mismo mensaje dos veces no duplica el efecto
+- Se confirma el procesamiento (ack) **despues** de completar la operacion, no antes
+- Los mensajes que fallan repetidamente van a una dead letter queue (no se pierden ni bloquean la cola)
+- Los producers no pierden mensajes si la cola no esta disponible (retry o persistencia local)
+- Los payloads de mensajes contienen la informacion suficiente para procesarse sin consultas adicionales innecesarias
+
+## B10. Performance
+- Las operaciones pesadas o de larga duracion son asincronas (colas, workers, background jobs)
+- No hay memory leaks obvios (subscriptions sin unsubscribe, listeners sin cleanup, conexiones sin cerrar, timers sin cancelar)
+- Los endpoints con respuesta pesada usan paginacion
+- No se cargan relaciones completas de BD si solo se necesitan campos puntuales (select especifico)
+
+## B11. Logging (estandar Refacil)
+- Se usa el logger centralizado del proyecto (no prints directos a consola), si ya se tiene en el repositorio
+- Procesos criticos en la operacion (ventas, transacciones, pagos) tienen logs
+- Se loggean propiedades especificas y necesarias — nunca objetos complejos ni entidades con relaciones completas
+- Los logs en catch contienen informacion suficiente para diagnosticar el error (que fallo, con que datos, en que contexto)
+- Los logs tienen nivel apropiado: error para fallos, warn para situaciones inesperadas recuperables, info para flujos criticos de negocio
+
+## B12. Testing backend
+- Tests de integracion con BD real para repositorios y queries complejas (no solo mocks)
+- Tests de los contratos de API (request valido retorna estructura esperada, request invalido retorna error formateado)
+- Tests de casos de error (dependencia caida, timeout, datos invalidos)
+- Si hay concurrencia critica: tests que validen idempotencia o atomicidad

package/skills/review/checklist-front.md

@@ -0,0 +1,72 @@
+# Checklist Frontend — Equipo Refacil
+
+> Complementa el [checklist general](checklist.md). Aplica a repositorios **frontend** (aplicaciones web, mobile, desktop con UI).
+> Detectar tipo: si el proyecto tiene estructura de componentes UI, manejo de estado en cliente, rutas/vistas, o consume APIs para renderizar interfaces, aplica este checklist.
+
+## F1. Componentes y estructura
+- Los componentes tienen una sola responsabilidad (no mezclan logica de negocio con presentacion)
+- La logica compleja esta separada en funciones auxiliares, servicios o el patron de reutilizacion del framework
+- Los componentes reutilizables estan en la carpeta compartida del proyecto (consultar AGENTS.md)
+- No hay componentes excesivamente grandes (> 200 lineas como guia — considerar extraer)
+
+## F2. Estado y datos
+- El estado se maneja en el nivel mas cercano a donde se necesita (evitar pasar datos innecesariamente por multiples niveles)
+- No hay estado duplicado o derivable que pueda calcularse
+- Las llamadas a APIs usan el patron establecido en el proyecto (consultar AGENTS.md)
+- Se manejan los 4 estados de cada vista que consume datos: carga, error, vacio y con datos
+
+## F3. Manejo de errores en UI
+- Existe manejo de errores a nivel de componente o seccion (que la app no se caiga entera por un error en un widget)
+- Las pantallas de error muestran feedback visual claro al usuario (nunca pantallas en blanco o rotas)
+- Los errores inesperados se capturan y loggean (si el proyecto tiene servicio de monitoreo)
+- Sin errores ni warnings en consola del navegador en flujos normales
+
+## F4. Integracion con APIs
+- Se manejan los estados de red: reintentos, timeout, desconexion
+- Las peticiones se cancelan al desmontar el componente o navegar fuera (evitar actualizaciones de estado en componentes ya destruidos)
+- Listas largas usan paginacion o scroll infinito con carga incremental
+- Se evitan llamadas duplicadas o innecesarias al mismo endpoint
+
+## F5. Validacion de formularios
+- Los formularios validan entrada del usuario antes de enviar
+- Los mensajes de error son claros y en el idioma del usuario
+- Se previene el doble envio (deshabilitar boton, estado de carga)
+
+## F6. Ruteo y navegacion
+- Las rutas protegidas validan autenticacion/autorizacion antes de renderizar
+- Existe manejo de rutas no encontradas (pantalla 404 o redireccion)
+- Deep linking funciona correctamente (acceder directo a una URL interna)
+- Las redirecciones post-login/logout son correctas
+
+## F7. Consistencia visual
+- Se usan los componentes y tokens del sistema de diseno del proyecto (consultar AGENTS.md)
+- Se respeta la escala de espaciado y tipografia definida
+- No hay estilos inline innecesarios si el proyecto tiene un sistema de estilos definido
+- Iconos e imagenes optimizados (formatos adecuados, tamanos correctos)
+- No hay texto hardcodeado si el proyecto usa internacionalizacion (i18n)
+- La UI es responsive si aplica al proyecto
+
+## F8. Performance frontend
+- No hay re-renderizados innecesarios (usar las tecnicas de memoizacion/optimizacion del framework)
+- Code splitting / carga diferida de rutas o modulos pesados
+- Las imagenes usan carga diferida (lazy loading)
+- Fuentes optimizadas (precarga, fallback definido)
+- No se cargan dependencias pesadas sin necesidad (evaluar tamano del bundle)
+- Sin dependencias duplicadas en el bundle
+- Las listas largas usan virtualizacion si aplica
+
+## F9. Accesibilidad (a11y)
+- Los elementos interactivos tienen etiquetas accesibles (labels, textos alternativos, roles ARIA)
+- La navegacion por teclado funciona correctamente
+- El contraste de colores es adecuado
+- Los targets tactiles tienen tamano minimo adecuado (44x44px como guia)
+
+## F10. Seguridad frontend
+- No hay datos sensibles expuestos en el cliente (tokens, secrets, API keys en codigo fuente)
+- Los inputs estan sanitizados para prevenir XSS
+- No se almacenan tokens o datos sensibles en almacenamiento del cliente sin proteccion adecuada
+
+## F11. Testing frontend
+- Tests de interaccion de usuario (clicks, formularios, navegacion)
+- Tests de los 4 estados visuales (carga, error, vacio, con datos)
+- Los tests verifican comportamiento del usuario, no detalles de implementacion

package/skills/review/checklist.md

@@ -1,77 +1,112 @@
-# Checklist de Calidad — Equipo Refacil
+# Checklist General — Equipo Refacil
 
-> **IMPORTANTE**: Este checklist es generico. Antes de evaluar, lee `AGENTS.md` del proyecto para adaptar cada seccion al stack, arquitectura y convenciones reales del repositorio. Si AGENTS.md indica patrones, frameworks o reglas especificas, usalas en lugar de los ejemplos genericos de abajo.
+> Aplica a **todos** los repositorios (backend, frontend, fullstack), independiente del lenguaje o framework.
+> Antes de evaluar, lee `AGENTS.md` del proyecto para adaptar cada seccion al stack real.
 > Si `AGENTS.md` no existe, aplica este checklist como baseline y marca N/A en reglas que dependan de convenciones no documentadas.
+> **Ademas de este checklist**, carga el checklist especifico del tipo de proyecto:
+> - Backend: [checklist-back.md](checklist-back.md)
+> - Frontend: [checklist-front.md](checklist-front.md)
 
 ## Como usar este checklist (metodologia)
 1. Define alcance de revision: `$ARGUMENTS` > `openspec/changes/` > `git diff`.
-2. Evalua primero bloqueantes: Spec, Testing y Seguridad.
-3. Luego evalua Calidad, Arquitectura, Performance y Mantenibilidad.
+2. Evalua primero bloqueantes: Alcance, Spec, Testing y Seguridad.
+3. Luego evalua Calidad, Arquitectura, Errores, Dependencias y Mantenibilidad.
 4. Marca cada item como PASS, FAIL o N/A con una justificacion breve.
 5. Para cada FAIL, agrega severidad: CRITICO, ALTO, MEDIO o BAJO.
 6. Si hay muchos FAIL, prioriza los 5 de mayor impacto.
 
-## 1. Conformidad con Spec
+## 1. Alcance y foco
+- El cambio hace **una sola cosa** (no mezcla features con refactors, ni correcciones con mejoras no solicitadas)
+- No se implemento funcionalidad fuera del alcance de la spec o del bug reportado
+- Si hay cambios no relacionados, deben estar en un commit o PR separado
+- El tamano del cambio es razonable para revisar (si es demasiado grande, sugerir dividir)
+
+## 2. Conformidad con Spec
 - Todos los criterios de aceptacion de la spec estan cubiertos
-- No se implemento funcionalidad fuera del alcance de la spec
 - Los criterios de rechazo (edge cases) estan manejados
 - El modelo de datos coincide con lo especificado
+- No hay diferencias entre lo que dice la spec y lo que hace el codigo
+
+## 3. Calidad de Codigo
+
+### Tipado (estandar Refacil)
+- No hay uso de tipos genericos sin restriccion (ej. `any`, `object`, `dynamic`) — usar interfaces, tipos concretos o genericos tipados
+- Se definen interfaces/DTOs para el transporte de datos entre capas
 
-## 2. Calidad de Codigo
-- El codigo sigue los patrones existentes del repo (consultar AGENTS.md seccion de arquitectura/convenciones)
+### Validacion de objetos (estandar Refacil)
+- Se valida el objeto Y la propiedad antes de acceder (null-safe access o guard clause)
+- No hay accesos directos a propiedades de objetos que pueden ser nulos o indefinidos
+
+### Naming (estandar Refacil)
+- **Variables**: camelCase — **Clases**: PascalCase — **Archivos**: kebab-case con tipo de componente
+- Nombres autodocumentados: el nombre explica el fin del componente sin necesidad de comentarios
+
+### Limpieza
+- El codigo sigue los patrones existentes del repo (consultar AGENTS.md)
 - No hay codigo duplicado que pueda extraerse
-- Los nombres de variables, funciones y clases son claros y descriptivos
-- No hay `console.log` fuera de bloques `catch` (permitido solo para diagnostico de errores), TODO, o codigo comentado sin razon
-- Los imports usan los alias configurados del proyecto (consultar AGENTS.md seccion de alias de rutas, si aplica)
+- Se prefieren variables inmutables (evitar mutaciones innecesarias)
+- No hay prints/logs de debug sueltos, TODO sin ticket asociado, o codigo comentado sin razon
+- Se usan enums y constantes para valores fijos — valores configurables van en archivos de configuracion, no hardcodeados
+- Los imports usan los alias del proyecto (si aplica)
 - No hay dependencias circulares nuevas
 
-## 3. Arquitectura
+## 4. Arquitectura
+- **SRP**: cada clase/funcion tiene una sola responsabilidad
+- **KISS**: la solucion es tan simple como sea posible — no hay sobreingenieria ni abstracciones prematuras
+- La logica esta separada en unidades con un solo fin, reutilizables
+- No se envian mas de 4 parametros a un metodo — si se necesitan mas, encapsular en un objeto/DTO
 - Se respetan los limites y capas definidos en AGENTS.md
-- Las dependencias fluyen en la direccion correcta segun la arquitectura del proyecto
-- No hay logica de negocio en la capa de infraestructura o transporte
-- Las interfaces/puertos estan en la capa correcta segun las convenciones del repo
-- Los DTOs estan en la capa correcta
+- No se introduce acoplamiento innecesario entre modulos o servicios
+
+> La arquitectura varia por proyecto. Consultar AGENTS.md para saber cual aplica.
 
-> **Nota**: La arquitectura varia por proyecto (DDD, MVC, Clean Architecture, Hexagonal, etc.). Consultar AGENTS.md para saber cual aplica y evaluar en consecuencia.
+## 5. Manejo de errores
+- Los errores se manejan de forma consistente con el resto del proyecto
+- Los mensajes de error son utiles para diagnosticar (que fallo, en que contexto)
+- No se exponen detalles internos al usuario/consumidor (stack traces, rutas internas, IDs de BD)
+- Los errores esperados (validacion, negocio) se distinguen de los inesperados (sistema, infraestructura)
+- No hay errores silenciados (catch vacio sin log ni manejo)
 
-## 4. Testing
+## 6. Testing
 - Cada archivo nuevo/modificado tiene su archivo de test correspondiente
 - Los tests cubren los criterios de aceptacion de la spec
 - Hay tests para edge cases y escenarios de error
-- Los mocks son minimos y necesarios
-- Los tests son independientes entre si
+- Los tests validan **comportamiento**, no detalles de implementacion (no se rompen al refactorizar)
+- Los mocks son minimos y necesarios — no se mockea lo que se puede probar directamente
+- Los tests son independientes entre si (no dependen de orden de ejecucion ni de estado compartido)
 - Coverage >= 80% en archivos nuevos
 - Los tests pasan sin errores (ejecutar el comando de test indicado en AGENTS.md)
 
-## 5. Seguridad
-- No hay secrets hardcodeados (passwords, API keys, tokens)
-- Los inputs del usuario estan validados (usar la libreria de validacion del proyecto)
-- No hay inyeccion SQL posible (queries parametrizadas con el ORM del proyecto)
-- Los endpoints sensibles tienen autorizacion adecuada
-- No se expone informacion sensible en logs o respuestas de error
+## 7. Seguridad
+- No hay secrets hardcodeados (passwords, API keys, tokens, URLs internas de servicios)
+- Los inputs del usuario estan validados antes de procesarse
+- Los endpoints o rutas sensibles tienen autorizacion adecuada
+- No se expone informacion sensible en logs, respuestas de error o codigo fuente del cliente
+- No hay dependencias con vulnerabilidades conocidas criticas (verificar si el proyecto tiene audit configurado)
 
-## 6. Performance
-- Las consultas a base de datos usan indices apropiados
-- No hay queries N+1
-- Las operaciones pesadas son asincronas donde corresponde
-- No hay memory leaks obvios (subscriptions sin unsubscribe, listeners sin cleanup, etc.)
+## 8. Dependencias
+- Las dependencias nuevas estan justificadas (no se agrega una libreria para algo que se puede hacer en pocas lineas)
+- La licencia es compatible con el proyecto
+- La dependencia esta activamente mantenida (no abandonada)
+- No duplica funcionalidad que ya existe en el proyecto o en otra dependencia instalada
+- La version esta fijada o usa rango seguro (no `*` ni `latest`)
 
-## 7. Mantenibilidad
+## 9. Mantenibilidad y observabilidad
 - El codigo es autoexplicativo (comentarios solo donde la logica no es obvia)
-- Las funciones hacen una sola cosa
 - Los archivos no son excesivamente largos (< 400 lineas como guia)
-- El manejo de errores es consistente con el resto del proyecto
+- Si algo falla en produccion, hay suficiente informacion para diagnosticar (logs, trazas, contexto en errores)
+- Los cambios en configuracion estan documentados (variables de entorno nuevas, flags, parametros)
 
-## 8. Git y Deploy
+## 10. Git y Deploy
 - Los commits son atomicos y tienen mensajes descriptivos
-- No hay archivos generados o temporales en el commit
-- Las migraciones de BD (si hay) son reversibles
+- No hay archivos generados, temporales o sensibles en el commit (verificar .gitignore)
 - No hay breaking changes no documentados
+- Si hay migraciones, son reversibles y no rompen datos existentes
 
-## 9. Reglas especificas del proyecto
+## 11. Reglas especificas del proyecto
 - Consultar la seccion "Reglas criticas" de AGENTS.md
 - Evaluar contra las reglas de "Siempre hacer", "Nunca hacer" y "Preguntar primero"
-- Si AGENTS.md define reglas adicionales (ej: zona horaria, formato de fechas, naming conventions), verificar su cumplimiento
+- Si AGENTS.md define reglas adicionales, verificar su cumplimiento
 
 ## Criterio de salida del review
 - **APROBADO**: No hay FAILs CRITICOS/ALTOS.