jarvis-ai-framework 2.1.1 → 3.2.0

package/skills/eng-automation/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: eng-automation
+description: >
+  Skill base de automação, válida em qualquer linguagem, biblioteca de coleta ou ferramenta de RPA:
+  fundamentos de automação, aquisição de dados, automação de navegador, scraping/crawling,
+  automação de APIs (REST/GraphQL/SOAP), webhooks e integração, RPA, extração de dados estruturados
+  e de documentos, ingestão de dados, CAPTCHA/anti-bot, limites de taxa e cortesia, agendamento e
+  orquestração, retentativa e tratamento de erros, autenticação/credenciais e observabilidade.
+  Pode ser complementada por especializações registradas em AUTOMATION_SPECIALIZATIONS.
+  Trigger: Use para RPA, web scraping, automação de browser, automação de APIs, extração de dados,
+  ingestão de dados ou qualquer automação de processo/fluxo de trabalho.
+license: AGPL-3.0
+compatibility: Designed for Claude Code (or similar products)
+allowed-tools: Read Write Edit Glob Grep Bash
+metadata:
+  author: jarvis-team
+  version: "1.0"
+  area: automation
+# Campos Claude Code-specific (não fazem parte da spec oficial agentskills.io):
+argument-hint: "[scraping|rpa|api|extracao|ingestao] [contexto]"
+disable-model-invocation: false
+---
+
+# Eng Automation - Skill Base de Automação
+
+Você é uma **pessoa especialista em automação sênior**, com domínio dos princípios que valem em qualquer linguagem, biblioteca de coleta ou ferramenta de RPA: aquisição de dados, automação de navegador e de APIs, extração, ingestão, resiliência e postura responsável diante de controles de acesso.
+
+## Objetivo
+
+Automatizar a obtenção, a extração e o movimento de dados e processos — da web e de APIs à interface de sistemas legados — de forma eficiente, resiliente e ética, aplicando a **base universal** de automação. Este skill não presume uma linguagem, biblioteca ou ferramenta de RPA: ele descobre o que o projeto já usa pelo próprio código e segue o padrão que encontra.
+
+## Entrada
+
+- `$ARGUMENTS` - URL, sistema ou tarefa de automação (ex: `scraper-precos-ecommerce`, `robo-login-portal`, `pipeline-ingestao-noticias`, `extrair-tabela-pdf`, `integrar-webhook-pagamento`)
+
+## Recursos
+
+- **ENV**: `$IDE/ENV.md` (variáveis de ambiente do projeto)
+- **Base universal**: os 16 temas em [references/](references/), carregados sob demanda
+- **Funções × skills**: [references/especializacoes.md](references/especializacoes.md) — peso por função (Data Acquisition, Web Automation, API Automation, RPA, Data Extraction, Data Ingestion, CAPTCHA & Anti-Bot Handling, Automation Engineering)
+- **Saída**: scripts, robôs e pipelines de automação no repositório atual
+
+---
+
+## Pré-requisito
+
+Verificar `robots.txt` e Terms of Service da fonte alvo ANTES de qualquer implementação que acesse a web:
+
+```bash
+curl -s "{url-alvo}/robots.txt"
+```
+
+Se houver restrições legais ou éticas significativas, comunicar ao usuário antes de prosseguir.
+
+---
+
+## Quando Usar
+
+Use este skill quando:
+- Extrair dados de páginas web, APIs ou documentos (preços, produtos, notícias, tabelas, PDFs)
+- Automatizar navegação em browsers (login, formulários, screenshots)
+- Automatizar chamadas a APIs REST/GraphQL/SOAP ou consumir/expor webhooks
+- Construir ou manter robôs de RPA sobre sistemas sem API
+- Construir pipelines de ingestão (lote, quase tempo real ou streaming)
+- Lidar com CAPTCHA, limites de taxa ou detecção de bot de forma responsável
+- Agendar, orquestrar ou tornar resiliente (retry, idempotência) uma automação existente
+
+**NÃO usar quando:**
+- A extração pode ser feita via API oficial — sempre preferir API sobre scraping/automação de UI
+- A fonte proíbe o acesso explicitamente e o caso de uso não é legítimo
+- A tarefa é de backend genérico sem aquisição, extração ou movimento de dados externos
+
+---
+
+## Validação de Entrada
+
+Se `$ARGUMENTS` está vazio, o skill funciona em modo interativo: pergunte à pessoa a fonte/sistema alvo, o tipo de dado ou processo e o formato de saída desejado — e verifique se existe API oficial antes de prosseguir com scraping ou automação de UI.
+
+---
+
+## Padrões Críticos
+
+### Padrão 1: Escolher a via mais estável
+
+```
+API oficial > exportação de dados > acesso direto autorizado > interface web > interação visual
+```
+
+Suba na hierarquia sempre que possível; cada nível abaixo é mais frágil e mais caro de manter.
+
+### Padrão 2: Fragilidade é a regra — projete para detectar e se adaptar
+
+- Nunca confiar que a estrutura de uma fonte (HTML, schema, layout de documento) é estável
+- Logar estruturas inesperadas para detectar mudanças antes que silenciosamente corrompam dados
+- Validar dados extraídos contra o formato esperado; quarentena para o que não valida
+
+### Padrão 3: Idempotência e reprocessamento em tudo que roda sozinho
+
+- Toda automação agendada deve poder reprocessar o mesmo período sem duplicar efeito
+- Checkpoints e chaves de idempotência em pipelines de ingestão e em robôs de RPA
+
+### Padrão 4: Postura responsável diante de controles de acesso
+
+Esta base ensina a **detectar, respeitar e escalar** diante de CAPTCHAs, limites de taxa e detecção de bot. Ela **não** ensina a burlá-los — um controle de acesso é decisão do dono do serviço:
+
+- Rate limiting e delays — nunca sobrecarregar o alvo
+- Se bloqueado: não contornar silenciosamente — avisar o usuário e buscar via oficial ou acordo
+- Dados pessoais exigem atenção especial (LGPD/GDPR) mesmo quando publicamente acessíveis
+
+### Padrão 5: Automação tem dono
+
+- Credenciais mínimas necessárias, cofre de segredos, rotação e trilha de auditoria
+- Humano no laço onde o risco ou a incerteza forem altos
+- Toda automação tem plano de desligamento — não é "configurar e esquecer"
+
+---
+
+## Base ou especialização?
+
+Pergunta-chave para decidir onde um conhecimento mora:
+
+> **Isso continua válido se eu trocar de linguagem, de biblioteca de coleta ou de ferramenta de RPA?**
+> **Sim** → pertence à base universal (este skill). **Não** → pertence a uma especialização de ferramenta.
+
+---
+
+## Árvore de Decisão
+
+```
+Decidir o que e como automatizar?             → tema 1 (fundamentos de automação)
+Definir a via de aquisição de uma fonte?      → tema 2 (aquisição de dados)
+Automatizar navegador (login, forms, DOM)?    → tema 3 (automação de navegador)
+Scraping, crawling ou extração web?           → tema 4 (scraping, crawling e extração web)
+Automatizar API REST/GraphQL/SOAP?            → tema 5 (automação de APIs)
+Consumir ou expor webhooks?                   → tema 6 (webhooks e integração)
+Construir robô de RPA sobre sistema legado?   → tema 7 (RPA e automação de processos)
+Extrair dados estruturados/semiestruturados?  → tema 8 (extração de dados estruturados)
+Extrair de PDF, imagem ou e-mail (OCR)?       → tema 9 (extração de documentos)
+Construir pipeline de ingestão?               → tema 10 (ingestão de dados)
+Lidar com CAPTCHA ou detecção de bot?         → tema 11 (CAPTCHA e anti-bot)
+Ajustar rate limiting, sessão ou cortesia?    → tema 12 (limites de taxa, sessões e cortesia)
+Agendar ou orquestrar execuções?              → tema 13 (agendamento e orquestração)
+Tratar erro, retry ou recuperação?            → tema 14 (retentativa e tratamento de erros)
+Gerenciar credenciais ou autenticação?        → tema 15 (autenticação e gestão de credenciais)
+Instrumentar logs/métricas de uma automação?  → tema 16 (observabilidade e confiabilidade)
+```
+
+---
+
+## Fluxo de Trabalho
+
+1. **Avaliar ética e viabilidade**: existe API oficial? `robots.txt`/ToS permitem? dados são pessoais?
+2. **Entender a fonte/sistema**: ler o que o projeto já usa (ferramenta, convenções, pipelines existentes)
+3. **Escolher a via mais estável** (Padrão 1) e projetar para resiliência (Padrão 2)
+4. **Implementar**: rate limiting, retry com backoff, validação de dados extraídos
+5. **Validar**: testar com amostra real e confirmar detecção de mudança de estrutura
+
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
+---
+
+## Base Universal
+
+Carregue **só o tema necessário** para a tarefa, em vez de todos de uma vez.
+
+| # | Tema | Nível | Carregue quando |
+|---|------|-------|-----------------|
+| 1 | [Fundamentos de automação](references/1-fundamentos-automacao.md) | Fundamental | Decidir o quê, por qual via e com que supervisão automatizar |
+| 2 | [Aquisição de dados](references/2-aquisicao-dados.md) | Fundamental | Escolher fonte, hierarquia de vias, permissões e proveniência |
+| 3 | [Automação de navegador](references/3-automacao-navegador.md) | Importante | Lidar com DOM, seletores estáveis, esperas, estado e evidências |
+| 4 | [Scraping, crawling e extração web](references/4-scraping-crawling.md) | Importante | Rastrear, gerenciar fronteira de URLs, cortesia, mudança de layout |
+| 5 | [Automação de APIs: REST, GraphQL e SOAP](references/5-apis-rest-graphql-soap.md) | Fundamental | Lidar com contratos, paginação, idempotência, erros, evolução |
+| 6 | [Webhooks e integração entre sistemas](references/6-webhooks-integracao.md) | Importante | Decidir push vs. polling, assinatura, duplicidade, padrões de integração |
+| 7 | [RPA e automação de processos](references/7-rpa.md) | Importante | Decidir quando usar, mapear processo, robôs, exceções, governança |
+| 8 | [Extração de dados estruturados e semiestruturados](references/8-extracao-estruturada.md) | Fundamental | Lidar com formatos, esquema, codificação, validação, quarentena |
+| 9 | [Extração de documentos e dados não estruturados](references/9-extracao-documentos.md) | Importante | OCR, layout, modelos, confiança, revisão humana, e-mail |
+| 10 | [Ingestão de dados](references/10-ingestao-dados.md) | Fundamental | Projetar lote, quase tempo real, streaming, eventos, garantias |
+| 11 | [CAPTCHA e anti-bot: postura responsável](references/11-captcha-antibot.md) | Fundamental | Detectar, respeitar, escalar a humano, buscar via oficial |
+| 12 | [Limites de taxa, sessões e cortesia](references/12-limites-taxa-sessoes.md) | Fundamental | Lidar com 429, Retry-After, throttle, cache condicional, sessões |
+| 13 | [Agendamento e orquestração](references/13-agendamento-orquestracao.md) | Importante | Definir gatilhos, dependências, execuções perdidas, backfill |
+| 14 | [Retentativa, recuperação e tratamento de erros](references/14-retentativa-erros.md) | Fundamental | Classificar erros, aplicar backoff, idempotência, checkpoints |
+| 15 | [Autenticação e gestão de credenciais](references/15-autenticacao-credenciais.md) | Fundamental | Contas de serviço, OAuth, cofre, rotação, MFA oficial |
+| 16 | [Observabilidade e confiabilidade de automações](references/16-observabilidade-confiabilidade.md) | Fundamental | Logs, métricas, auditoria, detecção de mudança na fonte |
+
+---
+
+## Funções e Peso por Área
+
+Automação reúne várias áreas (Data Acquisition, Web Automation, API Automation, RPA, Data Extraction, Data Ingestion, CAPTCHA & Anti-Bot Handling, Automation Engineering) que partem da mesma base, mas pesam os 16 temas de forma diferente. Ver [references/especializacoes.md](references/especializacoes.md) para o núcleo (●) e o apoio (○) esperado de cada área.
+
+> Segurança de credenciais e de dados em profundidade fica na skill base de Platform (segurança) e na skill base de Data (segurança e privacidade) — esta base cobre o essencial (tema 15) para a automação em si.
+
+---
+
+## Regras
+
+### Nunca
+- Ignorar `robots.txt`/ToS sem avaliar o contexto de uso com o usuário
+- Automatizar de forma agressiva (sem rate limiting), causando impacto no alvo
+- Coletar dados pessoais sem finalidade legítima e base legal (LGPD/GDPR)
+- Assumir que a estrutura de uma fonte é estável — sempre validar
+- Burlar CAPTCHA ou mecanismo anti-bot — escalar a humano ou buscar via oficial
+- Expor credenciais de automação em código, logs ou configs versionadas
+
+### Sempre
+- Preferir API oficial a scraping ou automação de UI
+- Verificar `robots.txt`/ToS antes de implementar acesso à web
+- Rate limiting e backoff para não sobrecarregar o alvo
+- Validar dados extraídos e detectar mudança de estrutura da fonte
+- Tratar erros com retry e idempotência em tudo que roda sozinho
+- Registrar logs e métricas suficientes para diagnosticar falha sem acesso ao ambiente
+
+---
+
+## Tratamento de Erros
+
+### Fonte bloqueando acesso (403/429/CAPTCHA)
+- Aumentar delay e revisar rate limiting antes de qualquer outra mudança
+- Se persistir: comunicar ao usuário — pode ser proteção legítima; buscar via oficial
+
+### Estrutura da fonte mudou (dados vazios ou incorretos)
+- Logar amostra do que foi recebido para inspecionar
+- Adicionar validação que detecte essa classe de mudança automaticamente da próxima vez
+
+### Falha transitória de rede ou timeout
+- Aplicar retry com backoff exponencial e jitter
+- Confirmar que a operação é idempotente antes de repetir
+
+---
+
+## Checklist de Conclusão
+
+- [ ] `robots.txt`/ToS verificados (quando a fonte for web)
+- [ ] API oficial descartada como alternativa, com justificativa
+- [ ] Rate limiting e backoff implementados
+- [ ] Dados validados contra o formato esperado, com quarentena para o que não valida
+- [ ] Idempotência garantida em qualquer automação agendada/recorrente
+- [ ] Credenciais fora do código, com rotação definida
+- [ ] Logs e métricas mínimas para diagnosticar falha remotamente
+
+---
+
+## Output
+
+| Artefato | Descrição |
+|----------|-----------|
+| Script/robô de automação | Extração, navegação ou RPA com retry, rate limiting e validação |
+| Pipeline de ingestão | Aquisição → transformação → carga, com idempotência |
+| Monitor de mudança | Detecção estruturada de mudança na fonte |
+
+---
+
+## Mensagem de Conclusão
+
+```
+Automação implementada!
+
+Fonte/sistema: {descrição da fonte ou sistema alvo}
+Via escolhida: {API oficial / exportação / acesso direto / web / interação visual}
+
+Resiliência: {rate limiting, retry e validação aplicados}
+Credenciais: {cofre/rotação configurados}
+
+Próximo passo: {executar com amostra real / agendar / integrar no pipeline}
+```
+
+---
+
+## Aviso: uso só da skill base
+
+Quando o trabalho usar **só a skill base** e envolver uma linguagem, biblioteca ou ferramenta de RPA para a qual **não há skill especializado** disponível, avise a pessoa de forma explícita:
+
+```
+ℹ️ Estou usando só a skill base de automação.
+   Não há skill especializado para {ferramenta}; vou seguir os princípios universais
+   e o padrão que encontrei no projeto.
+```
+
+Não invente convenções nem comandos específicos da ferramenta: siga o código do projeto e a base universal.
+
+---
+
+## Recursos Adicionais
+
+- **Base universal**: os 16 temas em [references/](references/)
+- **Funções × skills**: [references/especializacoes.md](references/especializacoes.md)

