refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/review/checklist.md

@@ -1,114 +1,114 @@
-# Checklist General — Equipo Refacil
-
-> 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: 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. 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
-- 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
-
-### 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
-- 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
-
-## 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
-- No se introduce acoplamiento innecesario entre modulos o servicios
-
-> La arquitectura varia por proyecto. Consultar AGENTS.md para saber cual aplica.
-
-## 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)
-
-## 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 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)
-
-## 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)
-
-## 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`)
-
-## 9. Mantenibilidad y observabilidad
-- El codigo es autoexplicativo (comentarios solo donde la logica no es obvia)
-- Los archivos no son excesivamente largos (< 400 lineas como guia)
-- 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)
-
-## 10. Git y Deploy
-- Los commits son atomicos y tienen mensajes descriptivos
-- 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
-
-## 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, verificar su cumplimiento
-
-## Criterio de salida del review
-- **APROBADO**: No hay FAILs CRITICOS/ALTOS.
-- **APROBADO CON OBSERVACIONES**: Solo FAILs MEDIOS/BAJOS.
-- **REQUIERE CORRECCIONES**: Existe al menos un FAIL CRITICO/ALTO.
+# General Checklist — Refacil Team
+
+> Applies to **all** repositories (backend, frontend, fullstack), regardless of language or framework.
+> Before evaluating, read the project's `AGENTS.md` to adapt each section to the actual stack.
+> If `AGENTS.md` does not exist, apply this checklist as a baseline and mark N/A for rules that depend on undocumented conventions.
+> **In addition to this checklist**, load the project-type specific checklist:
+> - Backend: [checklist-back.md](checklist-back.md)
+> - Frontend: [checklist-front.md](checklist-front.md)
+
+## How to use this checklist (methodology)
+1. Define review scope: `$ARGUMENTS` > `refacil-sdd/changes/` > `git diff`.
+2. Evaluate blockers first: Scope, Spec, Testing, and Security.
+3. Then evaluate Quality, Architecture, Errors, Dependencies, and Maintainability.
+4. Mark each item as PASS, FAIL, or N/A with a brief justification.
+5. For each FAIL, add severity: CRITICAL, HIGH, MEDIUM, or LOW.
+6. If there are many FAILs, prioritize the 5 with the highest impact.
+
+## 1. Scope and focus
+- The change does **one single thing** (does not mix features with refactors, or fixes with unsolicited improvements)
+- No functionality was implemented outside the scope of the spec or the reported bug
+- If there are unrelated changes, they must be in a separate commit or PR
+- The change size is reasonable to review (if too large, suggest dividing)
+
+## 2. Spec compliance
+- All acceptance criteria from the spec are covered
+- Rejection criteria (edge cases) are handled
+- The data model matches what was specified
+- There are no differences between what the spec says and what the code does
+
+## 3. Code quality
+
+### Typing (Refacil standard)
+- No use of unconstrained generic types (e.g. `any`, `object`, `dynamic`) — use interfaces, concrete types, or typed generics
+- Interfaces/DTOs are defined for data transport between layers
+
+### Object validation (Refacil standard)
+- Both the object AND the property are validated before accessing (null-safe access or guard clause)
+- No direct property access on objects that may be null or undefined
+
+### Naming (Refacil standard)
+- **Variables**: camelCase — **Classes**: PascalCase — **Files**: kebab-case with component type
+- Self-documenting names: the name explains the component's purpose without needing comments
+
+### Cleanliness
+- The code follows existing repo patterns (check AGENTS.md)
+- No duplicated code that could be extracted
+- Immutable variables are preferred (avoid unnecessary mutations)
+- No loose debug prints/logs, TODOs without an associated ticket, or commented-out code without reason
+- Enums and constants are used for fixed values — configurable values go in configuration files, not hardcoded
+- Imports use project aliases (if applicable)
+- No new circular dependencies
+
+## 4. Architecture
+- **SRP**: each class/function has a single responsibility
+- **KISS**: the solution is as simple as possible — no over-engineering or premature abstractions
+- Logic is separated into single-purpose, reusable units
+- No more than 4 parameters are passed to a method — if more are needed, encapsulate in an object/DTO
+- The boundaries and layers defined in AGENTS.md are respected
+- No unnecessary coupling is introduced between modules or services
+
+> Architecture varies by project. Consult AGENTS.md to know which applies.
+
+## 5. Error handling
+- Errors are handled consistently with the rest of the project
+- Error messages are useful for diagnosis (what failed, in what context)
+- Internal details are not exposed to the user/consumer (stack traces, internal paths, DB IDs)
+- Expected errors (validation, business) are distinguished from unexpected ones (system, infrastructure)
+- No silenced errors (empty catch without log or handling)
+
+## 6. Testing
+- Each new/modified file has a corresponding test file
+- Tests cover the acceptance criteria from the spec
+- There are tests for edge cases and error scenarios
+- Tests validate **behavior**, not implementation details (they do not break when refactoring)
+- Mocks are minimal and necessary — do not mock what can be tested directly
+- Tests are independent of each other (do not depend on execution order or shared state)
+- Coverage >= 80% on new files
+- Tests pass without errors (run the test command indicated in AGENTS.md)
+
+## 7. Security
+- No hardcoded secrets (passwords, API keys, tokens, internal service URLs)
+- User inputs are validated before processing
+- Sensitive endpoints or routes have appropriate authorization
+- Sensitive information is not exposed in logs, error responses, or client source code
+- No dependencies with known critical vulnerabilities (check if the project has audit configured)
+
+## 8. Dependencies
+- New dependencies are justified (no library added for something that can be done in a few lines)
+- The license is compatible with the project
+- The dependency is actively maintained (not abandoned)
+- Does not duplicate functionality that already exists in the project or another installed dependency
+- The version is pinned or uses a safe range (not `*` or `latest`)
+
+## 9. Maintainability and observability
+- The code is self-explanatory (comments only where logic is not obvious)
+- Files are not excessively long (< 400 lines as a guideline)
+- If something fails in production, there is enough information to diagnose (logs, traces, context in errors)
+- Configuration changes are documented (new environment variables, flags, parameters)
+
+## 10. Git and Deploy
+- Commits are atomic and have descriptive messages
+- No generated, temporary, or sensitive files in the commit (check .gitignore)
+- No undocumented breaking changes
+- If there are migrations, they are reversible and do not break existing data
+
+## 11. Project-specific rules
+- Consult the "Critical rules" section of AGENTS.md
+- Evaluate against the "Always do", "Never do", and "Ask first" rules
+- If AGENTS.md defines additional rules, verify their compliance
+
+## Review exit criteria
+- **APROBADO**: No CRITICAL/HIGH FAILs.
+- **APROBADO CON OBSERVACIONES**: Only MEDIUM/LOW FAILs.
+- **REQUIERE CORRECCIONES**: At least one CRITICAL/HIGH FAIL exists.

