Chat Navigator

Chat Navigator - Navegação Conversacional Web

Skill para testar aplicações web de forma conversacional, usando Chrome DevTools MCP com linguagem natural em português.

Quando Usar

Use esta skill quando o usuário:

• Pedir para "navegar", "abrir", "testar" um site
• Quiser interagir com uma página web conversacionalmente
• Solicitar testes de UI/UX em linguagem natural
• Precisar verificar funcionalidades de forma exploratória

Exemplos:

• "Abra o localhost:3000 e clique no botão de login"
• "Navegue para o site e me diga o que tem na tela"
• "Teste o formulário de cadastro e veja se funciona"
• "Verifique se o chat está carregando corretamente"

Características

🗣️ Conversacional

• Aceita comandos em português natural
• Interpreta intenções do usuário
• Fornece feedback descritivo
• Faz perguntas quando necessário

🧠 Inteligente

• Consulta Neo4j por contexto histórico
• Aprende com testes anteriores
• Sugere ações baseadas no contexto
• Identifica padrões conhecidos

🔗 Integrado

• Usa hooks de validação automaticamente
• Respeita pre-browser-validation
• Registra aprendizados no Neo4j
• Compartilha contexto entre sessões

🎯 Focado em Testes

• Identifica elementos interativos
• Valida estados esperados
• Reporta erros claramente
• Captura evidências (screenshots, logs)

Fluxo de Uso

1. Navegação Inicial

Usuário diz: "Abra o localhost:3000"

Skill faz:

1. Validar URL (hook pre-browser-validation dispara)
2. Consultar Neo4j: "localhost:3000"
3. Abrir página: mcp__chrome-devtools__new_page
4. Tirar snapshot: mcp__chrome-devtools__take_snapshot
5. Descrever o que vê para o usuário
6. Sugerir próximas ações baseadas no contexto

Resposta exemplo:

✅ Navegado para http://localhost:3000/html/

📸 Página carregada:
- Título: "Claude Chat - Streaming Real"
- Status: 🟢 (conectado ao backend)

🧭 Toolbar de Navegação:
- ⟲ Projetos → index_projects.html
- 📁 Histórico → index_projects.html
- 📄 Outputs → output.html
- 📊 Audit → audit_dashboard.html

📝 Elementos principais:
- Campo de texto: textbox "Digite sua mensagem..."
- Botão "Enviar ➤"
- Botão "✨ Novo Chat"
- Botão "🔄" (atualizar)

💡 Sugestões:
- Testar enviar uma mensagem
- Ver arquivos em Outputs
- Verificar tool calls em Audit

2. Interação Conversacional

Usuário diz: "Digite 'olá mundo' e envie"

Skill faz:

1. Localizar campo de texto: textbox "Digite sua mensagem..."
2. Preencher: mcp__chrome-devtools__fill(uid="X", value="olá mundo")
3. Localizar botão: button "Enviar ➤"
4. Clicar: mcp__chrome-devtools__click(uid="Y")
5. Aguardar resposta: mcp__chrome-devtools__wait_for(text="📋", timeout=30000)
   (📋 é o botão de copiar que aparece quando resposta completa)
6. Tirar novo snapshot para ver resposta
7. Reportar resultado ao usuário

Indicadores de Estado:

• Durante processamento: "Claude está processando..." + timer + botão "Parar"
• Resposta completa: Botão "📋" (copiar) aparece na mensagem do Claude
• Botão enviar fica disabled durante processamento

3. Verificação e Validação

Usuário diz: "Verifique se funcionou"

Skill faz:

1. Analisar último snapshot
2. Verificar console logs (erros?)
3. Verificar network requests
4. Comparar estado esperado vs atual
5. Reportar sucesso ou falhas
6. Registrar resultado no Neo4j

Comandos Suportados

Navegação

• "Abra [URL]"
• "Navegue para [URL]"
• "Vá para [URL]"
• "Acesse [URL]"
• "Volte" / "Avance"
• "Recarregue a página"

Interação

• "Clique em [elemento]"
• "Clique no botão [nome]"
• "Digite [texto] no campo [nome]"
• "Preencha o formulário com [dados]"
• "Selecione [opção]"
• "Arraste [elemento] para [destino]"

Verificação