package/skills/eng-automation/references/1-fundamentos-automacao.md

@@ -0,0 +1,25 @@
+# 1. Fundamentos de Automação
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Decidir o que automatizar, por qual via e com que nível de supervisão humana.
+
+**Conhecimentos:** camadas de automação: dados/API > integração de sistemas > interface > interação visual; custo-benefício e retorno; mapear e simplificar o processo antes de automatizar; determinismo e idempotência; fragilidade e custo de manutenção; níveis de automação e papel do humano; tarefa vs. processo; segurança, conformidade e responsabilização; toil; critérios para não automatizar; dívida de automação.
+
+**Princípios:**
+- Prefira a camada mais estável e de menor acoplamento.
+- Automatizar um processo ruim apenas o torna rápido e ruim.
+- Toda automação tem dono, manutenção e plano de desligamento.
+
+**Fora do escopo:** plataformas e ferramentas específicas de automação.
+
+**Pergunta-chave:** Se a fonte mudar amanhã, quem percebe, quanto custa corrigir e quem responde pelo resultado?
+
+**Referências:**
+- Bainbridge, *Ironies of Automation* (Automatica, 1983)
+- Parasuraman, Sheridan & Wickens, *A Model for Types and Levels of Human Interaction with Automation* (IEEE SMC-A, 2000)
+- Beyer et al., *Site Reliability Engineering*, cap. 5 (Eliminating Toil)
+- Hohpe & Woolf, *Enterprise Integration Patterns*
+- Dumas et al., *Fundamentals of Business Process Management*
+
+**Usam mais:** todas as áreas

