Plan de modernización de aplicaciones

​

Objetivo

​

Principios

• Preservar la arquitectura actual salvo que se demuestre que un límite causa rotación, coste de rendimiento o errores visibles para el usuario.
• Preferir el parche correcto más pequeño para cada problema y luego repetir.
• Separar las correcciones necesarias del pulido opcional para que los mantenedores puedan integrar trabajo de alto valor sin esperar decisiones subjetivas.
• Mantener documentado y compatible hacia atrás el comportamiento orientado a plugins.
• Verificar el comportamiento publicado, los contratos de dependencias y las pruebas antes de afirmar que una regresión está corregida.
• Mejorar primero la ruta principal del usuario: incorporación, autenticación, chat, configuración de proveedores, gestión de plugins y diagnósticos.

​

Fase 1: Auditoría de referencia

• Identificar los principales flujos de trabajo de usuario y las superficies de código que los poseen.
• Listar posibilidades de acción obsoletas, ajustes duplicados, estados de error poco claros y rutas de renderizado costosas.
• Capturar los comandos de validación actuales para cada superficie.
• Marcar los problemas como requeridos, recomendados u opcionales.
• Documentar los bloqueos conocidos que necesitan revisión del propietario, especialmente cambios de API, seguridad, release y contrato de plugins.

• Una lista de problemas con referencias de archivos desde la raíz del repo.
• Cada problema tiene severidad, superficie propietaria, impacto esperado en el usuario y una ruta de validación propuesta.
• No hay elementos de limpieza especulativa mezclados con correcciones requeridas.

​

Fase 2: Limpieza de producto y UX

• Ajustar el texto de incorporación y los estados vacíos en torno a la autenticación de modelos, el estado del gateway y la configuración de plugins.
• Eliminar o desactivar posibilidades de acción obsoletas donde no haya ninguna acción posible.
• Mantener visibles las acciones importantes en anchos responsivos en lugar de ocultarlas tras supuestos frágiles de maquetación.
• Consolidar el lenguaje de estado repetido para que los errores tengan una única fuente de verdad.
• Añadir divulgación progresiva para ajustes avanzados mientras se mantiene rápida la configuración básica.

• Ruta feliz manual para la configuración inicial y el arranque de usuarios existentes.
• Pruebas enfocadas para cualquier lógica de enrutamiento, persistencia de configuración o derivación de estado.
• Capturas de navegador para superficies responsivas modificadas.

​

Fase 3: Ajuste de arquitectura frontend

• Mover transformaciones repetidas de estado de UI a helpers tipados y estrechos.
• Mantener separadas las responsabilidades de obtención de datos, persistencia y presentación.
• Preferir hooks, stores y patrones de componentes existentes antes que nuevas abstracciones.
• Dividir componentes demasiado grandes solo cuando reduzca el acoplamiento o aclare las pruebas.
• Evitar introducir estado global amplio para interacciones locales de paneles.

• No cambiar el comportamiento público como efecto secundario de dividir archivos.
• Mantener intacto el comportamiento de accesibilidad para menús, diálogos, pestañas y navegación por teclado.
• Verificar que los estados de carga, vacío, error y optimistas sigan renderizándose.

​

Fase 4: Rendimiento y fiabilidad

• Medir los costes de arranque, transición de rutas, listas grandes y transcripciones de chat.
• Sustituir datos derivados costosos repetidos por selectores memorizados o helpers en caché cuando el perfilado demuestre valor.
• Reducir escaneos evitables de red o sistema de archivos en rutas calientes.
• Mantener un orden determinista para entradas de prompts, registros, archivos, plugins y red antes de construir payloads de modelo.
• Añadir pruebas de regresión ligeras para helpers calientes y límites de contrato.

• Cada cambio de rendimiento registra referencia, impacto esperado, impacto real y brecha restante.
• Ningún parche de rendimiento se integra solo por intuición cuando hay medición barata disponible.

​

Fase 5: Refuerzo de tipos, contratos y pruebas