• "O que tem na tela?"
• "Mostre o que está aparecendo"
• "Verifique se [condição]"
• "Tem algum erro?"
• "O [elemento] está visível?"
• "Qual o status da conexão?"

Captura

• "Tire um screenshot"
• "Mostre os logs do console"
• "Quais requisições foram feitas?"
• "Me mostra o HTML do [elemento]"

Contexto

• "O que você sabe sobre este site?"
• "Já testamos isso antes?"
• "Qual o contexto histórico?"
• "Salve esta informação"

Padrões de Resposta

Sucesso

✅ [Ação] concluída com sucesso

📋 Resultado:
- [Detalhe 1]
- [Detalhe 2]

💡 Próximo passo sugerido: [sugestão]

Erro

❌ [Ação] falhou: [razão]

🔍 Detalhes:
- [Erro específico]
- [Contexto do erro]

💡 Sugestão: [como resolver]

Aguardando

⏳ Aguardando [condição]...

Informação

📊 [Título]

[Conteúdo estruturado]

💡 [Insights ou sugestões]

Integração com Neo4j

Consulta Antes de Navegar

Antes de navegar para uma URL, sempre:
1. Consultar: mcp__neo4j-memory__search_memories(query="[host]")
2. Analisar resultados
3. Incorporar contexto na resposta
4. Sugerir ações baseadas em histórico

Registro Após Testes

Após completar uma ação importante:
1. Identificar aprendizado
2. Criar observação no Neo4j
3. Conectar com entidades relevantes
4. Exemplo: "Botão de envio demora 2s para responder"

Tratamento de Erros

URL Inválida

❌ URL inválida ou inacessível

Verifique:
- Protocolo correto (http/https)
- Servidor está rodando?
- Porta correta?

💡 Use: lsof -i :[porta] para verificar

Elemento Não Encontrado

❌ Elemento "[nome]" não encontrado na página

🔍 Elementos disponíveis:
[Lista dos elementos visíveis]

💡 Talvez você quis dizer: "[sugestão]"

Timeout

⏸️ Timeout aguardando "[condição]"

A página pode estar:
- Carregando lentamente
- Com erro de JavaScript
- Sem resposta do backend

💡 Verificar console logs?

Melhores Práticas

1. Sempre Tirar Snapshot Primeiro

Antes de qualquer interação, capture o estado atual da página.

2. Aguardar Carregamentos

Use wait_for() após ações que causam mudanças assíncronas.

3. Verificar Console Logs

Após ações importantes, verifique se há erros no console.

4. Contexto Incremental

Mantenha contexto da sessão, não peça snapshot a cada comando trivial.

5. Feedback Contínuo

Sempre informe o usuário sobre o que está fazendo e o que encontrou.

6. Aprendizado Persistente

Registre padrões úteis no Neo4j para reusar em futuras sessões.

Exemplos Completos

Exemplo 1: Teste de Login

Usuário: "Teste o login no localhost:3000"

Skill:
1. 🔍 Consultando Neo4j...
   → localhost:3000 é o frontend do chat-simples
   → Backend em localhost:8001

2. 🌐 Navegando para http://localhost:3000...
   ✅ Página carregada

3. 📸 Analisando tela...
   → Status: 🟢 (conectado)
   → Campo de mensagem disponível
   → Botão "Enviar ➤" visível

4. ⚠️ Observação: Não encontrei formulário de login
   Este parece ser um chat direto, sem autenticação na UI.

💡 Quer que eu teste enviar uma mensagem?

Exemplo 2: Interação Completa

Usuário: "Envie a mensagem 'teste' e veja a resposta"

Skill:
1. ✍️ Digitando "teste" no campo de mensagem...
   ✅ Campo preenchido

2. 🖱️ Clicando em "Enviar ➤"...
   ✅ Botão clicado

3. ⏳ Aguardando resposta do backend...
   ✅ Resposta recebida em 1.2s

4. 📊 Verificando resultado...
   ✅ Mensagem apareceu na tela
   ✅ Resposta do Claude recebida
   ✅ Sem erros no console

5. 💾 Registrando no Neo4j...
   → "Chat responde em ~1.2s"
   → "Funcionalidade de envio OK"

✅ Teste completado com sucesso!

Páginas do Hello Agent (localhost:3000)

Estrutura de URLs