package/skills/eng-automation/references/10-ingestao-dados.md

@@ -0,0 +1,25 @@
+# 10. Ingestão de Dados
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Trazer dados ao destino com a latência, a garantia e o custo adequados ao uso.
+
+**Conhecimentos:** lote, quase tempo real, fluxo contínuo e baseado em eventos; latência vs. vazão vs. custo; carga completa vs. incremental; marcas d'água e captura de mudanças (CDC); semântica de entrega: no máximo uma, ao menos uma, efeito exatamente uma vez; idempotência e deduplicação; ordem, janelas e dados tardios; contrapressão e buffers; filas, logs e reprocessamento; evolução de esquema; falhas parciais e filas de mensagens mortas; reconciliação com a fonte.
+
+**Princípios:**
+- Escolha a latência que o negócio precisa, não a menor possível.
+- Projete para reprocessar.
+- 'Exatamente uma vez' é efeito de idempotência, não mágica.
+
+**Fora do escopo:** motores de processamento e brokers específicos.
+
+**Pergunta-chave:** Se a ingestão falhar às 3h e reiniciar às 5h, o destino fica correto, incompleto ou duplicado?
+
+**Referências:**
+- Akidau et al., *The Dataflow Model* (VLDB, 2015)
+- Akidau, Chernyak & Lax, *Streaming Systems*
+- Kleppmann, *Designing Data-Intensive Applications*
+- Kreps, *The Log: What every software engineer should know about real-time data's unifying abstraction* (2013)
+- Reis & Housley, *Fundamentals of Data Engineering*
+
+**Usam mais:** Data Ingestion, Data Acquisition, Automation Engineering

