refacil-sdd-ai 4.2.4 → 4.3.0

package/skills/reply/SKILL.md

@@ -1,44 +1,44 @@
----
-name: refacil:reply
-description: Responder la última pregunta dirigida a esta sesión en el bus. El broker autocompleta el correlationId.
-user-invocable: true
----
-
-# refacil:reply — Responder una pregunta del bus
-
-Envía una respuesta a la última pregunta dirigida a esta sesión. **$ARGUMENTS** = texto de la respuesta.
-
-## Instrucciones
-
-### Paso 1: Ejecutar reply
-
-Ejecuta vía `Bash`:
-
-```bash
-refacil-sdd-ai bus reply --text "<respuesta>"
-```
-
-El broker:
-- Busca automáticamente el último `ask` dirigido a esta sesión en la sala
-- Usa su `correlationId` para que el que preguntó (si está en `ask --wait`) reciba la respuesta directo
-- Broadcast a toda la sala como mensaje `kind=reply`
-
-### Paso 2: Confirmar
-
-Reporta al usuario que la respuesta se envió.
-
-## Cuándo usar `reply` vs `say`
-
-- **`reply`**: siempre que estés respondiendo algo que te preguntaron. Esto permite que el otro lado en `ask --wait` desbloquee automáticamente.
-- **`say`**: anuncio general sin relación con una pregunta previa.
-
-## Reglas
-
-- Si acabas de **implementar** un cambio pedido por otro agente y este `reply` es el **cierre** (hecho / PR / bloqueo), incluye ese resumen en el texto; es el canal por defecto para contestar a quien hizo el `ask` original (mismo hilo).
-- Entrecomilla correctamente el texto.
-- Responde solo desde tu conocimiento de ESTE repo. Si la pregunta cae fuera de tu scope, dilo explícitamente: `"fuera de mi alcance, esto lo sabe el repo X"`.
-- Si no hay pregunta pendiente dirigida a ti y no quieres engancharla, usa `/refacil:say` en su lugar.
-- Si te hicieron múltiples preguntas y quieres responder una específica más vieja, pasa `--correlation <id>` explícito:
-  ```bash
-  refacil-sdd-ai bus reply --text "..." --correlation <id>
-  ```
+---
+name: refacil:reply
+description: Reply to the last question directed to this session on the bus. The broker autocompletes the correlationId.
+user-invocable: true
+---
+
+# refacil:reply — Reply to a bus question
+
+Sends a response to the last question directed to this session. **$ARGUMENTS** = response text.
+
+## Instructions
+
+### Step 1: Execute reply
+
+Run via `Bash`:
+
+```bash
+refacil-sdd-ai bus reply --text "<response>"
+```
+
+The broker:
+- Automatically finds the last `ask` directed to this session in the room
+- Uses its `correlationId` so the asker (if in `ask --wait`) receives the response directly
+- Broadcasts to the entire room as a `kind=reply` message
+
+### Step 2: Confirm
+
+Report to the user that the response was sent.
+
+## When to use `reply` vs `say`
+
+- **`reply`**: always when you are responding to something you were asked. This allows the other side in `ask --wait` to unblock automatically.
+- **`say`**: general announcement unrelated to a previous question.
+
+## Rules
+
+- If you just **implemented** a change requested by another agent and this `reply` is the **close** (done / PR / blocked), include that summary in the text; it is the default channel to respond to whoever made the original `ask` (same thread).
+- Correctly quote the text.
+- Respond only from your knowledge of THIS repo. If the question falls outside your scope, say it explicitly: `"out of my scope, repo X knows about this"`.
+- If there is no pending question directed to you and you do not want to link it, use `/refacil:say` instead.
+- If you were asked multiple questions and want to respond to a specific older one, pass `--correlation <id>` explicitly:
+  ```bash
+  refacil-sdd-ai bus reply --text "..." --correlation <id>
+  ```

package/skills/review/SKILL.md

