Plano de modernização de aplicações

# Objetivo

Mover a aplicação rumo a um produto mais limpo, rápido e sustentável, sem quebrar fluxos de trabalho atuais nem ocultar riscos em refatorações amplas. O trabalho deve ser entregue em fatias pequenas e revisáveis, com comprovação para cada superfície alterada.

# Princípios

• Preserve a arquitetura atual, a menos que um limite esteja comprovadamente causando retrabalho, custo de desempenho ou bugs visíveis ao usuário.
• Prefira o menor patch correto para cada problema, depois repita.
• Separe correções obrigatórias de polimentos opcionais para que mantenedores possam entregar trabalho de alto valor sem esperar por decisões subjetivas.
• Mantenha o comportamento voltado a Plugin documentado e compatível com versões anteriores.
• Verifique o comportamento publicado, os contratos de dependência e os testes antes de afirmar que uma regressão foi corrigida.
• Melhore primeiro o caminho principal do usuário: onboarding, autenticação, chat, configuração de provedor, gerenciamento de Plugin e diagnósticos.

# Fase 1: Auditoria de linha de base

Faça um inventário da aplicação atual antes de alterá-la.

• Identifique os principais fluxos de trabalho do usuário e as superfícies de código responsáveis por eles.
• Liste recursos mortos, configurações duplicadas, estados de erro pouco claros e caminhos de renderização caros.
• Capture os comandos de validação atuais para cada superfície.
• Marque problemas como obrigatórios, recomendados ou opcionais.
• Documente bloqueadores conhecidos que precisam de revisão de proprietário, especialmente mudanças de API, segurança, release e contrato de Plugin.

Definição de concluído:

• Uma lista de problemas com referências de arquivo relativas à raiz do repo.
• Cada problema tem severidade, superfície proprietária, impacto esperado ao usuário e um caminho de validação proposto.
• Nenhum item especulativo de limpeza é misturado às correções obrigatórias.

# Fase 2: Limpeza de produto e UX

Priorize fluxos de trabalho visíveis e remova confusão.

• Ajuste o texto de onboarding e estados vazios em torno de autenticação de modelo, status do Gateway e configuração de Plugin.
• Remova ou desabilite recursos mortos quando nenhuma ação for possível.
• Mantenha ações importantes visíveis em larguras responsivas, em vez de escondê-las atrás de suposições frágeis de layout.
• Consolide linguagem de status repetida para que erros tenham uma única fonte de verdade.
• Adicione divulgação progressiva para configurações avançadas, mantendo a configuração principal rápida.

Validação recomendada:

• Caminho feliz manual para configuração de primeira execução e inicialização de usuário existente.
• Testes focados para qualquer lógica de roteamento, persistência de configuração ou derivação de status.
• Capturas de tela do navegador para superfícies responsivas alteradas.

# Fase 3: Ajuste da arquitetura de frontend

Melhore a sustentabilidade sem uma reescrita ampla.

• Mova transformações repetidas de estado de UI para helpers tipados e estreitos.
• Mantenha separadas as responsabilidades de busca de dados, persistência e apresentação.
• Prefira hooks, stores e padrões de componentes existentes a novas abstrações.
• Divida componentes grandes demais apenas quando isso reduzir acoplamento ou esclarecer testes.
• Evite introduzir estado global amplo para interações locais de painel.

Proteções obrigatórias:

• Não altere comportamento público como efeito colateral de divisão de arquivos.
• Mantenha intacto o comportamento de acessibilidade para menus, diálogos, abas e navegação por teclado.
• Verifique se estados de carregamento, vazio, erro e otimistas ainda renderizam.

# Fase 4: Desempenho e confiabilidade

Ataque dores medidas em vez de otimização teórica ampla.

• Meça custos de inicialização, transição de rota, listas grandes e transcrições de chat.
• Substitua dados derivados caros e repetidos por seletores memoizados ou helpers em cache quando o profiling comprovar valor.
• Reduza varreduras evitáveis de rede ou sistema de arquivos em caminhos quentes.
• Mantenha ordenação determinística para entradas de prompt, registro, arquivo, Plugin e rede antes da construção do payload do modelo.
• Adicione testes leves de regressão para helpers quentes e limites de contrato.

Definição de concluído:

• Cada mudança de desempenho registra linha de base, impacto esperado, impacto real e lacuna restante.
• Nenhum patch de desempenho é entregue somente por intuição quando medição barata está disponível.

# Fase 5: Endurecimento de tipos, contratos e testes

Eleve a correção nos pontos de limite dos quais usuários e autores de Plugin dependem.

• Substitua strings soltas em runtime por uniões discriminadas ou listas fechadas de códigos.
• Valide entradas externas com helpers de schema existentes ou zod.
• Adicione testes de contrato em torno de manifestos de Plugin, catálogos de provedores, mensagens de protocolo do Gateway e comportamento de migração de configuração.
• Mantenha caminhos de compatibilidade em fluxos de doctor ou reparo, em vez de migrações ocultas em tempo de inicialização.
• Evite acoplamento apenas de teste a detalhes internos de Plugin; use fachadas do SDK e barrels documentados.

Validação recomendada:

• pnpm check:changed
• Testes direcionados para cada limite alterado.
• pnpm build quando limites lazy, empacotamento ou superfícies publicadas mudarem.

# Fase 6: Documentação e prontidão para release

Mantenha a documentação voltada ao usuário alinhada ao comportamento.

• Atualize a documentação com mudanças de comportamento, API, configuração, onboarding ou Plugin.
• Adicione entradas de changelog somente para mudanças visíveis ao usuário.
• Mantenha a terminologia de Plugin voltada ao usuário; use nomes internos de pacote somente quando necessário para contribuidores.
• Confirme que as instruções de release e instalação ainda correspondem à superfície atual de comandos.

Definição de concluído:

• Documentação relevante é atualizada na mesma branch das mudanças de comportamento.
• Verificações de documentação gerada ou drift de API passam quando tocadas.
• O handoff nomeia qualquer validação ignorada e por que ela foi ignorada.

# Primeira fatia recomendada

Comece com uma passagem escopada pela Control UI e pelo onboarding:

• Audite superfícies de configuração de primeira execução, prontidão de autenticação de provedor, status do Gateway e configuração de Plugin.
• Remova ações mortas e esclareça estados de falha.
• Adicione ou atualize testes focados para derivação de status e persistência de configuração.
• Execute pnpm check:changed.

Isso entrega alto valor ao usuário com risco limitado de arquitetura.

# Atualização da skill de frontend

Use esta seção para atualizar o SKILL.md focado em frontend fornecido com a tarefa de modernização. Se estiver adotando esta orientação como uma skill local do repo para OpenClaw, crie .agents/skills/openclaw-frontend/SKILL.md primeiro, mantenha o frontmatter que pertence a essa skill de destino e então adicione ou substitua a orientação do corpo pelo conteúdo a seguir.

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.