package/skills/eng-automation/references/11-captcha-antibot.md

@@ -0,0 +1,25 @@
+# 11. CAPTCHA e Anti-bot: Postura Responsável
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Lidar com CAPTCHAs e detecção de bots detectando, respeitando e escalando, sem contornar o controle.
+
+**Conhecimentos:** finalidade e tipos de CAPTCHA: texto ou imagem, pontuação de risco, desafios invisíveis, prova de trabalho; como serviços detectam automação (conceito): taxa, padrões de acesso, reputação, sinais do cliente; detectar um desafio e interromper com segurança; humano no laço: fila de intervenção e retomada; alternativas oficiais: API, parceria, exportação, feed, acordo de acesso; termos de uso e consentimento; tratamento de falha: recuo, alerta, fonte marcada como bloqueada; registro do evento e decisão de negócio; se a fonte não permite automação, não automatize.
+
+**Princípios:**
+- CAPTCHA indica que o dono do serviço não quer acesso automatizado ali: trate como limite, não como obstáculo técnico.
+- Antes de qualquer tentativa técnica, pergunte se existe via oficial.
+- Falha explícita e escalada valem mais que sucesso obtido contornando controles.
+
+**Fora do escopo:** técnicas e serviços para burlar CAPTCHAs ou evadir detecção de bots.
+
+**Pergunta-chave:** A automação encontrou um desafio: ela para, avisa quem e qual alternativa oficial existe?
+
+**Referências:**
+- von Ahn et al., *CAPTCHA: Using Hard AI Problems for Security* (EUROCRYPT 2003)
+- OWASP, *Automated Threats to Web Applications*
+- W3C, *Inaccessibility of CAPTCHA* (Nota do grupo de trabalho)
+- RFC 9309 (Robots Exclusion Protocol)
+- Parasuraman, Sheridan & Wickens (2000), humano no laço
+
+**Usam mais:** CAPTCHA & Anti-Bot, Web Automation, RPA, Data Acquisition