package/skills/say/SKILL.md

@@ -1,38 +1,38 @@
----
-name: refacil:say
-description: Enviar un mensaje a toda la sala del bus (broadcast). Para anuncios generales, no para preguntas dirigidas.
-user-invocable: true
----
-
-# refacil:say — Broadcast a la sala
-
-Envía un mensaje visible para todos los miembros de la sala en la que está esta sesión. **$ARGUMENTS** = texto del mensaje.
-
-## Instrucciones
-
-### Paso 1: Ejecutar el broadcast
-
-Ejecuta vía `Bash`:
-
-```bash
-refacil-sdd-ai bus say --text "<texto>"
-```
-
-Donde `<texto>` es $ARGUMENTS (o lo que el usuario te pidió anunciar). Entrecomilla el texto correctamente.
-
-### Paso 2: Confirmar
-
-Reporta al usuario que el mensaje se envió con su id.
-
-## Cuándo usar `say` vs otros comandos del bus
-
-- **`say`**: anuncio general a la sala — "terminé mi parte", "cambié el contrato de X", "voy a reiniciar el servicio"
-- **`ask`**: pregunta dirigida a otra sesión específica (usa `/refacil:ask`)
-- **`reply`**: responder una pregunta que te hicieron (usa `/refacil:reply`)
-
-## Reglas
-
-- La sesión debe estar unida a una sala; si no, el CLI retornará error.
-- Mensaje corto y útil — evita spam en el bus.
-- Si el usuario pide "avisa al equipo ...", usa `say`. Si pide "pregúntale a X ...", usa `ask`.
-- Si un hilo en sala **acuerda cambios en este repo**, sigue `refacil-prereqs/BUS-CROSS-REPO.md`: **`/refacil:propose`** y cierre por bus con quien pidio el trabajo al terminar.
+---
+name: refacil:say
+description: Send a message to the entire bus room (broadcast). For general announcements, not directed questions.
+user-invocable: true
+---
+
+# refacil:say — Broadcast to the room
+
+Sends a message visible to all members of the room this session is in. **$ARGUMENTS** = message text.
+
+## Instructions
+
+### Step 1: Execute the broadcast
+
+Run via `Bash`:
+
+```bash
+refacil-sdd-ai bus say --text "<text>"
+```
+
+Where `<text>` is $ARGUMENTS (or what the user asked you to announce). Correctly quote the text.
+
+### Step 2: Confirm
+
+Report to the user that the message was sent with its id.
+
+## When to use `say` vs other bus commands
+
+- **`say`**: general announcement to the room — "I finished my part", "I changed the X contract", "I'm going to restart the service"
+- **`ask`**: directed question to another specific session (use `/refacil:ask`)
+- **`reply`**: respond to a question you were asked (use `/refacil:reply`)
+
+## Rules
+
+- The session must be joined to a room; if not, the CLI will return an error.
+- Short and useful message — avoid bus spam.
+- If the user asks "tell the team ...", use `say`. If they ask "ask X ...", use `ask`.
+- If a room thread **agrees on changes in this repo**, follow `refacil-prereqs/BUS-CROSS-REPO.md`: **`/refacil:propose`** and close via bus with whoever requested the work when done.