http://localhost:3000/html/
├── index.html           # Chat principal (RAG Agent)
├── index_projects.html  # Lista de sessões/projetos
├── output.html          # Arquivos gerados pela sessão
├── audit_dashboard.html # Dashboard de tool calls
└── session-viewer.html  # Visualizador de sessão específica

Elementos Comuns por Página

index.html (Chat):

• textbox "Digite sua mensagem..." - Campo de entrada
• button "Enviar ➤" - Enviar mensagem
• button "✨ Novo Chat" - Nova sessão
• StaticText "🟢" - Status conexão (🟢=ok, ⚫=offline)
• link "📄 Outputs" - Ir para outputs

index_projects.html (Projetos):

• link "⟲ Chat" - Voltar ao chat
• heading "🗂️ [projeto]" - Grupo de sessões
• StaticText "✨ Atual" - Sessão ativa
• button "🗑️" - Deletar sessão

output.html (Outputs):

• link "← Voltar ao Chat" - Voltar
• button "Atualizar" - Refresh lista
• Lista de arquivos com Download/Excluir

audit_dashboard.html (Audit):

• Cards: Total chamadas, Erros, Latência, Tools
• Gráfico de chamadas por tool
• Tabela com histórico de tool calls

Limitações

• Chrome apenas: Usa Chrome DevTools MCP
• Localhost preferível: Melhor para apps locais
• JavaScript necessário: SPAs funcionam melhor
• Sem multi-tab complexo: Foco em fluxo linear

Troubleshooting

"Hook não está funcionando"

• Verificar settings.local.json
• Confirmar que hook está habilitado
• Testar manualmente a validação

"Neo4j não retorna contexto"

• Verificar conexão: cypher-shell -u neo4j -p password
• Popular dados de teste
• Usar queries mais específicas

"Elementos não são encontrados"

• Tirar snapshot verbose: take_snapshot(verbose=true)
• Aguardar carregamento completo
• Verificar se página usa shadow DOM

Próximas Melhorias

• Suporte a múltiplas tabs simultâneas
• Gravação de sessões de teste
• Geração automática de scripts de teste
• Comparação visual com screenshots de referência
• Relatórios de teste estruturados

Modo 2: Validação RAG 🧪

Quando Usar

Valida a suite de testes do RAG Agent (test_all.py) no projeto hello-agent.

Comandos que ativam este modo:

• "Valide os testes RAG"
• "Execute test_all.py"
• "Verifique documentos.db"
• "Rode os testes do RAG Agent"
• "Teste o sistema RAG"

Funcionamento

1. Pré-validação: Verifica test_all.py e documentos.db existem
2. Execução: Roda test_all.py (6 módulos de teste)
3. Parse: Analisa output procurando [OK], [FAIL], [WARN]
4. Armazenamento: Salva resultado no Turso KvStore
5. Report: Apresenta status detalhado ao usuário

Módulos Testados

• Imports: Dependências (apsw, sqlite-vec, fastembed, mcp)
• Database: Banco documentos.db e embeddings
• FastEmbed: Modelo BAAI/bge-small-en-v1.5 (384D)
• Search: Busca semântica com similarity scores
• MCP Server: Ferramentas search_documents, get_document, etc
• Config: RAG_AGENT_OPTIONS e configuração

Exemplo de Uso

Usuário: "Valide os testes RAG"

Skill:
🔍 Iniciando validação RAG...

✅ Pré-validação OK
  - test_all.py encontrado
  - documentos.db acessível (11 docs)

🧪 Executando suite de testes...
  [1/6] imports ✓
  [2/6] database ✓
  [3/6] fastembed ✓
  [4/6] search ✓
  [5/6] mcp_server ✓
  [6/6] config ✓

✅ VALIDAÇÃO COMPLETA: 6/6 PASS

📊 Detalhes:
  • Banco: 11 docs, 11 embeddings
  • Modelo: BAAI/bge-small-en-v1.5 (384D)
  • MCP Tools: search_documents, get_document, list_sources, count_documents
  • Top search: "Politica_Uso_IA.docx" (87% similarity)

💾 Resultado salvo no Turso: rag_validation:1703350800

💡 Sistema 100% operacional! Pronto para responder consultas RAG.

Quando Falhas Ocorrem

Se testes falharem, o sistema:

1. Identifica módulos com falha
2. Classifica tipo de erro
3. Automaticamente ativa Modo 3 (Refatoração)
4. Tenta corrigir até 3 vezes

Modo 3: Refatoração Automática 🔧

Quando Usar

Ativado automaticamente quando Modo 2 detecta falhas, ou via comandos manuais:

• "Refatore automaticamente"
• "Corrija os testes RAG"
• "Aplique ruff --fix"
• "Tente corrigir automaticamente"

Funcionamento

1. Análise: Identifica testes falhando e classifica erros
2. Estratégia: Escolhe abordagem (ruff fix, import, syntax)
3. Aplicação: Executa ruff check --fix no código
4. Re-validação: Roda test_all.py novamente
5. Loop: Repete até passar ou max 3 tentativas

Tipos de Erro Suportados

Limitações

• Apenas erros sintáticos/formatação: Não corrige lógica complexa
• Max 3 tentativas: Evita loops infinitos
• Não instala pacotes: pip install requer confirmação manual
• Não modifica testes: Apenas código fonte (mcp_server, core/*)

Exemplo de Uso

Usuário: "Valide e corrija se necessário"

Skill:
🔍 Validando RAG...

❌ FALHAS DETECTADAS: 2/6

📋 Testes falhando:
  ❌ imports - ModuleNotFoundError: No module named 'mcp'
  ❌ config - AttributeError: 'Options' object has no attribute 'model'

🔧 REFATORAÇÃO AUTOMÁTICA ATIVADA

━━━ TENTATIVA 1/3 ━━━

🔍 Análise:
  → imports: Dependency 'mcp' não instalada
  → config: Typo em nome de atributo

🛠️ Aplicando correções...
  ✓ ruff check --fix config.py
  ✓ 1 arquivo corrigido: config.py

🧪 Re-validando...
  ✅ config: PASS agora!
  ❌ imports: ainda falhando (precisa instalar)

━━━ TENTATIVA 2/3 ━━━

💡 Estratégia: Erro requer pip install mcp

⚠️ AÇÃO MANUAL NECESSÁRIA:
   O erro "ModuleNotFoundError: No module named 'mcp'" requer:
   → pip install mcp

   Deseja que eu execute? [s/N]

Quando Desiste

Refatoração automática para quando:

• Atingiu max 3 tentativas
• Erro requer intervenção manual (logic, files)
• Nenhum arquivo foi modificado pelo ruff
• Situação piorou após tentativa

Nestes casos, reporta ao usuário e sugere próximos passos.

Integração Turso + Neo4j

Turso (KvStore)

Armazena resultados de validação para histórico:

# Estrutura salva
{
  "key": "rag_validation:1703350800",
  "value": {
    "status": "success",
    "passed": 6,
    "total": 6,
    "tests": {
      "teste_de_imports": "pass",
      "teste_de_banco_de_dados": "pass",
      ...
    },
    "timestamp": 1703350800
  }
}

Neo4j (Grafo)

Registra sessões de refatoração para análise histórica:

(RAGAgent)-[:HAD_SESSION]->(RefactoringSession {
  timestamp: 1703350800,
  attempts: 2,
  success: true,
  files_modified: ["config.py"],
  errors_fixed: ["AttributeError"]
})

Comandos Completos (Todos os Modos)

Modo 1: Navegação Web

• "Abra localhost:3000"
• "Clique em [elemento]"
• "Digite [texto]"
• "Tire um screenshot"

Modo 2: Validação RAG

• "Valide os testes RAG"
• "Execute test_all.py"
• "Verifique documentos.db"
• "Histórico de validações" (consulta Turso)

Modo 3: Refatoração

• "Refatore automaticamente" (ou ativação automática)
• "Corrija os testes falhando"
• "Aplique ruff --fix"

Como Ativar

Esta skill tem 3 modos operacionais ativados automaticamente:

Modo 1: Navegação Web (padrão)

Triggers: "abra", "navegue", "clique", "teste [site]"

Modo 2: Validação RAG (NOVO)

Triggers: "valide", "teste rag", "test_all", "documentos.db"

Modo 3: Refatoração (NOVO)

Triggers: Automático (quando Modo 2 falha) ou "refatore", "corrija"

Não use esta skill para:

• Leitura de código fonte
• Manipulação de arquivos locais
• Tarefas que não envolvem browser ou testes RAG