package/skills/eng-automation/references/12-limites-taxa-sessoes.md

@@ -0,0 +1,25 @@
+# 12. Limites de Taxa, Sessões e Cortesia
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Respeitar a capacidade das fontes e manter sessões corretas, estáveis e seguras.
+
+**Conhecimentos:** limitação de taxa: janela fixa e deslizante, token bucket, leaky bucket; respostas 429 e Retry-After; limitação no cliente (throttle) e concorrência controlada; recuo e cortesia por host; cache e requisições condicionais (ETag, If-Modified-Since); cotas do provedor e custo por chamada; sessões: cookies, tokens, expiração e renovação; isolamento de sessão por identidade; logout e invalidação; estado entre execuções; rejeição de sessões compartilhadas inseguras.
+
+**Princípios:**
+- Seu limite de taxa deve ser menor que o da fonte.
+- Peça menos: cache e condicionais reduzem carga e custo.
+- Sessão expirada é caso normal, não exceção.
+
+**Fora do escopo:** parâmetros de limites de serviços específicos.
+
+**Pergunta-chave:** Ao receber 429, a automação espera o tempo indicado ou insiste?
+
+**Referências:**
+- RFC 6585 (429 Too Many Requests)
+- RFC 9110 (condicionais e Retry-After)
+- RFC 6265 (cookies)
+- OWASP, *Session Management Cheat Sheet*
+- Beyer et al., *Site Reliability Engineering*, cap. 21 (Handling Overload)
+
+**Usam mais:** CAPTCHA & Anti-Bot, Web Automation, API Automation, Automation Engineering

package/skills/eng-automation/references/13-agendamento-orquestracao.md

@@ -0,0 +1,24 @@
+# 13. Agendamento e Orquestração
+
+**Nível:** IMPORTANTE · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Disparar e encadear automações no momento certo, com dependências explícitas.
+
+**Conhecimentos:** gatilhos: tempo, evento, arquivo, dependência, manual; expressões de agenda, fusos e horário de verão; grafo de dependências (DAG) e ordem de execução; execução atrasada, perdida ou sobreposta; janelas de dados e reprocessamento (backfill); filas de trabalho e paralelismo; prioridade e limites de recursos; versionamento e promoção de fluxos; idempotência por execução; parada e retomada; calendário de negócio (feriados).
+
+**Princípios:**
+- Toda execução tem identidade e janela de dados definidas.
+- Duas execuções simultâneas não podem corromper o resultado.
+- Todo horário agendado declara o fuso.
+
+**Fora do escopo:** agendadores e orquestradores específicos.
+
+**Pergunta-chave:** Se o agendador ficar fora por 6 horas, o que roda ao voltar e em que ordem?
+
+**Referências:**
+- Beyer et al., *Site Reliability Engineering*, cap. 24 (Distributed Periodic Scheduling with Cron)
+- Reis & Housley, *Fundamentals of Data Engineering* (orquestração)
+- Burns, *Designing Distributed Systems*
+- Kleppmann, *Designing Data-Intensive Applications* (processamento em lote)
+
+**Usam mais:** Automation Engineering, Data Ingestion, RPA

package/skills/eng-automation/references/14-retentativa-erros.md

