refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/review/checklist-back.md

@@ -1,92 +1,92 @@
-# 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)
-- **Esquema (DDL)**: por defecto, no usar el sistema de migraciones de TypeORM ni `synchronize` para aplicar o versionar cambios de BD (ni `MigrationInterface`, ni depender de `migration:run` / `migration:generate` en el flujo de despliegue de la app). Los cambios de esquema se entregan como **scripts explícitos** (p. ej. `.sql` versionados bajo convención del repo) para que **quien opera el motor** los ejecute **manualmente y aparte** en cada entorno (Postgres, MySQL, etc.). **Excepción**: si `AGENTS.md` define **explicitamente** como regla de **ese** repositorio otro mecanismo (p. ej. migraciones TypeORM u otro pipeline acordado), marca esta viñeta como **N/A** y revisa solo que el cambio cumple lo documentado allí (sin exigir scripts manuales).
-- Si aplica la politica por defecto (scripts manuales): los scripts de esquema entregados documentan orden de ejecución, son reversibles o describen rollback, y no destruyen datos existentes sin plan explícito. Si aplica la excepción por `AGENTS.md`, marca **N/A** o evalua segun lo que ese archivo exija para migraciones.
-
-## 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
+# Backend Checklist — Refacil Team
+
+> Complements the [general checklist](checklist.md). Applies to **backend** repositories (APIs, microservices, workers, queues).
+> Detection: if the project has server frameworks (HTTP, gRPC, messaging), microservice structure, or database access, apply this checklist.
+> Mark N/A in sections that do not apply to the change being reviewed (e.g. queues if the change does not touch messaging).
+
+## B1. Input validation
+- Endpoint DTOs/input objects use the framework's automatic validation mechanism
+- Each field declares its type and constraints (required, format, range)
+- Endpoints named in kebab-case (`get-user-info`, `create-payment`)
+- Client data is not trusted without validation (query params, headers, body)
+
+## B2. API contracts
+- Responses use a consistent structure (do not return different formats depending on the case)
+- HTTP codes are correct and specific (not everything is 200 or 500)
+- Response DTOs do not expose internal fields (DB IDs, audit fields, internal relationships)
+- If the endpoint is consumed by another service: verify that no breaking changes are introduced in the contract (renamed, removed, or differently-typed fields)
+- Errors return a standard format with a message understandable to the consumer
+
+## B3. Error handling (Refacil standard)
+- No nested or multiple try/catch blocks in the same request thread
+- Errors are captured, logged, and formatted responses are returned
+- New modules/services use the project's global exception filter or middleware (if it exists)
+- Client errors (4xx) are distinguished from server errors (5xx)
+- External dependency errors (APIs, DB, queues) are handled with their own messages, not propagated as-is to the consumer
+
+## B4. Architecture and patterns
+- **Layer responsibility**: no business logic in the transport layer (controllers/handlers) or in the infrastructure layer (repositories/adapters)
+- DTOs are in the correct layer (input in transport, output in application)
+- Repository Pattern for data access (if the project has a base repository, new ones extend it)
+- If it is a new microservice, follows the structure defined in AGENTS.md (hexagonal, clean architecture, etc.)
+- Dependencies flow in the correct direction according to the project architecture
+
+## B5. Concurrency and atomicity
+- Operations that modify multiple records or tables use DB transactions (all or nothing)
+- Critical write endpoints (payments, transfers, order creation) are **idempotent**: if retried, they do not duplicate the effect
+  ```
+  // Pattern: check if the operation was already executed before processing it
+  IF operationExists(idempotencyKey) THEN return existing_result
+  ELSE execute operation AND save result with idempotencyKey
+  ```
+- If multiple processes can modify the same resource simultaneously, distributed locks or optimistic versioning are used to avoid race conditions
+- Read-modify-write operations are atomic (not read, process in memory and write without protection)
+
+## B6. DB queries
+- No loops to fetch information from different data sources
+- If cross-data is needed, create a function that uses JOINs or internally optimized queries
+- Queries use appropriate indexes
+- No N+1 queries
+- No SQL/NoSQL injection possible (parameterized queries with the project's ORM/driver)
+- **Schema (DDL)**: by default, do not use TypeORM's migration system or `synchronize` to apply or version DB changes (neither `MigrationInterface`, nor relying on `migration:run` / `migration:generate` in the app deployment flow). Schema changes are delivered as **explicit scripts** (e.g. versioned `.sql` files under the repo convention) so **whoever operates the engine** executes them **manually and separately** in each environment (Postgres, MySQL, etc.). **Exception**: if `AGENTS.md` **explicitly** defines another mechanism as a rule for **that** repository (e.g. TypeORM migrations or another agreed pipeline), mark this bullet as **N/A** and only verify the change complies with what is documented there (without requiring manual scripts).
+- If the default policy applies (manual scripts): the delivered schema scripts document execution order, are reversible or describe rollback, and do not destroy existing data without an explicit plan. If the exception applies via `AGENTS.md`, mark **N/A** or evaluate according to what that file requires for migrations.
+
+## B7. Caching
+- Repetitive DB queries use **distributed** cache (not in-process memory cache — avoid restarts due to RAM exhaustion)
+- The pattern is: check cache -> if not found, query DB -> save to cache with TTL
+- Cache keys are specific and predictable (include the parameters that make the query unique)
+- Cache is invalidated when underlying data changes (if applicable)
+- TTL is appropriate for the data type (configuration: long, transactional data: short or no cache)
+
+## B8. Resilience and connections
+- All external calls (HTTP, gRPC, DB, queues) have **configured timeout** (do not wait indefinitely)
+- If an external dependency fails, the response degrades gracefully (fallback, clear error message, retry)
+- Connection pooling in DB and HTTP clients (do not open/close a connection per request)
+- Connections are properly released (in finally blocks or equivalent)
+- If the project uses circuit breaker, calls to unstable services implement it
+
+## B9. Queues and messaging (if applicable)
+- Consumers are **idempotent**: processing the same message twice does not duplicate the effect
+- Processing is acknowledged (ack) **after** completing the operation, not before
+- Messages that fail repeatedly go to a dead letter queue (they are not lost or stuck in the queue)
+- Producers do not lose messages if the queue is unavailable (retry or local persistence)
+- Message payloads contain enough information to be processed without unnecessary additional queries
+
+## B10. Performance
+- Heavy or long-running operations are asynchronous (queues, workers, background jobs)
+- No obvious memory leaks (subscriptions without unsubscribe, listeners without cleanup, unclosed connections, uncanceled timers)
+- Endpoints with heavy responses use pagination
+- Complete DB relationships are not loaded if only specific fields are needed (specific select)
+
+## B11. Logging (Refacil standard)
+- The project's centralized logger is used (not direct console prints), if already present in the repository
+- Critical business operations (sales, transactions, payments) have logs
+- Specific and necessary properties are logged — never complex objects or entities with full relationships
+- Catch logs contain enough information to diagnose the error (what failed, with what data, in what context)
+- Logs have appropriate level: error for failures, warn for recoverable unexpected situations, info for critical business flows
+
+## B12. Backend testing
+- Integration tests with a real DB for repositories and complex queries (not just mocks)
+- API contract tests (valid request returns expected structure, invalid request returns formatted error)
+- Error case tests (dependency down, timeout, invalid data)
+- If there is critical concurrency: tests that validate idempotency or atomicity

package/skills/review/checklist-front.md

@@ -1,72 +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
+# Frontend Checklist — Refacil Team
+
+> Complements the [general checklist](checklist.md). Applies to **frontend** repositories (web, mobile, desktop applications with UI).
+> Detection: if the project has UI component structure, client-side state management, routes/views, or consumes APIs to render interfaces, apply this checklist.
+
+## F1. Components and structure
+- Components have a single responsibility (do not mix business logic with presentation)
+- Complex logic is separated into helper functions, services, or the framework's reuse pattern
+- Reusable components are in the project's shared folder (consult AGENTS.md)
+- No excessively large components (> 200 lines as a guideline — consider extracting)
+
+## F2. State and data
+- State is managed at the closest level to where it is needed (avoid passing data unnecessarily through multiple levels)
+- No duplicated or derivable state that can be calculated
+- API calls use the pattern established in the project (consult AGENTS.md)
+- All 4 states of each data-consuming view are handled: loading, error, empty, and with data
+
+## F3. Error handling in UI
+- Error handling exists at the component or section level (so the entire app does not crash due to a widget error)
+- Error screens show clear visual feedback to the user (never blank or broken screens)
+- Unexpected errors are captured and logged (if the project has a monitoring service)
+- No errors or warnings in the browser console during normal flows
+
+## F4. API integration
+- Network states are handled: retries, timeout, disconnection
+- Requests are cancelled when unmounting the component or navigating away (avoid state updates in already-destroyed components)
+- Long lists use pagination or infinite scroll with incremental loading
+- Duplicate or unnecessary calls to the same endpoint are avoided
+
+## F5. Form validation
+- Forms validate user input before submitting
+- Error messages are clear and in the user's language
+- Double submission is prevented (disable button, loading state)
+
+## F6. Routing and navigation
+- Protected routes validate authentication/authorization before rendering
+- Handling of not-found routes exists (404 screen or redirect)
+- Deep linking works correctly (accessing an internal URL directly)
+- Post-login/logout redirects are correct
+
+## F7. Visual consistency
+- The project's design system components and tokens are used (consult AGENTS.md)
+- The defined spacing and typography scale is respected
+- No unnecessary inline styles if the project has a defined style system
+- Icons and images are optimized (appropriate formats, correct sizes)
+- No hardcoded text if the project uses internationalization (i18n)
+- The UI is responsive if applicable to the project
+
+## F8. Frontend performance
+- No unnecessary re-renders (use the framework's memoization/optimization techniques)
+- Code splitting / lazy loading of heavy routes or modules
+- Images use lazy loading
+- Optimized fonts (preload, fallback defined)
+- No heavy dependencies loaded unnecessarily (evaluate bundle size)
+- No duplicate dependencies in the bundle
+- Long lists use virtualization if applicable
+
+## F9. Accessibility (a11y)
+- Interactive elements have accessible labels (labels, alternative texts, ARIA roles)
+- Keyboard navigation works correctly
+- Color contrast is adequate
+- Touch targets have an adequate minimum size (44x44px as a guideline)
+
+## F10. Frontend security
+- No sensitive data exposed on the client (tokens, secrets, API keys in source code)
+- Inputs are sanitized to prevent XSS
+- Tokens or sensitive data are not stored in client storage without adequate protection
+
+## F11. Frontend testing
+- User interaction tests (clicks, forms, navigation)
+- Tests for all 4 visual states (loading, error, empty, with data)
+- Tests verify user behavior, not implementation details