• Sustituir cadenas de runtime laxas por uniones discriminadas o listas cerradas de códigos.
• Validar entradas externas con helpers de esquema existentes o zod.
• Añadir pruebas de contrato en torno a manifiestos de plugins, catálogos de proveedores, mensajes de protocolo del gateway y comportamiento de migración de configuración.
• Mantener las rutas de compatibilidad en flujos de doctor o reparación en lugar de migraciones ocultas durante el arranque.
• Evitar acoplamiento solo de pruebas a internos de plugins; usar fachadas del SDK y barrels documentados.

• pnpm check:changed
• Pruebas dirigidas para cada límite modificado.
• pnpm build cuando cambien límites lazy, empaquetado o superficies publicadas.

​

Fase 6: Documentación y preparación de release

• Actualizar la documentación con cambios de comportamiento, API, configuración, incorporación o plugins.
• Añadir entradas al changelog solo para cambios visibles para el usuario.
• Mantener la terminología de plugins orientada al usuario; usar nombres de paquetes internos solo cuando sea necesario para colaboradores.
• Confirmar que las instrucciones de release e instalación sigan coincidiendo con la superficie actual de comandos.

• La documentación relevante se actualiza en la misma rama que los cambios de comportamiento.
• Las comprobaciones de documentación generada o deriva de API pasan cuando se tocan.
• La entrega nombra cualquier validación omitida y por qué se omitió.

​

Primer segmento recomendado

• Auditar las superficies de configuración inicial, preparación de autenticación de proveedores, estado del gateway y configuración de plugins.
• Eliminar acciones obsoletas y aclarar estados de fallo.
• Añadir o actualizar pruebas enfocadas para derivación de estado y persistencia de configuración.
• Ejecutar pnpm check:changed.

​

Actualización de skill frontend

# Estándares de entrega frontend

Usa esta skill al implementar o revisar trabajo de UI orientado al usuario en React, Next.js,
webview de escritorio o aplicación.

## Reglas operativas

- Empieza desde el flujo de trabajo del producto existente y las convenciones de código.
- Prefiere el parche correcto más pequeño que mejore la ruta actual del usuario.
- Separa las correcciones requeridas del pulido opcional en la entrega.
- No construyas páginas de marketing cuando la solicitud sea para una superficie de aplicación.
- Mantén las acciones visibles y utilizables en los tamaños de viewport soportados.
- Elimina posibilidades de acción obsoletas en lugar de dejar controles que no pueden actuar.
- Preserva estados de carga, vacío, error, éxito y permisos.
- Usa componentes del sistema de diseño, hooks, stores e iconos existentes antes de añadir
  primitivas nuevas.

## Lista de implementación

1. Identifica la tarea principal del usuario y el componente o ruta que la posee.
2. Lee los patrones de componentes locales antes de editar.
3. Parchea la superficie más estrecha que resuelva el problema.
4. Añade restricciones responsivas para controles de formato fijo, barras de herramientas, cuadrículas y
   contadores para que el texto y los estados hover no puedan redimensionar la maquetación inesperadamente.
5. Mantén claras las responsabilidades de carga de datos, derivación de estado y renderizado.
6. Añade pruebas cuando cambien lógica, persistencia, enrutamiento, permisos o helpers compartidos.
7. Verifica la ruta feliz principal y el caso límite más relevante.

## Controles de calidad visual

- El texto debe caber dentro de su contenedor en móvil y escritorio.
- Las barras de herramientas pueden envolverse, pero los controles deben seguir siendo alcanzables.
- Los botones deberían usar iconos familiares cuando el icono sea más claro que el texto.
- Las cards deberían usarse para elementos repetidos, modales y herramientas enmarcadas, no para
  cada sección de página.
- Evita paletas de color monótonas y fondos decorativos que compitan con
  contenido operativo.
- Las superficies densas de producto deberían optimizarse para escaneo, comparación y uso
  repetido.

## Formato de entrega

Reporta:

- Qué cambió.
- Qué comportamiento de usuario cambió.
- Validación requerida que pasó.
- Cualquier validación omitida y la razón concreta.
- Trabajo de seguimiento opcional, separado claramente de las correcciones requeridas.