@@ -0,0 +1,25 @@
+# 14. Retentativa, Recuperação e Tratamento de Erros
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Falhar de modo previsível e se recuperar sem duplicar efeitos nem esconder problemas.
+
+**Conhecimentos:** erros transitórios, permanentes, de negócio e de dados; repetição com recuo exponencial e jitter; limite de tentativas e orçamento de repetição; idempotência e chaves de deduplicação; disjuntor (circuit breaker); pontos de verificação e retomada parcial; compensação (sagas); filas de mensagens mortas e reprocessamento manual; timeouts em tudo; mensagens de erro acionáveis; fonte alterada vs. falha de infraestrutura.
+
+**Princípios:**
+- Só repita o que é seguro repetir.
+- Retry sem limite e sem jitter amplifica a falha.
+- Erro engolido é incidente adiado.
+
+**Fora do escopo:** bibliotecas de repetição e resiliência.
+
+**Pergunta-chave:** A etapa 3 de 5 falha depois de gravar na etapa 2: o que acontece ao repetir?
+
+**Referências:**
+- Nygard, *Release It!* (2ª ed.)
+- Brooker, *Exponential Backoff and Jitter* (2015)
+- Garcia-Molina & Salem, *Sagas* (SIGMOD 1987)
+- Helland, *Idempotence Is Not a Medical Condition* (ACM Queue, 2012)
+- Beyer et al., *Site Reliability Engineering*, cap. 22 (Addressing Cascading Failures)
+
+**Usam mais:** Automation Engineering, API Automation, Data Ingestion, RPA

package/skills/eng-automation/references/15-autenticacao-credenciais.md

@@ -0,0 +1,24 @@
+# 15. Autenticação e Gestão de Credenciais
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Autenticar automações com o menor privilégio e sem expor segredos.
+
+**Conhecimentos:** contas de serviço vs. credenciais de pessoas; fluxos de autorização (credenciais de cliente, código com PKCE, tokens de atualização); chaves de API, certificados e mTLS; escopo mínimo e expiração; cofre de segredos e rotação; segredos fora de código, logs e capturas de tela; MFA em fluxos automatizados: mecanismos aprovados pelo provedor; renovação de token no meio da execução; identidade por robô para auditoria; revogação e resposta a vazamento; separação por ambiente.
+
+**Princípios:**
+- Nunca compartilhe credenciais de pessoas com automações.
+- Vida curta, escopo estreito, rotação automática.
+- Se o provedor exige MFA para a automação, peça um mecanismo oficial; não o contorne.
+
+**Fora do escopo:** cofres, provedores de identidade e protocolos proprietários.
+
+**Pergunta-chave:** Se o segredo desta automação vazasse hoje, o que seria alcançado e como você o revogaria?
+
+**Referências:**
+- RFC 6749 (OAuth 2.0), RFC 6750 e RFC 7636 (PKCE)
+- NIST SP 800-63B (autenticação)
+- NIST SP 800-57 (gestão de chaves)
+- OWASP, *Secrets Management Cheat Sheet*
+
+**Usam mais:** Automation Engineering, API Automation, RPA, Web Automation

package/skills/eng-automation/references/16-observabilidade-confiabilidade.md

@@ -0,0 +1,24 @@
+# 16. Observabilidade e Confiabilidade de Automações
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Saber se as automações funcionam, se os dados estão corretos e quando as fontes mudam.
+
+**Conhecimentos:** logs estruturados com identificador de execução; taxa de sucesso, duração, volume, atraso e frescor; rastreamento ponta a ponta; trilha de auditoria, inclusive de intervenção humana; alertas por sintoma (SLO), não por ruído; detecção de mudança na fonte: esquema, layout, volume; verificações pós-execução: contagem, completude, anomalia; painéis de saúde e de custo; monitores canário contra as fontes; dono, runbook e revisão de incidentes.
+
+**Princípios:**
+- Sucesso do processo não é sucesso do dado: valide o resultado.
+- Detecte a mudança na fonte antes do consumidor.
+- Toda automação tem dono, runbook e alerta.
+
+**Fora do escopo:** ferramentas de monitoramento e painéis específicos.
+
+**Pergunta-chave:** Como você sabe, sem ninguém avisar, que a automação de ontem rodou e entregou dados corretos?
+
+**Referências:**
+- Beyer et al., *Site Reliability Engineering*, cap. 6
+- Majors, Fong-Jones & Miranda, *Observability Engineering*
+- Moses, Gavish & Vorwerck, *Data Quality Fundamentals*
+- Especificação OpenTelemetry
+
+**Usam mais:** Automation Engineering, todas as áreas

package/skills/eng-automation/references/2-aquisicao-dados.md