@@ -1,126 +1,135 @@
----
-name: refacil:review
-description: Review de codigo con el checklist de calidad del equipo — construye un briefing con archivos cambiados y tipo de proyecto, delega al sub-agente refacil-auditor y procesa el veredicto
-user-invocable: true
----
-
-# refacil:review — Entrypoint del Review
-
-Este skill es un **wrapper delgado** que delega el review pesado al sub-agente `refacil-auditor`. Antes de delegar, construye un **briefing estructurado** con los archivos cambiados y el tipo de proyecto ya detectados — el sub-agente arranca evaluando, no descubriendo.
-
-**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
-
-## Flujo
-
-### Paso 0: Resolver alcance
-
-- Determina el alcance del review ANTES de invocar al sub-agente. Prioriza este orden:
-  1) Argumento del usuario (`$ARGUMENTS`)
-  2) Cambio activo en `openspec/changes/`
-  3) Cambios no commiteados (`git diff`)
-- Si hay multiples cambios activos en `openspec/changes/` y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio revisar. **No invoques al sub-agente con scope ambiguo.**
-
-**Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review (existencia del marcador: **`METHODOLOGY-CONTRACT.md` §8**):
-1. Lee la `date` del `.review-passed`.
-2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain`.
-3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y continua (construye briefing e invoca al sub-agente).
-4. **Si NO hay cambios nuevos**: informa al usuario y termina sin invocar al sub-agente:
-   ```
-   El cambio [nombre] ya tiene review aprobado ([verdict] — [date]) y no hay cambios posteriores.
-   ```
-
-### Paso 0.5: Construir briefing para el sub-agente (reduce tool calls del auditor)
-
-Antes de invocar al sub-agente, extrae el contexto que de otro modo el auditor calcularía por su cuenta:
-
-1. **Archivos cambiados** — ejecuta `git diff --name-only HEAD` y `git status --porcelain`. La union es el scope bloqueante. (Si ya lo corriste en Paso 0 para verificar cambios post-review, reutiliza ese resultado.)
-
-2. **Tipo de proyecto** — lee `package.json` (si existe) e inspecciona las dependencias:
-   - Indicadores backend: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
-   - Indicadores frontend: `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `vite`, `@tanstack/*`
-   - Si ambos → `fullstack`; si solo backend → `backend`; si solo frontend → `frontend`; si no hay `package.json` o ninguno aplica → lee las primeras 20 lineas de `AGENTS.md` para inferir.
-
-3. **Objetivo del cambio** (solo si hay cambio activo en `openspec/changes/`) — lee la primera seccion de `proposal.md`. Extrae el objetivo en 1-2 oraciones. Si el scope es `git-diff` sin cambio activo → `null`.
-
-Construye el bloque BRIEFING:
-
-```
-BRIEFING:
-scope: <changeName | "git-diff">
-changedFiles: [ruta/archivo-1.ts, ruta/archivo-2.ts, ...]
-projectType: backend | frontend | fullstack | library
-changeObjective: <objetivo en 1-2 oraciones, o null>
-mode: conciso | detailed
-```
-
-### Paso 1: Delegar al sub-agente refacil-auditor
-
-Invoca al sub-agente `refacil-auditor` pasandole el BRIEFING del paso anterior.
-
-El sub-agente:
-- Usa `changedFiles` del briefing como scope bloqueante (sin re-correr git diff).
-- Usa `projectType` para cargar directamente los checklists correctos (sin detection phase).
-- Usa `changeObjective` como contexto de intencion (sin releer proposal.md).
-- Lee los checklists y los archivos del scope bloqueante.
-- Evalua cada item con PASS/FAIL/N/A + severidad en cada FAIL.
-- Retorna UN solo mensaje con el reporte + bloque JSON fenced como ` ```refacil-review-result `.
-
-### Paso 2: Procesar el reporte del sub-agente
-
-Muestra al usuario el **reporte conciso** (todo lo anterior al bloque `refacil-review-result`). No muestres el bloque JSON — es metadata interna.
-
-**Si el sub-agente retorno `SCOPE_ERROR: <razon>`**: propaga el error al usuario y pide clarificacion. No escribas marker.
-
-### Paso 3: Crear marcador `.review-passed` (si aplica)
-
-Parsea el bloque ` ```refacil-review-result ` del sub-agente. Si `verdict` es **APROBADO** o **APROBADO CON OBSERVACIONES** y `changeName` no es null:
-
-**Ruta:** `openspec/changes/<changeName>/.review-passed`
-
-**Contenido (el JSON parseado del bloque, verbatim):**
-```json
-{
-  "verdict": "APROBADO|APROBADO CON OBSERVACIONES",
-  "date": "<ISO>",
-  "changeName": "<nombre-cambio>",
-  "summary": "<resumen 1 linea>",
-  "failCount": <int — solo FAILs en codigo nuevo>,
-  "preexistingCount": <int — FAILs preexistentes, no bloqueantes>,
-  "blockers": false
-}
-```
-
-**No crees el marker si:**
-- `verdict` es `REQUIERE CORRECCIONES`.
-- `changeName` es null.
-- El sub-agente retorno `SCOPE_ERROR`.
-
-### Paso 4: Recomendar siguiente paso
-
-Segun el `verdict` parseado, agrega al final de tu respuesta:
-
-**Si APROBADO o APROBADO CON OBSERVACIONES:**
-```
-El siguiente paso es archivar el cambio.
-Quieres que continue con /refacil:archive?
-```
-
-**Si REQUIERE CORRECCIONES:**
-```
-Una vez aplicadas las correcciones, el siguiente paso es re-verificar la implementacion.
-Quieres que continue con /refacil:verify?
-```
-
-## Reglas
-
-- **Siempre construye el briefing (Paso 0.5) antes de delegar** — es la pieza clave que reduce el costo del sub-agente.
-- **Siempre delega al sub-agente**. No repliques la logica de checklists ni de evaluacion aqui.
-- **El marker lo crea este skill, no el sub-agente**.
-- **No muestres el bloque JSON al usuario**.
-- Si el sub-agente retorno algo fuera de formato (sin bloque JSON parseable y no es `SCOPE_ERROR`), informa al usuario: "El reviewer retorno un reporte no estructurado — no se creo marker. Revisa el reporte manualmente."
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad, invocar inmediatamente el **Skill tool** correspondiente: `skill: "refacil:archive"` si el veredicto es APROBADO/APROBADO CON OBSERVACIONES, o `skill: "refacil:verify"` si es REQUIERE CORRECCIONES. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-auditor.md` (fuente: `refacil-sdd-ai/agents/auditor.md`)
-- Checklists: `checklist.md`, `checklist-back.md`, `checklist-front.md` en este mismo directorio.
+---
+name: refacil:review
+description: Code review with the team quality checklist — builds a briefing with changed files and project type, delegates to the refacil-auditor sub-agent, and processes the verdict
+user-invocable: true
+---
+
+# refacil:review — Review Entrypoint
+
+This skill is a **thin wrapper** that delegates the heavy review to the `refacil-auditor` sub-agent. Before delegating, it builds a **structured briefing** with the changed files and detected project type — the sub-agent starts evaluating, not discovering.
+
+**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + output mode from `METHODOLOGY-CONTRACT.md`.
+
+## Flow
+
+### Step 0: Resolve scope
+
+- Determine the review scope BEFORE invoking the sub-agent. Prioritize in this order:
+  1) User argument (`$ARGUMENTS`)
+  2) Active change in `refacil-sdd/changes/`
+  3) Uncommitted changes (`git diff`)
+- If there are multiple active changes in `refacil-sdd/changes/` and no `$ARGUMENTS`, **stop** and ask the user to explicitly select which change to review. **Do not invoke the sub-agent with ambiguous scope.**
+
+### Step 0.3: Git working tree snapshot (run once)
+
+After scope is unambiguous (you are **not** stopping for multiple active changes), collect git state **exactly once** for this skill invocation:
+
+1. Run `git diff --name-only HEAD` → set `pathsFromDiff`.
+2. Run `git status --porcelain` → parse each line (strip the first two status columns) → set `pathsFromStatus`.
+3. **`changedFilesUnion`** = sorted unique union of `pathsFromDiff` and `pathsFromStatus` (drop empty entries).
+
+**Rules:**
+- Reuse **`changedFilesUnion`** and the **same** `git status --porcelain` interpretation everywhere below — **do not** run `git diff --name-only` or `git status --porcelain` again in this skill.
+- If a later step needs “is the working tree non-empty?”, derive it from the snapshot (e.g. non-empty `changedFilesUnion` or any porcelain line) instead of re-running `git status`.
+
+If you already have a `changeName`, run `refacil-sdd-ai sdd status <changeName> --json` to get the change status (artifacts, tasks, reviewPassed).
+
+**Review already approved**: If `reviewPassed` is `true` in the status JSON (or if the target change already has `.review-passed`), verify if there are changes after the review (marker existence: **`METHODOLOGY-CONTRACT.md` §8**):
+1. Read the `date` from `.review-passed`.
+2. Compare with `git log --since="[date]" --oneline` and **reuse the Step 0.3 snapshot** for working-tree activity (do not run `git status` again).
+3. **If there are new changes** (commits since marker date and/or paths in `changedFilesUnion`): delete the previous `.review-passed` and continue (build briefing and invoke the sub-agent).
+4. **If there are NO new changes**: inform the user and finish without invoking the sub-agent:
+   ```
+   The change [name] already has an approved review ([verdict] — [date]) and there are no subsequent changes.
+   ```
+
+### Step 0.5: Build briefing for the sub-agent (reduces auditor tool calls)
+
+Before invoking the sub-agent, extract the context that the auditor would otherwise calculate on its own:
+
+1. **Changed files** — use **`changedFilesUnion` from Step 0.3** as the blocking scope. Do not run `git diff` or `git status` again.
+
+2. **Project type** — read `package.json` (if it exists) and inspect the dependencies:
+   - Backend indicators: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
+   - Frontend indicators: `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `vite`, `@tanstack/*`
+   - If both → `fullstack`; if only backend → `backend`; if only frontend → `frontend`; if no `package.json` or none applies → read the first 20 lines of `AGENTS.md` to infer.
+
+3. **Change objective** (only if there is an active change in `refacil-sdd/changes/`) — read the first section of `proposal.md`. Extract the objective in 1-2 sentences. If the scope is `git-diff` without an active change → `null`.
+
+Build the BRIEFING block:
+
+```
+BRIEFING:
+scope: <changeName | "git-diff">
+changedFiles: [path/file-1.ts, path/file-2.ts, ...]
+projectType: backend | frontend | fullstack | library
+changeObjective: <objective in 1-2 sentences, or null>
+mode: concise | detailed
+```
+
+### Step 1: Delegate to the refacil-auditor sub-agent
+
+Invoke the `refacil-auditor` sub-agent passing it the BRIEFING from the previous step.
+
+The sub-agent:
+- Uses `changedFiles` from the briefing as the blocking scope (without re-running git diff).
+- Uses `projectType` to directly load the correct checklists (without a detection phase).
+- Uses `changeObjective` as intent context (without re-reading proposal.md).
+- Reads the checklists and the blocking scope files.
+- Evaluates each item with PASS/FAIL/N/A + severity for each FAIL.
+- Returns ONE single message with the report + JSON block fenced as ` ```refacil-review-result `.
+
+### Step 2: Process the sub-agent report
+
+Show the user the **concise report** (everything before the `refacil-review-result` block). Do not show the JSON block — it is internal metadata.
+
+**If the sub-agent returned `SCOPE_ERROR: <reason>`**: propagate the error to the user and ask for clarification. Do not write a marker.
+
+### Step 3: Create `.review-passed` marker (if applicable)
+
+Parse the ` ```refacil-review-result ` block from the sub-agent. If `verdict` is **APROBADO** or **APROBADO CON OBSERVACIONES** and `changeName` is not null:
+
+Run the following command to write the marker:
+
+```bash
+refacil-sdd-ai sdd mark-reviewed <changeName> \
+  --verdict "<verdict>" \
+  --summary "<1-line summary>" \
+  --fail-count <failCount> \
+  --preexisting-count <preexistingCount>
+```
+
+Where the values are extracted from the sub-agent's `refacil-review-result` block:
+- `<verdict>`: the value of `verdict` (APROBADO, APROBADO CON OBSERVACIONES, etc.)
+- `<summary>`: the value of `summary`
+- `<failCount>`: FAILs in new code (default 0)
+- `<preexistingCount>`: pre-existing non-blocking FAILs (default 0)
+
+**Do NOT run the command if:**
+- `verdict` is `REQUIERE CORRECCIONES`.
+- `changeName` is null.
+- The sub-agent returned `SCOPE_ERROR`.
+
+### Step 4: Recommend next step
+
+According to the parsed `verdict`, add at the end of your response:
+
+**If APROBADO or APROBADO CON OBSERVACIONES:**
+```
+The next step is to archive the change.
+Do you want me to continue with /refacil:archive?
+```
+
+**If REQUIERE CORRECCIONES:**
+```
+Once the corrections are applied, the next step is to re-verify the implementation.
+Do you want me to continue with /refacil:verify?
+```
+
+## Rules
+
+- **Always build the briefing (Step 0.5) before delegating** — it is the key piece that reduces the sub-agent cost.
+- **Always delegate to the sub-agent**. Do not replicate checklist or evaluation logic here.
+- **The marker is created by this skill, not the sub-agent**.
+- If the sub-agent returned something out of format (no parseable JSON block and not `SCOPE_ERROR`), inform the user: "The reviewer returned an unstructured report — no marker was created. Review the report manually."
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question, immediately invoke the corresponding **Skill tool**: `skill: "refacil:archive"` if the verdict is APROBADO/APROBADO CON OBSERVACIONES, or `skill: "refacil:verify"` if REQUIERE CORRECCIONES. (See `METHODOLOGY-CONTRACT.md §5`.)

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