theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/revision-codigo-flutter-dart/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: revision-codigo-flutter-dart
+description: Checklist de revisión de código Flutter/Dart agnóstico de librerías — buenas prácticas
+  de widgets, gestión de estado (BLoC, Riverpod, Provider, GetX, MobX, Signals), idiomas de Dart,
+  rendimiento, accesibilidad, seguridad y arquitectura limpia.
+---
+
+# Revisión de código Flutter/Dart
+
+Checklist integral y agnóstico de librerías para revisar aplicaciones Flutter/Dart. Estos principios aplican sea cual sea la solución de gestión de estado, la librería de routing o el framework de inyección de dependencias del proyecto.
+
+---
+
+## 1. Salud general del proyecto
+
+- [ ] El proyecto sigue una estructura de carpetas consistente (feature-first o layer-first)
+- [ ] Separación de responsabilidades correcta: capas de UI, lógica de negocio y datos
+- [ ] Sin lógica de negocio en widgets; los widgets son puramente presentacionales
+- [ ] `pubspec.yaml` limpio — sin dependencias sin uso, versiones fijadas apropiadamente
+- [ ] `analysis_options.yaml` incluye un set de lints estricto con ajustes estrictos del analizador
+- [ ] Sin `print()` en código de producción — usar `log()` de `dart:developer` o un paquete de logging
+- [ ] Archivos generados (`.g.dart`, `.freezed.dart`, `.gr.dart`) actualizados o en `.gitignore`
+- [ ] Código específico de plataforma aislado tras abstracciones
+
+---
+
+## 2. Trampas del lenguaje Dart
+
+- [ ] **`dynamic` implícito**: anotaciones de tipo ausentes que degradan a `dynamic` — activar `strict-casts`, `strict-inference`, `strict-raw-types`
+- [ ] **Mal uso de null safety**: exceso de `!` (operador bang) en lugar de comprobaciones de null o pattern matching de Dart 3 (`if (value case var v?)`)
+- [ ] **Fallos de promoción de tipos**: usar `this.field` donde funcionaría la promoción de variable local
+- [ ] **Capturas demasiado amplias**: `catch (e)` sin cláusula `on`; especificar siempre los tipos de excepción
+- [ ] **Capturar `Error`**: los subtipos de `Error` indican bugs y no deben capturarse
+- [ ] **`async` sin uso**: funciones marcadas `async` que nunca hacen `await` — sobrecoste innecesario
+- [ ] **Abuso de `late`**: `late` donde un nullable o la inicialización en constructor sería más segura; difiere errores al runtime
+- [ ] **Concatenación de strings en bucles**: usar `StringBuffer` en lugar de `+` para construcción iterativa
+- [ ] **Estado mutable en contextos `const`**: los campos de clases con constructor `const` no deben ser mutables
+- [ ] **Ignorar valores `Future`**: usar `await` o llamar explícitamente `unawaited()` para señalar la intención
+- [ ] **`var` donde cabe `final`**: preferir `final` para locales y `const` para constantes de compilación
+- [ ] **Imports relativos**: usar imports `package:` por consistencia
+- [ ] **Colecciones mutables expuestas**: las APIs públicas deben devolver vistas inmodificables, no `List`/`Map` crudos
+- [ ] **Falta de pattern matching de Dart 3**: preferir switch expressions e `if-case` sobre comprobaciones `is` verbosas y casting manual
+- [ ] **Clases desechables para retornos múltiples**: usar records de Dart 3 `(String, int)` en lugar de DTOs de un solo uso
+- [ ] **`print()` en producción**: usar `log()` de `dart:developer` o el paquete de logging del proyecto; `print()` no tiene niveles ni se puede filtrar
+
+---
+
+## 3. Buenas prácticas de widgets
+
+### Descomposición de widgets:
+- [ ] Ningún widget con un `build()` que supere ~80-100 líneas
+- [ ] Widgets divididos por encapsulación Y por cómo cambian (fronteras de rebuild)
+- [ ] Los métodos privados `_build*()` que devuelven widgets se extraen a clases widget separadas (habilita reutilización de elementos, propagación de `const` y optimizaciones del framework)
+- [ ] Widgets Stateless preferidos sobre Stateful cuando no hay estado local mutable
+- [ ] Los widgets extraídos van en archivos separados cuando son reutilizables
+
+### Uso de const:
+- [ ] Constructores `const` usados siempre que sea posible — evita rebuilds innecesarios
+- [ ] Literales `const` para colecciones que no cambian (`const []`, `const {}`)
+- [ ] El constructor se declara `const` cuando todos los campos son final
+
+### Uso de keys:
+- [ ] `ValueKey` en listas/grids para preservar estado en reordenamientos
+- [ ] `GlobalKey` con moderación — solo cuando realmente hay que acceder a estado a través del árbol
+- [ ] `UniqueKey` evitado en `build()` — fuerza rebuild en cada frame
+- [ ] `ObjectKey` cuando la identidad se basa en un objeto de datos y no en un valor simple
+
+### Theming y sistema de diseño:
+- [ ] Los colores vienen de `Theme.of(context).colorScheme` — nada de `Colors.red` ni hex hardcodeados
+- [ ] Los estilos de texto vienen de `Theme.of(context).textTheme` — sin `TextStyle` inline con tamaños crudos
+- [ ] Compatibilidad con modo oscuro verificada — sin asumir fondo claro
+- [ ] Espaciado y tamaños con tokens de diseño o constantes consistentes, no números mágicos
+
+### Complejidad del método build:
+- [ ] Sin llamadas de red, I/O de archivos ni cómputo pesado en `build()`
+- [ ] Sin `Future.then()` ni trabajo `async` en `build()`
+- [ ] Sin creación de suscripciones (`.listen()`) en `build()`
+- [ ] `setState()` localizado en el subárbol más pequeño posible
+
+---
+
+## 4. Gestión de estado (agnóstico de librería)
+
+Estos principios aplican a todas las soluciones de gestión de estado en Flutter (BLoC, Riverpod, Provider, GetX, MobX, Signals, ValueNotifier, etc.).
+
+### Arquitectura:
+- [ ] La lógica de negocio vive fuera de la capa de widgets — en un componente de gestión de estado (BLoC, Notifier, Controller, Store, ViewModel, etc.)
+- [ ] Los gestores de estado reciben dependencias por inyección, no construyéndolas internamente
+- [ ] Una capa de servicios o repositorios abstrae las fuentes de datos — widgets y gestores de estado no llaman a APIs ni bases de datos directamente
+- [ ] Los gestores de estado tienen responsabilidad única — nada de gestores "dios" con asuntos inconexos
+- [ ] Las dependencias entre componentes siguen las convenciones de cada solución:
+  - En **Riverpod**: providers que dependen de providers vía `ref.watch` es lo esperado — marcar solo cadenas circulares o excesivamente enredadas
+  - En **BLoC**: los blocs no deben depender directamente de otros blocs — preferir repositorios compartidos o coordinación en la capa de presentación
+  - En otras soluciones: seguir las convenciones documentadas de comunicación entre componentes
+
+### Inmutabilidad e igualdad por valor (soluciones de estado inmutable: BLoC, Riverpod, Redux):
+- [ ] Los objetos de estado son inmutables — instancias nuevas vía `copyWith()` o constructores, nunca mutación in-place
+- [ ] Las clases de estado implementan `==` y `hashCode` correctamente (todos los campos en la comparación)
+- [ ] El mecanismo es consistente en el proyecto — override manual, `Equatable`, `freezed`, records de Dart u otro
+- [ ] Las colecciones dentro del estado no se exponen como `List`/`Map` mutables crudos
+
+### Disciplina de reactividad (soluciones de mutación reactiva: MobX, GetX, Signals):
+- [ ] El estado solo se muta a través de la API reactiva de la solución (`@action` en MobX, `.value` en signals, `.obs` en GetX) — la mutación directa de campos elude el seguimiento de cambios
+- [ ] Los valores derivados usan el mecanismo computed de la solución en lugar de almacenarse redundantemente
+- [ ] Reacciones y disposers se limpian correctamente (`ReactionDisposer` en MobX, cleanup de effects en Signals)
+
+### Diseño de la forma del estado:
+- [ ] Los estados mutuamente excluyentes usan tipos sealed, variantes union o el tipo async de la solución (p. ej. `AsyncValue` de Riverpod) — no banderas booleanas (`isLoading`, `isError`, `hasData`)
+- [ ] Cada operación async modela loading, éxito y error como estados distintos
+- [ ] Todas las variantes de estado se manejan exhaustivamente en la UI — sin casos silenciosamente ignorados
+- [ ] Los estados de error llevan la información del error para mostrarla; los de carga no llevan datos obsoletos
+- [ ] Los datos nullable no se usan como indicador de carga — los estados son explícitos
+
+```dart
+// MAL — la sopa de banderas booleanas permite estados imposibles
+class UserState {
+  bool isLoading = false;
+  bool hasError = false; // ¡isLoading && hasError es representable!
+  User? user;
+}
+
+// BIEN (enfoque inmutable) — los tipos sealed hacen irrepresentables los estados imposibles
+sealed class UserState {}
+class UserInitial extends UserState {}
+class UserLoading extends UserState {}
+class UserLoaded extends UserState {
+  final User user;
+  const UserLoaded(this.user);
+}
+class UserError extends UserState {
+  final String message;
+  const UserError(this.message);
+}
+
+// BIEN (enfoque reactivo) — enum observable + datos, mutaciones vía API de reactividad
+// enum UserStatus { initial, loading, loaded, error }
+// Usa el observable/signal de tu solución para envolver status y datos por separado
+```
+
+### Optimización de rebuilds:
+- [ ] Los widgets consumidores de estado (Builder, Consumer, Observer, Obx, Watch, etc.) acotados lo más estrecho posible
+- [ ] Selectores para reconstruir solo cuando cambian campos concretos — no en cada emisión de estado
+- [ ] Widgets `const` para frenar la propagación de rebuilds por el árbol
+- [ ] El estado computado/derivado se calcula reactivamente, no se almacena de forma redundante
+
+### Suscripciones y disposal:
+- [ ] Toda suscripción manual (`.listen()`) se cancela en `dispose()` / `close()`
+- [ ] Los stream controllers se cierran cuando ya no se necesitan
+- [ ] Los timers se cancelan en el ciclo de disposal
+- [ ] Se prefiere el ciclo de vida gestionado por el framework sobre la suscripción manual (builders declarativos sobre `.listen()`)
+- [ ] Comprobación de `mounted` antes de `setState` en callbacks async
+- [ ] `BuildContext` no se usa después de un `await` sin comprobar `context.mounted` (Flutter 3.7+) — un contexto obsoleto provoca crashes
+- [ ] Sin navegación, diálogos ni mensajes de scaffold tras huecos async sin verificar que el widget sigue montado
+- [ ] `BuildContext` nunca se guarda en singletons, gestores de estado ni campos estáticos
+
+### Estado local vs global:
+- [ ] El estado efímero de UI (checkbox, slider, animación) usa estado local (`setState`, `ValueNotifier`)
+- [ ] El estado compartido se eleva solo lo necesario — no se sobre-globaliza
+- [ ] El estado acotado a una feature se libera correctamente cuando la feature deja de estar activa
+
+---
+
+## 5. Rendimiento
+
+### Rebuilds innecesarios:
+- [ ] `setState()` no se llama en la raíz — localizar los cambios de estado
+- [ ] Widgets `const` para frenar la propagación de rebuilds
+- [ ] `RepaintBoundary` alrededor de subárboles complejos que repintan de forma independiente
+- [ ] Parámetro `child` de `AnimatedBuilder` para subárboles independientes de la animación
+
+### Operaciones caras en build():
+- [ ] Sin ordenar, filtrar ni mapear colecciones grandes en `build()` — computar en la capa de gestión de estado
+- [ ] Sin compilación de regex en `build()`
+- [ ] Uso específico de `MediaQuery.of(context)` (p. ej. `MediaQuery.sizeOf(context)`)
+
+### Optimización de imágenes:
+- [ ] Las imágenes de red usan caché (cualquier solución de caché apropiada para el proyecto)
+- [ ] Resolución de imagen adecuada al dispositivo objetivo (no cargar 4K para miniaturas)
+- [ ] `Image.asset` con `cacheWidth`/`cacheHeight` para decodificar al tamaño mostrado
+- [ ] Placeholder y widget de error para imágenes de red
+
+### Carga diferida:
+- [ ] `ListView.builder` / `GridView.builder` en lugar de `ListView(children: [...])` para listas grandes o dinámicas (los constructores concretos están bien para listas pequeñas y estáticas)
+- [ ] Paginación implementada para conjuntos de datos grandes
+- [ ] Carga diferida (`deferred as`) para librerías pesadas en builds web
+
+### Otros:
+- [ ] Widget `Opacity` evitado en animaciones — usar `AnimatedOpacity` o `FadeTransition`
+- [ ] Clipping evitado en animaciones — pre-recortar las imágenes
+- [ ] `operator ==` no se sobreescribe en widgets — usar constructores `const`
+- [ ] Widgets de dimensiones intrínsecas (`IntrinsicHeight`, `IntrinsicWidth`) con moderación (pase de layout extra)
+
+---
+
+## 6. Testing
+
+### Tipos de tests y expectativas:
+- [ ] **Tests unitarios**: cubren toda la lógica de negocio (gestores de estado, repositorios, utilidades)
+- [ ] **Tests de widget**: cubren comportamiento, interacciones y salida visual de widgets individuales
+- [ ] **Tests de integración**: cubren flujos de usuario críticos de extremo a extremo
+- [ ] **Golden tests**: comparaciones pixel-perfect para componentes de UI críticos de diseño
+
+### Objetivos de cobertura:
+- [ ] Apuntar a 80 %+ de cobertura de líneas en la lógica de negocio
+- [ ] Todas las transiciones de estado tienen tests (loading → success, loading → error, reintento, etc.)
+- [ ] Casos límite testeados: estados vacíos, de error, de carga, valores frontera
+
+### Aislamiento de tests:
+- [ ] Las dependencias externas (clientes de API, bases de datos, servicios) se mockean o se sustituyen por fakes
+- [ ] Cada archivo de test prueba exactamente una clase/unidad
+- [ ] Los tests verifican comportamiento, no detalles de implementación
+- [ ] Los stubs definen solo el comportamiento necesario para cada test (stubbing mínimo)
+- [ ] Sin estado mutable compartido entre casos de test
+
+### Calidad de los tests de widget:
+- [ ] `pumpWidget` y `pump` usados correctamente para operaciones async
+- [ ] `find.byType`, `find.text`, `find.byKey` usados apropiadamente
+- [ ] Sin tests flaky que dependan del timing — usar `pumpAndSettle` o `pump(Duration)` explícito
+- [ ] Los tests corren en CI y sus fallos bloquean los merges
+
+---
+
+## 7. Accesibilidad
+
+### Widgets semánticos:
+- [ ] Widget `Semantics` para dar etiquetas de lector de pantalla donde las automáticas no bastan
+- [ ] `ExcludeSemantics` para elementos puramente decorativos
+- [ ] `MergeSemantics` para combinar widgets relacionados en un único elemento accesible
+- [ ] Las imágenes tienen la propiedad `semanticLabel`
+
+### Soporte de lector de pantalla:
+- [ ] Todos los elementos interactivos son enfocables y tienen descripciones significativas
+- [ ] El orden de foco es lógico (sigue el orden visual de lectura)
+
+### Accesibilidad visual:
+- [ ] Contraste >= 4.5:1 entre texto y fondo
+- [ ] Objetivos táctiles de al menos 48x48 píxeles
+- [ ] El color no es el único indicador de estado (acompañar con iconos/texto)
+- [ ] El texto escala con la configuración de tamaño de fuente del sistema
+
+### Accesibilidad de interacción:
+- [ ] Sin callbacks `onPressed` vacíos — cada botón hace algo o está deshabilitado
+- [ ] Los campos con error sugieren correcciones
+- [ ] El contexto no cambia inesperadamente mientras el usuario introduce datos
+
+---
+
+## 8. Aspectos específicos de plataforma
+
+### Diferencias iOS/Android:
+- [ ] Widgets adaptativos por plataforma donde corresponda
+- [ ] Navegación atrás correcta (botón atrás de Android, gesto swipe de iOS)
+- [ ] Barra de estado y safe area gestionadas vía widget `SafeArea`
+- [ ] Permisos específicos de plataforma declarados en `AndroidManifest.xml` e `Info.plist`
+
+### Diseño responsivo:
+- [ ] `LayoutBuilder` o `MediaQuery` para layouts responsivos
+- [ ] Breakpoints definidos consistentemente (teléfono, tablet, escritorio)
+- [ ] El texto no desborda en pantallas pequeñas — usar `Flexible`, `Expanded`, `FittedBox`
+- [ ] Orientación horizontal testeada o explícitamente bloqueada
+- [ ] Web: interacciones de ratón/teclado soportadas, estados hover presentes
+
+---
+
+## 9. Seguridad
+
+### Almacenamiento seguro:
+- [ ] Los datos sensibles (tokens, credenciales) usan el almacenamiento seguro de la plataforma (Keychain en iOS, EncryptedSharedPreferences en Android)
+- [ ] Nunca guardar secretos en almacenamiento plano
+- [ ] Considerar autenticación biométrica para operaciones sensibles
+
+### Manejo de API keys:
+- [ ] Las API keys NO están hardcodeadas en el código Dart — usar `--dart-define`, archivos `.env` excluidos del VCS o configuración en tiempo de compilación
+- [ ] Los secretos no se commitean a git — revisar `.gitignore`
+- [ ] Proxy de backend para claves realmente secretas (el cliente nunca debe poseer secretos de servidor)
+
+### Validación de entrada:
+- [ ] Toda entrada del usuario se valida antes de enviarse a la API
+- [ ] La validación de formularios usa patrones apropiados
+- [ ] Sin SQL crudo ni interpolación de strings con entrada del usuario
+- [ ] Las URLs de deep links se validan y sanitizan antes de navegar
+
+### Seguridad de red:
+- [ ] HTTPS obligatorio en todas las llamadas de API
+- [ ] Considerar certificate pinning para apps de alta seguridad
+- [ ] Tokens de autenticación se refrescan y expiran correctamente
+- [ ] Sin datos sensibles en logs ni prints
+
+---
+
+## 10. Revisión de paquetes/dependencias
+
+### Evaluar paquetes de pub.dev:
+- [ ] Revisar la **puntuación de pub points** (apuntar a 130+/160)
+- [ ] Revisar **likes** y **popularidad** como señales de comunidad
+- [ ] Verificar que el publicador esté **verificado** en pub.dev
+- [ ] Revisar la fecha de última publicación — los paquetes estancados (>1 año) son un riesgo
+- [ ] Revisar issues abiertas y tiempo de respuesta de los mantenedores
+- [ ] Comprobar compatibilidad de licencia con el proyecto
+- [ ] Verificar que el soporte de plataformas cubra los targets
+
+### Restricciones de versión:
+- [ ] Sintaxis caret (`^1.2.3`) para dependencias — permite actualizaciones compatibles
+- [ ] Fijar versiones exactas solo cuando sea absolutamente necesario
+- [ ] Ejecutar `flutter pub outdated` con regularidad para vigilar dependencias obsoletas
+- [ ] Sin dependency overrides en el `pubspec.yaml` de producción — solo para arreglos temporales con comentario/enlace a issue
+- [ ] Minimizar el número de dependencias transitivas — cada dependencia es superficie de ataque
+
+### Específico de monorepos (melos/workspace):
+- [ ] Los paquetes internos importan solo desde la API pública — nada de `package:other/src/internal.dart` (rompe la encapsulación de paquetes Dart)
+- [ ] Las dependencias entre paquetes internos usan resolución de workspace, no strings relativos `path: ../../` hardcodeados
+- [ ] Todos los subpaquetes comparten o heredan el `analysis_options.yaml` raíz
+
+---
+
+## 11. Navegación y routing
+
+### Principios generales (aplican a cualquier solución de routing):
+- [ ] Un solo enfoque de routing usado consistentemente — sin mezclar `Navigator.push` imperativo con un router declarativo
+- [ ] Los argumentos de ruta están tipados — sin castings de `Map<String, dynamic>` u `Object?`
+- [ ] Las rutas se definen como constantes, enums o código generado — sin strings mágicos dispersos
+- [ ] Guards/redirecciones de autenticación centralizados — no duplicados en pantallas individuales
+- [ ] Deep links configurados para Android e iOS
+- [ ] Las URLs de deep links se validan y sanitizan antes de navegar
+- [ ] El estado de navegación es testeable — los cambios de ruta se pueden verificar en tests
+- [ ] El comportamiento de "atrás" es correcto en todas las plataformas
+
+---
+
+## 12. Manejo de errores
+
+### Manejo de errores del framework:
+- [ ] `FlutterError.onError` sobreescrito para capturar errores del framework (build, layout, paint)
+- [ ] `PlatformDispatcher.instance.onError` configurado para errores async no capturados por Flutter
+- [ ] `ErrorWidget.builder` personalizado en modo release (amigable en vez de pantalla roja)
+- [ ] Envoltura global de captura de errores alrededor de `runApp` (p. ej. `runZonedGuarded` o el wrapper del servicio de reporte)
+
+### Reporte de errores:
+- [ ] Servicio de reporte de errores integrado (Firebase Crashlytics, Sentry o equivalente)
+- [ ] Errores no fatales reportados con stack traces
+- [ ] El observador de errores de la gestión de estado conectado al reporte (p. ej. BlocObserver, ProviderObserver o equivalente)
+- [ ] Información identificable (user ID) adjunta a los reportes para depuración
+
+### Degradación elegante:
+- [ ] Los errores de API resultan en UI de error amigable, no en crashes
+- [ ] Mecanismos de reintento para fallos de red transitorios
+- [ ] Estado offline manejado con elegancia
+- [ ] Los estados de error en la gestión de estado llevan la información para mostrarla
+- [ ] Las excepciones crudas (red, parsing) se mapean a mensajes amigables y localizados antes de llegar a la UI — nunca mostrar strings de excepción crudos al usuario
+
+---
+
+## 13. Internacionalización (l10n)
+
+### Configuración:
+- [ ] Solución de localización configurada (ARB/l10n integrado de Flutter, easy_localization o equivalente)
+- [ ] Locales soportados declarados en la configuración de la app
+
+### Contenido:
+- [ ] Todos los strings visibles usan el sistema de localización — sin strings hardcodeados en widgets
+- [ ] El archivo plantilla incluye descripciones/contexto para traductores
+- [ ] Sintaxis ICU para plurales, géneros, selects
+- [ ] Placeholders definidos con tipos
+- [ ] Sin claves faltantes entre locales
+
+### En la revisión:
+- [ ] Accesor de localización usado consistentemente en todo el proyecto
+- [ ] Formato de fecha, hora, número y moneda consciente del locale
+- [ ] Direccionalidad de texto (RTL) soportada si se apunta a árabe, hebreo, etc.
+- [ ] Sin concatenación de strings para texto localizado — usar mensajes parametrizados
+
+---
+
+## 14. Inyección de dependencias
+
+### Principios (aplican a cualquier enfoque de DI):
+- [ ] Las clases dependen de abstracciones (interfaces), no de implementaciones concretas en las fronteras de capa
+- [ ] Las dependencias se proveen externamente vía constructor, framework de DI o grafo de providers — no se crean internamente
+- [ ] El registro distingue tiempos de vida: singleton vs factory vs lazy singleton
+- [ ] Los bindings por entorno (dev/staging/prod) usan configuración, no `if` en runtime
+- [ ] Sin dependencias circulares en el grafo de DI
+- [ ] Las llamadas al service locator (si se usa) no están dispersas por la lógica de negocio
+
+---
+
+## 15. Análisis estático
+
+### Configuración:
+- [ ] `analysis_options.yaml` presente con ajustes estrictos
+- [ ] Analizador estricto: `strict-casts: true`, `strict-inference: true`, `strict-raw-types: true`
+- [ ] Se incluye un set completo de lints (very_good_analysis, flutter_lints o reglas estrictas propias)
+- [ ] Todos los subpaquetes de un monorepo heredan o comparten las opciones raíz
+
+### Cumplimiento:
+- [ ] Sin warnings del analizador sin resolver en código commiteado
+- [ ] Las supresiones de lint (`// ignore:`) están justificadas con comentarios que explican el porqué
+- [ ] `flutter analyze` corre en CI y sus fallos bloquean los merges
+
+### Reglas clave a verificar con cualquier paquete de lints:
+- [ ] `prefer_const_constructors` — rendimiento en árboles de widgets
+- [ ] `avoid_print` — logging apropiado
+- [ ] `unawaited_futures` — evita bugs async de "dispara y olvida"
+- [ ] `prefer_final_locals` — inmutabilidad a nivel de variable
+- [ ] `always_declare_return_types` — contratos explícitos
+- [ ] `avoid_catches_without_on_clauses` — manejo de errores específico
+- [ ] `always_use_package_imports` — estilo de imports consistente
+
+---
+
+## Referencia rápida de gestión de estado
+
+La tabla mapea principios universales a su implementación en soluciones populares. Úsala para adaptar las reglas de revisión a la solución que use el proyecto.
+
+| Principio | BLoC/Cubit | Riverpod | Provider | GetX | MobX | Signals | Integrado |
+|-----------|-----------|----------|----------|------|------|---------|----------|
+| Contenedor de estado | `Bloc`/`Cubit` | `Notifier`/`AsyncNotifier` | `ChangeNotifier` | `GetxController` | `Store` | `signal()` | `StatefulWidget` |
+| Consumidor de UI | `BlocBuilder` | `ConsumerWidget` | `Consumer` | `Obx`/`GetBuilder` | `Observer` | `Watch` | `setState` |
+| Selector | `BlocSelector`/`buildWhen` | `ref.watch(p.select(...))` | `Selector` | N/A | computed | `computed()` | N/A |
+| Efectos secundarios | `BlocListener` | `ref.listen` | callback de `Consumer` | `ever()`/`once()` | `reaction` | `effect()` | callbacks |
+| Disposal | auto vía `BlocProvider` | `.autoDispose` | auto vía `Provider` | `onClose()` | `ReactionDisposer` | manual | `dispose()` |
+| Testing | `blocTest()` | `ProviderContainer` | `ChangeNotifier` directo | `Get.put` en test | store directo | signal directo | test de widget |
+
+---
+
+## Referencias
+
+- [Effective Dart: Style](https://dart.dev/effective-dart/style)
+- [Effective Dart: Usage](https://dart.dev/effective-dart/usage)
+- [Effective Dart: Design](https://dart.dev/effective-dart/design)
+- [Buenas prácticas de rendimiento en Flutter](https://docs.flutter.dev/perf/best-practices)
+- [Panorama de testing en Flutter](https://docs.flutter.dev/testing/overview)
+- [Accesibilidad en Flutter](https://docs.flutter.dev/ui/accessibility-and-internationalization/accessibility)
+- [Internacionalización en Flutter](https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization)
+- [Navegación y routing en Flutter](https://docs.flutter.dev/ui/navigation)
+- [Manejo de errores en Flutter](https://docs.flutter.dev/testing/errors)
+- [Opciones de gestión de estado en Flutter](https://docs.flutter.dev/data-and-backend/state-mgmt/options)
+
+## Relacionados
+
+- Agente: `agents/revisor-flutter.md`
+- Comandos: `/revisar-flutter`, `/build-flutter`, `/test-flutter`
+- Skill: `skills/patrones-dart-flutter/`

package/vendor/theus-arsenal/skills/revision-literatura-cientifica/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: revision-literatura-cientifica
+description: Flujo de revisión de literatura sistemática para temas académicos, biomédicos, técnicos
+  y científicos. Incluye planificación de búsqueda, cribado de fuentes, síntesis, verificación de
+  citas y registro de evidencia.
+---
+
+# Revisión de literatura científica
+
+Usa esta skill cuando la tarea sea encontrar, cribar, sintetizar y citar un cuerpo de literatura académica o técnica.
+
+## Cuándo usarla
+
+- Al construir una revisión de literatura sistemática, de alcance (scoping) o narrativa.
+- Al sintetizar el estado del arte para una pregunta de investigación.
+- Al buscar brechas, contradicciones o direcciones de trabajo futuro.
+- Al preparar secciones de antecedentes respaldadas por citas para artículos o informes.
+- Al comparar evidencia entre artículos revisados por pares, preprints, patentes e informes técnicos.
+
+## Tipos de revisión
+
+- **Revisión narrativa**: síntesis amplia; útil para orientación.
+- **Revisión de alcance (scoping)**: mapea conceptos, métodos y brechas de evidencia.
+- **Revisión sistemática**: protocolo predefinido, búsqueda reproducible, cribado y exclusión explícitos.
+- **Metaanálisis**: revisión sistemática más agregación cuantitativa de efectos.
+
+Pregunta al usuario qué nivel de rigor necesita. Si no lo especifica, usa por defecto una revisión de alcance para trabajo exploratorio y una revisión sistemática para publicación o afirmaciones clínicas.
+
+## Flujo de trabajo
+
+### 1. Define la pregunta
+
+Convierte el encargo en una pregunta de investigación buscable.
+
+Para trabajo clínico o biomédico, usa PICO:
+
+- Población
+- Intervención o exposición
+- Comparador
+- Resultado (outcome)
+
+Para trabajo técnico, usa:
+
+- sistema o dominio
+- método o intervención
+- línea base de comparación
+- métrica de evaluación
+
+### 2. Planifica la búsqueda
+
+Crea un protocolo de búsqueda antes de recolectar fuentes:
+
+- bases de datos a consultar
+- rango de fechas
+- idiomas
+- tipos de publicación
+- criterios de inclusión
+- criterios de exclusión
+- cadenas de búsqueda exactas
+
+Conjunto mínimo útil de bases de datos:
+
+- PubMed para literatura biomédica y de ciencias de la vida.
+- arXiv para informática, matemáticas, física, biología cuantitativa y preprints.
+- Semantic Scholar o Crossref para descubrimiento académico amplio.
+- Fuentes específicas del dominio cuando aplique: registros de ensayos clínicos, bases de patentes, organismos de estándares o documentación técnica oficial.
+
+### 3. Busca y registra la evidencia
+
+Mantén una bitácora de búsqueda que haga la revisión reproducible:
+
+```markdown
+| Base de datos | Fecha de búsqueda | Consulta | Filtros | Resultados | Exportación |
+| --- | --- | --- | --- | ---: | --- |
+| PubMed | 2026-05-11 | `("CRISPR"[tiab] OR "Cas9"[tiab]) AND "sickle cell"[tiab]` | 2020:2026, inglés | 86 | lista de PMID |
+| arXiv | 2026-05-11 | `CRISPR sickle cell gene editing` | q-bio, 2020:2026 | 9 | BibTeX |
+```
+
+Guarda los IDs crudos, URLs, DOIs, resúmenes y notas por separado de la prosa final.
+
+### 4. Deduplica
+
+Deduplica en este orden:
+
+1. DOI
+2. PMID o ID de arXiv
+3. título exacto
+4. título normalizado más primer autor y año
+
+Registra cuántos duplicados se eliminaron.
+
+### 5. Criba las fuentes
+
+Criba por etapas:
+
+1. título
+2. resumen (abstract)
+3. texto completo
+
+Para trabajo sistemático, registra las razones de exclusión:
+
+- población incorrecta
+- intervención incorrecta
+- resultado incorrecto
+- no es investigación primaria
+- duplicado
+- texto completo no disponible
+- fuera del rango de fechas
+
+### 6. Extrae los datos
+
+Usa una tabla de extracción estructurada:
+
+```markdown
+| Estudio | Diseño | Población/Datos | Método | Comparador | Resultado | Hallazgo clave | Limitaciones |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Autor Año | ECA/cohorte/revisión/etc. | muestra o corpus | método | línea base | resultado medido | resultado | advertencia |
+```
+
+Para artículos técnicos, incluye conjunto de datos, benchmark, métrica, línea base y notas de reproducibilidad.
+
+### 7. Sintetiza
+
+Agrupa la evidencia por tema en lugar de resumir los artículos uno por uno.
+
+Lentes de síntesis útiles:
+
+- evidencia más sólida
+- evidencia contradictoria
+- debilidades metodológicas
+- límites de población o de conjunto de datos
+- actualidad y replicación
+- implicaciones prácticas
+- preguntas sin responder
+
+Separa las afirmaciones por nivel de confianza:
+
+- **Confianza alta**: evidencia replicada y de alta calidad en varias fuentes.
+- **Confianza media**: plausible pero limitada por muestra, método o actualidad.
+- **Confianza baja**: temprana, especulativa, de una sola fuente o medida con debilidad.
+
+### 8. Verifica las citas
+
+Antes de finalizar:
+
+- verifica el DOI, PMID, ID de arXiv o URL oficial
+- comprueba nombres de autores y año de publicación
+- no cites un artículo por una afirmación que no hace
+- marca los preprints como preprints
+- distingue las revisiones de la evidencia primaria
+
+## Plantilla de salida
+
+```markdown
+# Revisión de literatura: <tema>
+
+Generada: <fecha>
+Tipo de revisión: <narrativa | de alcance | sistemática | metaanálisis>
+Ventana de búsqueda: <fechas>
+Bases de datos: <lista>
+
+## Pregunta de investigación
+
+## Estrategia de búsqueda
+
+## Criterios de inclusión y exclusión
+
+## Resumen de la evidencia
+
+## Síntesis temática
+
+## Brechas y limitaciones
+
+## Referencias
+
+## Bitácora de búsqueda
+```
+
+## Errores a evitar
+
+- No trates los fragmentos (snippets) de búsqueda como evidencia.
+- No mezcles preprints, revisiones y estudios primarios sin etiquetarlos.
+- No omitas hallazgos negativos o contradictorios.
+- No afirmes rigor de revisión sistemática sin un protocolo reproducible.
+- No uses una sola base de datos para una afirmación amplia, salvo que el alcance esté explícitamente limitado a esa base.
+
+## Skills relacionadas
+
+- `base-datos-pubmed`
+- `evaluacion-academica`
+- `investigacion-profunda`