@@ -0,0 +1,25 @@
+# 2. Aquisição de Dados
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Escolher, para cada necessidade, a fonte e a via de acesso mais estáveis, legítimas e baratas.
+
+**Conhecimentos:** tipos de fonte: web, APIs, bancos, arquivos, documentos, e-mail, sistemas externos; hierarquia de vias: acordo ou API oficial, exportação ou feed, acesso direto autorizado, e só então extração de interface; termos de uso e contratos de acesso; direitos sobre conteúdo e bases de dados; dados pessoais e base legal; proveniência e linhagem; frequência, volume e custo; qualidade da fonte; credenciais com escopo mínimo; plano de contingência para fonte que muda ou fecha.
+
+**Princípios:**
+- Pergunte primeiro se existe via oficial; extrair da interface é último recurso e não dispensa obrigações.
+- Registre de onde cada dado veio e sob que permissão.
+- Colete o mínimo necessário.
+
+**Fora do escopo:** interpretação jurídica específica e conectores proprietários.
+
+**Pergunta-chave:** Com que permissão e por qual via você obtém este dado, e o que acontece se ela deixar de existir?
+
+**Referências:**
+- DAMA International, *DAMA-DMBOK2*
+- Reis & Housley, *Fundamentals of Data Engineering*
+- RFC 9309 (Robots Exclusion Protocol)
+- Lei nº 13.709/2018 (LGPD) e Regulamento (UE) 2016/679
+- Lei nº 9.610/1998 e Diretiva 96/9/CE (direitos autorais e bases de dados)
+
+**Usam mais:** Data Acquisition, Data Extraction, Data Ingestion, Web

package/skills/eng-automation/references/3-automacao-navegador.md

@@ -0,0 +1,24 @@
+# 3. Automação de Navegador
+
+**Nível:** IMPORTANTE · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Controlar navegadores de forma estável para fluxos que só existem na interface web.
+
+**Conhecimentos:** HTML, DOM e renderização por JavaScript; páginas estáticas vs. dinâmicas; protocolo de controle de navegador (WebDriver); seletores estáveis (semântica, papéis acessíveis) vs. frágeis (posição, classes geradas); esperas por condição, não por tempo fixo; estado: cookies, armazenamento local, perfis isolados; navegador sem interface e suas diferenças; iframes, janelas, downloads e uploads; evidências: capturas de tela e rastros; isolamento e limpeza entre execuções; testabilidade acordada com o dono do site.
+
+**Princípios:**
+- Espere por condição, não por segundos.
+- Seletor ancorado em semântica sobrevive a redesenho.
+- Navegador é último recurso quando existe API ou dado estruturado.
+
+**Fora do escopo:** bibliotecas e drivers específicos.
+
+**Pergunta-chave:** Este fluxo realmente exige um navegador ou existe a chamada de rede que ele faz por trás?
+
+**Referências:**
+- W3C, *WebDriver* (Recomendação)
+- WHATWG, *HTML Living Standard* e *DOM Standard*
+- W3C, *WAI-ARIA* (papéis e árvore de acessibilidade)
+- Fowler, *PageObject*
+
+**Usam mais:** Web Automation, RPA (navegador), Data Acquisition

package/skills/eng-automation/references/4-scraping-crawling.md

@@ -0,0 +1,25 @@
+# 4. Scraping, Crawling e Extração Web
+
+**Nível:** IMPORTANTE · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Coletar páginas e extrair conteúdo em escala, respeitando as regras do site e a carga que se causa.
+
+**Conhecimentos:** scraping (extrair) vs. crawling (descobrir e percorrer) vs. spiders (agentes de rastreamento); fronteira de URLs, profundidade e priorização; normalização e deduplicação de URLs; sitemaps e links canônicos; paginação, rolagem infinita e carregamento incremental; robots.txt como convenção; cortesia: intervalo, concorrência por host, identificação clara do agente; cache e requisições condicionais; extração por seletores e por dados estruturados embutidos; detecção de mudança de layout; guardar o HTML bruto para reprocessar.
+
+**Princípios:**
+- Armazene o bruto, extraia depois.
+- Rastreie como bom cidadão: identifique-se e limite a carga.
+- A extração deve falhar alto quando o layout muda.
+
+**Fora do escopo:** frameworks de rastreamento e técnicas para ocultar a identidade do agente.
+
+**Pergunta-chave:** Se o site mudar o HTML hoje, você descobre pelo monitoramento ou pelo cliente?
+
+**Referências:**
+- Olston & Najork, *Web Crawling* (Foundations and Trends in IR, 2010)
+- Manning, Raghavan & Schütze, *Introduction to Information Retrieval*, cap. 20
+- Heydon & Najork, *Mercator: A Scalable, Extensible Web Crawler* (1999)
+- RFC 9309 (Robots Exclusion Protocol)
+- W3C, *JSON-LD 1.1*; Schema.org
+
+**Usam mais:** Web Automation, Data Extraction, Data Acquisition

package/skills/eng-automation/references/5-apis-rest-graphql-soap.md

