refacil-sdd-ai 4.2.4 → 4.3.0

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

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.