@@ -0,0 +1,26 @@
+# 5. Automação de APIs: REST, GraphQL e SOAP
+
+**Nível:** FUNDAMENTAL · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Consumir APIs de qualquer estilo com correção, resiliência e baixo acoplamento.
+
+**Conhecimentos:** REST: recursos, métodos, status, idempotência, cache, hipermídia; GraphQL: esquema, consultas, mutações, limites de complexidade, N+1; SOAP: envelope, WSDL, XML e segurança de mensagens (conceito); paginação por deslocamento e por cursor; filtros e ordenação; versionamento e evolução; especificações de contrato (OpenAPI, esquema GraphQL, WSDL); formatos padronizados de erro; polling vs. notificação; tolerância a campos novos; limites e cotas do provedor; testes contra o contrato.
+
+**Princípios:**
+- Leia o contrato; não infira comportamento a partir de exemplos.
+- Seja tolerante no que recebe e rigoroso no que envia.
+- Idempotência decide se uma chamada pode ser repetida.
+
+**Fora do escopo:** SDKs e clientes de API específicos.
+
+**Pergunta-chave:** Se a chamada for repetida por falha de rede, o efeito acontece uma ou duas vezes?
+
+**Referências:**
+- Fielding, *Architectural Styles and the Design of Network-based Software Architectures* (2000)
+- RFC 9110 (HTTP Semantics)
+- GraphQL Foundation, *GraphQL Specification*
+- W3C, *SOAP 1.2* e *WSDL 2.0*
+- RFC 9457 (Problem Details for HTTP APIs)
+- OpenAPI Specification
+
+**Usam mais:** API Automation, Data Acquisition, Data Ingestion

package/skills/eng-automation/references/6-webhooks-integracao.md

@@ -0,0 +1,25 @@
+# 6. Webhooks e Integração entre Sistemas
+
+**Nível:** IMPORTANTE · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Integrar sistemas por eventos e notificações de forma segura e tolerante a falhas.
+
+**Conhecimentos:** push (webhook) vs. polling; receptor: resposta rápida e processamento assíncrono; autenticidade: assinatura (HMAC), timestamp, proteção contra replay; entrega ao menos uma vez, duplicidade e idempotência; ordem não garantida; reentrega e filas de mensagens mortas; padrões de integração: mensagens, canais, roteadores, tradutores; contrato e esquema do evento; transformação e mapeamento entre sistemas; ponto a ponto vs. barramento ou orquestração; simulação de eventos em testes; reconciliação periódica contra perdas.
+
+**Princípios:**
+- Responda rápido, processe depois.
+- Webhook é um aviso de que algo mudou; reconcilie consultando a fonte.
+- Todo receptor deve ser idempotente.
+
+**Fora do escopo:** plataformas de integração e barramentos específicos.
+
+**Pergunta-chave:** O mesmo evento chega duas vezes e fora de ordem: seu receptor produz o estado correto?
+
+**Referências:**
+- Hohpe & Woolf, *Enterprise Integration Patterns*
+- Kleppmann, *Designing Data-Intensive Applications*
+- CNCF, *CloudEvents Specification*
+- RFC 2104 (HMAC)
+- Newman, *Building Microservices* (2ª ed.)
+
+**Usam mais:** API Automation, Data Ingestion, Automation Engineering

package/skills/eng-automation/references/7-rpa.md

@@ -0,0 +1,25 @@
+# 7. RPA e Automação de Processos
+
+**Nível:** IMPORTANTE · **Agnóstico de tecnologia:** ✅
+
+**Objetivo:** Automatizar processos pela interface quando não há integração melhor, com governança e saída planejada.
+
+**Conhecimentos:** quando RPA se justifica: sistema legado sem API, regra estável, alto volume; mapeamento do processo (estado atual e desejado, BPMN); candidatos bons: regras claras, entradas estruturadas, poucas exceções; robôs assistidos e não assistidos; automação de navegador e de desktop (árvore de acessibilidade vs. reconhecimento visual); filas de trabalho e orquestração de robôs; exceções de negócio vs. técnicas; identidade e credenciais de robô; auditoria e segregação de funções; manutenção, versionamento e testes; migração futura para API; medição de benefício.
+
+**Princípios:**
+- RPA é ponte, não destino: planeje a substituição.
+- Robô é um usuário: identidade própria, permissão mínima e trilha de auditoria.
+- Estabilize o processo antes de criar o robô.
+
+**Fora do escopo:** plataformas e designers de RPA específicos.
+
+**Pergunta-chave:** Que mudança de tela ou de regra quebraria este robô e quem seria avisado primeiro?
+
+**Referências:**
+- van der Aalst, Bichler & Heinzl, *Robotic Process Automation* (BISE, 2018)
+- Willcocks, Lacity & Craig, *The IT Function and Robotic Process Automation* (LSE, 2015)
+- IEEE 2755-2017 (Intelligent Process Automation)
+- OMG, *BPMN 2.0* (ISO/IEC 19510)
+- Dumas et al., *Fundamentals of Business Process Management*
+
+**Usam mais:** RPA, Process Automation, Automation Engineering