publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

aprimoração de ia

Browse source
This commit is contained in:
Luiz Silva 2026-08-10 16:18:49 -03:00
parent 1177e31e56
commit 4a9f5f70ff
109 changed files with 8835 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

118
skills/adicionar-ajuda/SKILL.md Normal file
View file

@ -0,0 +1,118 @@
---
type: workflow
name: adicionar-ajuda
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Adicionar Ajuda em Telas
Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.
O objetivo da ajuda é **auxiliar o usuário final a compreender e utilizar corretamente a aplicação**, explicando o funcionamento da tela de forma clara e objetiva.
## Pré-requisitos
- O arquivo alvo deve ser um componente de interface (`.tsx` para React ou `.vue` para Vue).
- O projeto deve possuir um componente de ajuda (ex: `BotaoAjuda`, `HelpButton` ou equivalente) disponível para uso na interface.
- Caso não exista, criar um componente reutilizável que exiba o conteúdo do `.ajuda.md` em modal ou drawer.
## Passos
### 1. Identificar o Componente Alvo
Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.
- React → `.tsx`
- Vue → `.vue`
### 2. Verificar Existência de Ajuda
Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: `.ajuda.md`) localizado na mesma pasta.
Exemplo:
```
TelaCadastroUsuario.tsx
TelaCadastroUsuario.ajuda.md
```
ou
```
TelaCadastroUsuario.vue
TelaCadastroUsuario.ajuda.md
````
### 3. Criar ou Atualizar o Arquivo Markdown
Se o arquivo `.ajuda.md` não existir, crie-o utilizando o template básico abaixo.
O conteúdo deve ser escrito **pensando no usuário final**, explicando de forma simples como utilizar a tela.
A documentação deve incluir, quando aplicável:
- **Objetivo da tela**
- **Descrição dos botões**
- **Descrição dos campos de formulário**
- **Regras de preenchimento e validações**
- **Fluxo esperado de uso**
- **Contexto técnico ou legal**, quando relevante para o entendimento da funcionalidade
Template inicial:
```markdown
# Ajuda: [Nome da Tela]
## Objetivo da Tela
Explique de forma simples para que serve esta tela dentro do sistema.
## Botões
- **Salvar**: grava as informações preenchidas.
- **Cancelar**: descarta as alterações realizadas.
- **Excluir**: remove o registro atual do sistema.
## Campos do Formulário
- **Nome**: informe o nome completo do responsável.
- **Data de Vistoria**: data em que a vistoria foi realizada.
- **Observações**: campo livre para registrar informações adicionais.
## Fluxo de Uso
1. Preencha os campos obrigatórios.
2. Revise as informações inseridas.
3. Clique em **Salvar** para registrar os dados no sistema.
## Informações Técnicas ou Legais (quando aplicável)
Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
````
### 4. Posicionamento do Botão de Ajuda
O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
#### Telas / Páginas
* O botão deve ficar na **parte inferior esquerda da página**.
* Deve respeitar espaçamento suficiente das bordas da interface.
* **Não pode sobrepor nenhum componente da tela.**
* **Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.**
* Ajustar `margin`, `padding` ou `z-index` quando necessário para garantir visibilidade adequada.
#### Modais e Diálogos
* O botão deve ficar na **parte inferior esquerda do modal**.
* Preferencialmente no rodapé do modal ou em um container equivalente.
* **Não pode sobrepor botões ou ações do modal.**
* Garantir espaçamento adequado para não interferir na usabilidade.

235
skills/aprimora-ia/SKILL.md Normal file
View file

@ -0,0 +1,235 @@
---
type: workflow
name: aprimora-ia
description: Otimizar o ecossistema da IA conforme identificado durante a conversa e registrar eventos na memória
scope: global
updatedAt: "2026-08-10"
---
# Workflow: /aprimora-ia (Aprimoramento Contínuo e Registro de Memória)
## 🎯 Objetivo
Analisar os aprendizados, alterações e decisões tomadas ao longo da conversa, aplicando as devidas otimizações diretamente nos artefatos do ecossistema (Rules, Workflows, Skills e Personas).
Este workflow é **obrigatório** e deve ser executado sempre que houver qualquer definição nova.
---
## Artefatos de Conhecimento
O conhecimento do agente está organizado em **três tipos de artefatos**, cada um com responsabilidade distinta:
| Artefato | Diretório (herdado) | Diretório (local) | Responsabilidade |
|----------|---------------------|-------------------|------------------|
| **Rules** | `.agent/base/global/rules/` | `.agent/local/rules/` | Restrições e convenções que o agente **deve respeitar sempre** |
| **Workflows** | `.agent/base/global/workflows/` | `.agent/local/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas |
| **Skills** | `.agent/base/global/skills/` | `.agent/local/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
| **Memória do Projeto** | — | `./.memoria-ia/` | Decisões de negócio, contexto do produto, especificações e ADRs (raiz do pai, versionado pelo pai) |
| **Evoluções da IA** | `.agent/memory/` | — | Relatórios de sessões `/aprimora-ia`, otimizações dos agentes e melhorias da IA (versionado pelo submódulo) |
### Diferenças entre os artefatos
| Critério | Rule | Workflow | Skill | Memória |
|----------|------|----------|-------|---------|
| **Formato** | Regra declarativa | Passos sequenciais | Guia prático com templates | Diários, ADRs, documentação de contexto puro |
| **Quando usar** | Aplicada **automaticamente** em todo contexto | Acionado por **comando** (`/workflow`) | Consultado **sob demanda** ao iniciar tarefa complexa | Consultado **para restaurar contexto** e entender escopo |
| **Exemplos** | "Nunca usar `any`" | "/migracao_banco" | "Criar função api2 end-to-end" | "ADR de transição para Nuxt 4", "Dicionário de dados" |
| **Escopo** | Restrição transversal | Processo pontual | Padrão operacional completo | Registro histórico e base factual |
### Regra de escolha
- Se é uma **restrição** que vale sempre → **Rule**
- Se é um **processo com etapas** que o usuário aciona → **Workflow**
- Se é um **guia operacional** com templates e checklist para tarefas complexas → **Skill**
- Se o conteúdo serve como **referência cruzada** durante tarefas → **Skill**
- Se é um **registro de estado, decisão técnica importante ou compreensão do domínio temporal** → **Memória**
---
## 1️⃣ Análise do Contexto Atual (Obrigatória)
É obrigatório:
- Revisar integralmente a conversa atual.
- Identificar:
- Regras de negócio novas ou alteradas.
- Padrões técnicos definidos.
- Convenções estabelecidas.
- Decisões arquiteturais.
- Ajustes de comportamento do sistema ou do agente.
Para cada item identificado, classificar obrigatoriamente:
- Já existe artefato correspondente (rule, workflow ou skill) → **ATUALIZAR**
- Existe parcialmente → **REFATORAR**
- Não existe → **CRIAR**
- Impacta múltiplas áreas → **PROPAGAR**
---
## 2️⃣ Atualização das Rules (Obrigatória)
### Regras inegociáveis:
- Toda nova regra **DEVE** ser registrada.
- Nenhuma regra pode existir apenas na conversa.
- É **PROIBIDO** deixar conhecimento implícito.
### Estrutura obrigatória:
- Um arquivo = um único assunto.
- Nome claro em `kebab-case`.
- Limite máximo: ~10.000 caracteres.
### É obrigatório:
- Evitar duplicação de conteúdo.
- Atualizar regras antigas quando substituídas.
- Remover ou ajustar regras conflitantes.
- Garantir consistência semântica entre arquivos.
### Estrutura obrigatória da rule:
```md
# Nome da Regra
## Contexto
Quando se aplica.
## Regra
Definição objetiva e obrigatória.
## Exemplos
✅ Correto
❌ Incorreto
## Impacto
Problema que evita.
```
---
## 3️⃣ Atualização dos Workflows (Obrigatória quando aplicável)
Sempre que houver processo repetível identificado:
* Criar ou atualizar workflow em `.agent/local/workflows/`.
### Obrigatório:
* Frontmatter com `description`.
* Passos numerados.
* Clareza operacional (sem ambiguidade).
* Comandos executáveis quando possível.
* Uso de `// turbo` para comandos seguros.
---
## 4️⃣ Atualização das Skills (Obrigatória quando aplicável)
Sempre que um padrão operacional complexo for definido, refinado ou corrigido:
* Criar ou atualizar skill em `.agent/local/skills/<nome-da-skill>/SKILL`.
### Quando atualizar uma skill:
- Nova regra afeta o padrão operacional descrito na skill (ex: nova convenção de tipagem afeta `criar-funcao-api2`)
- Novo workflow introduz etapas que complementam ou substituem uma skill
- Um erro recorrente revela que a skill está incompleta ou desatualizada
- Uma decisão arquitetural muda o fluxo descrito na skill
### Estrutura obrigatória da skill:
```md
---
name: nome-da-skill
description: >
Descrição em uma linha do que a skill faz.
---
# Skill: Nome Descritivo
Parágrafo de contexto explicando quando usar.
## PASSO N — Título do Passo
Instruções com código, regras e padrões.
## Checklist Final
- [ ] Item de verificação
## Referências
- Regras: `.agent/local/rules/xxx`
- Workflow: `.agent/local/workflows/xxx`
```
### Regras de organização:
- Uma skill por diretório: `.agent/local/skills/<nome>/SKILL`
- Skills globais são identificadas pelo campo `scope: global` no frontmatter
- Nome do diretório em `kebab-case`
- A skill **não deve duplicar** conteúdo de rules — referencia-as via seção `Referências`
- A skill **pode consolidar** conhecimento de múltiplas rules e workflows em um guia unificado
- Templates de código devem estar na própria skill (não em arquivos separados, a menos que sejam muito grandes)
- Skills globais residem em `global/skills/`
- Skills específicas do projeto residem em `.agent/local/skills/<nome>/SKILL`
---
## 5️⃣ Revisão de Impacto (Dirigida por Grafo)
Quando um artefato é alterado, a revisão deve ser **dirigida**, não exaustiva.
### Processo:
1. Identificar o artefato alterado
2. Consultar a seção `Referências` do artefato para encontrar dependentes diretos
3. Verificar consistência APENAS entre o artefato alterado e seus dependentes
4. Se uma inconsistência for encontrada, propagar para o próximo nível
### Regras de escopo:
| Se alterou... | Revisar... |
|---|---|
| Uma **Rule** | Workflows e skills que a **referenciam** |
| Um **Workflow** | Skills que o **referenciam** |
| Uma **Skill** | Rules e workflows na seção Referências |
| **Memória/ADR** | Nada — memória é registro, não dependência |
### É PROIBIDO:
* Revisar artefatos **sem relação** com a mudança
* Afirmar que "tudo foi revisado" sem listar quais artefatos foram verificados
* Criar artefatos sem verificar se já existe um com o mesmo escopo
### A revisão DEVE verificar:
* Não existem regras conflitantes entre o artefato alterado e seus dependentes
* Referências cruzadas continuam válidas (arquivos existem, nomes corretos)
* Skills refletem fielmente as rules que referenciam
* Não há duplicação de conteúdo entre artefatos
---
## 7⃣ Verificação Final (Checklist obrigatório)
Só é permitido encerrar se TODOS forem verdadeiros:
* [ ] Artefatos dependentes do alterado foram revisados
* [ ] Não existe conflito entre artefatos revisados
* [ ] Não existe duplicação de conteúdo
* [ ] Nenhuma regra ficou implícita
* [ ] Referências cruzadas estão válidas
* [ ] Estrutura está organizada por assunto
* [ ] Skills referenciam (não duplicam) rules
---
## ⚠️ Regra Suprema
> Se existir qualquer dúvida, conflito ou inconsistência
> entre o artefato alterado e seus dependentes,
> o trabalho é considerado **INCOMPLETO**.
A revisão é dirigida, não opcional.

89
skills/auditar-arquitetura-modulo/SKILL.md Normal file
View file

@ -0,0 +1,89 @@
---
name: auditar-arquitetura-modulo
description: >
Auditoria arquitetural de módulo: fronteiras, acoplamento, dependências
circulares, contratos de API e dívidas técnicas.
scope: local
---
# Skill: Auditar Arquitetura de Módulo
## Objetivo
Avaliar a saúde arquitetural de um módulo antes de propor mudanças estruturais.
## Etapas
### 1. Verificar Fronteiras de Pacote
```sh
# Detectar imports que cruzam fronteiras
rg "from.*-back" --include='*.ts' --include='*.vue' <modulo>-front/src/ -n
rg "from.*-front" --include='*.ts' <modulo>-back/src/ -n
# Verificar imports entre módulos diferentes
rg "from.*<outro-modulo>" --include='*.ts' <modulo>/ -n
```
### 2. Verificar Acoplamento
```sh
# Contar imports por arquivo (alto = muito acoplado)
fd "*.ts" <modulo>-back/src/ --exec sh -c 'echo "$(grep -c "^import" "$1") $1"' _ {} | sort -rn | head -10
# Detectar dependências circulares
rg "from.*\.\/" --include='*.ts' <modulo>/src/ -l | head -20
```
### 3. Verificar Contratos de API
```sh
# Listar rotas e seus schemas de validação
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
# Verificar se schemas Zod estão no *-comuns (não duplicados no back)
rg "z\.object" --include='*.ts' <modulo>-back/src/ -l
```
### 4. Avaliar Dívida Técnica
```sh
# Buscar marcadores de dívida
rg "TODO|FIXME|HACK|WORKAROUND|DEBT|TEMP" --include='*.ts' --include='*.vue' <modulo>/ -n
# Verificar limite de linhas
fd "*.ts" <modulo>/src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {}
# Verificar uso de any
rg "as any|: any" --include='*.ts' <modulo>/ -c
```
### 5. Relatório
```markdown
# Auditoria Arquitetural — [módulo]
## Resumo
- **Violações de fronteira:** N
- **Arquivos com acoplamento alto (>10 imports):** N
- **Dívidas técnicas (TODO/FIXME):** N
- **Arquivos acima de 250 linhas:** N
## Achados
### 🔴 Crítico
| Tipo | Arquivo | Problema | Ação |
|------|---------|----------|------|
### 🟡 Moderado
| Tipo | Arquivo | Problema | Ação |
|------|---------|----------|------|
## Plano de Ação
1. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Rule: `global/rules/fronteiras-monorepo`
- Skill: `global/skills/mapear-codigo-fonte/SKILL`

63
skills/auditar-ux-heuristicas/SKILL.md Normal file
View file

@ -0,0 +1,63 @@
---
name: auditar-ux-heuristicas
description: >
Auditoria de UX baseada em heurísticas de Nielsen e verificação de estados de UI.
scope: local
---
# Skill: Auditar UX por Heurísticas
## Objetivo
Avaliar UX de tela ou fluxo antes de propor mudanças.
## Etapas
### 1. Heurísticas de Nielsen
| # | Heurística | Pergunta |
|---|-----------|----------|
| 1 | Visibilidade do status | Sistema informa o que acontece? |
| 2 | Compatibilidade | Mensagens usam linguagem do domínio? |
| 3 | Controle e liberdade | Pode desfazer, voltar, cancelar? |
| 4 | Consistência | Mesmos conceitos, mesma aparência? |
| 5 | Prevenção de erros | Campos obrigatórios claros? Confirmação em ações destrutivas? |
| 6 | Reconhecimento > Lembrança | Labels descritivos? |
| 7 | Flexibilidade | Ações frequentes acessíveis? |
| 8 | Estética minimalista | Info desnecessária? |
| 9 | Recuperação de erros | Mensagens orientam correção? |
| 10 | Ajuda | Ajuda contextual disponível? |
### 2. Estados de Interface
Para cada componente: `□ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado`
### 3. Acessibilidade Básica
```sh
rg "<img" --include='*.vue' <modulo>-front/src/ -n | grep -v "alt="
rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-label\|title"
```
### 4. Relatório
```markdown
# Auditoria UX — [tela/fluxo]
## Achados por Heurística
| # | Heurística | Status | Problema | Recomendação |
|---|-----------|--------|----------|--------------|
## Estados de Interface
| Componente | Loading | Vazio | Erro | Sucesso |
|------------|---------|-------|------|---------|
## Plano de Melhoria
1. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Rule: `global/rules/mensagens-usuario`
- Rule: `global/rules/feedback-visivel`

144
skills/comercial/SKILL.md Normal file
View file

@ -0,0 +1,144 @@
---
type: workflow
name: comercial
description: Criar uma descrição comercial das funcionalidades e do sistema
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Criar Descrição Comercial
Este workflow gera uma descrição comercial de funcionalidades ou do sistema completo, escrita na pasta `./COMERCIAL/`. Cada módulo ou funcionalidade gera um arquivo separado com o padrão `./COMERCIAL/<nome-do-modulo>.md`.
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural`) em toda produção textual deste workflow.
---
## Passos
### 1. Identificar as funcionalidades solicitadas
Perguntar ao usuário quais módulos ou funcionalidades devem ser descritos. Se o pedido for genérico ("descreva o sistema"), listar os módulos principais do projeto e confirmar o escopo antes de redigir.
### 2. Levantar contexto real de cada funcionalidade
Antes de escrever, ler o código-fonte e os componentes relacionados para entender:
- Qual **problema real** a funcionalidade resolve?
- Quem são os **usuários diretos**? (consultor ambiental, gestor ambiental, gestor público, técnico de campo)
- Qual é o **fluxo de uso** no dia a dia?
- Quais **dificuldades operacionais** existiam antes da solução?
### 3. Redigir a descrição comercial
Para cada funcionalidade, produzir **dois blocos de texto** no arquivo `./COMERCIAL/<nome-do-modulo>.md`:
#### Bloco A — Descrição Resumida (2 a 4 linhas)
Texto curto que pode ser usado em páginas de divulgação, apresentações rápidas ou materiais institucionais.
Estrutura obrigatória:
- **Linha 1**: o problema/dificuldade que existe sem a solução
- **Linha 2-3**: como funciona na prática (ação do usuário, sem termos técnicos de TI)
- **Linha 4**: o impacto concreto (ganho mensurável)
*Exemplo:*
> Sem controle digital, registros de campo ficam em cadernos e planilhas isoladas — sujeitos a perda e erro de transcrição.
> Com a solução, o técnico registra os dados direto no celular, mesmo sem internet, com validação automática.
> Isso elimina falhas de preenchimento e garante rastreabilidade completa para auditorias.
#### Bloco B — Descrição Detalhada
Texto mais completo (5 a 15 linhas) que aprofunda o funcionamento e os diferenciais. Deve incluir:
- Cenário de uso realista (quem faz o quê, quando e onde)
- Recursos técnicos relevantes explicados de forma acessível (offline, sincronização, alertas automáticos)
- Benefícios encadeados (causa → efeito)
- **Implicações legais ou normativas** (quando aplicável): se a funcionalidade tem relação com legislação, normas regulatórias ou resoluções de órgãos competentes, **citar expressamente** a norma ou obrigação legal. Isso fortalece o argumento comercial e demonstra que a solução atende requisitos reais de conformidade.
> **Regra de siglas**: toda sigla usada pela primeira vez no texto deve vir acompanhada do nome por extenso. Exemplo: "ANA (Agência Nacional de Águas e Saneamento Básico)". Nas ocorrências seguintes, pode-se usar apenas a sigla.
### 4. Revisar contra o checklist de qualidade
Antes de entregar, validar **cada bloco** contra as restrições abaixo:
- [ ] O texto do Resumo começa pelo problema, não pela funcionalidade?
- [ ] Há pelo menos um cenário de uso prático (quem, onde, como)?
- [ ] Os parágrafos são curtos (2 a 4 linhas) com uma ideia principal cada?
- [ ] A linguagem soa como alguém que vive o problema, não como manual de software?
- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
- [ ] Está **LIVRE** de termos vazios ("Inovador", "Eficiente", "Solução completa", "O presente projeto")?
- [ ] Está **LIVRE** do padrão repetitivo "O sistema permite / A funcionalidade permite / A ferramenta permite"?
- [ ] As frases variam de estrutura? (alternando "Na prática...", "Com isso...", "Isso reduz...", "Como resultado...")
- [ ] Quando há implicação legal ou normativa, a norma/lei/resolução está **citada e destacada** no texto?
- [ ] O texto é compreensível pelo **público-alvo do produto** sem conhecimento de TI?
---
## Público-Alvo
Todo texto produzido por este workflow deve ser compreensível pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
Regra geral: nenhum dos perfis-alvo tem obrigação de conhecer termos de tecnologia. A linguagem deve ser **acessível, direta e sem jargões de TI**.
---
## Regras de Tom e Vocabulário
| ✅ Usar | ❌ Evitar |
|---|---|
| "Na prática, o técnico..." | "O sistema permite..." |
| "Com isso, a equipe..." | "A solução inovadora..." |
| "Isso elimina..." | "O presente projeto visa..." |
| "Como resultado..." | "Dessa forma..." |
| "Sem a solução, o gestor precisa..." | "A ferramenta oferece..." |
| "Entregamos controle sobre..." | "Nossa solução oferece..." |
| "O gestor ganha visibilidade de..." | "A plataforma disponibiliza..." |
| "página de divulgação" | "landing page" |
| "frase de abertura" | "hook" |
| "chamada para ação" | "CTA" (isolado, sem explicação) |
| "texto persuasivo" | "copywriting" |
| "linha do tempo, publicações" | "feed" |
**Tom geral**: profissional, direto, sem burocracia institucional. O texto deve parecer escrito por quem constrói a solução e entende a operação do dia a dia do cliente.
---
## Formato de Saída
Cada módulo ou funcionalidade deve gerar **um arquivo próprio** dentro da pasta `./COMERCIAL/`.
**Regra de nomeação do arquivo:**
- Usar o nome do módulo em **kebab-case** (minúsculo, separado por hifens)
O arquivo `./COMERCIAL/<nome-do-modulo>.md` deve seguir esta estrutura:
```markdown
# [Nome do Módulo]
## [Nome da Sub-funcionalidade]
### Resumo
[Bloco A — 2 a 4 linhas: problema → solução → impacto]
### Detalhamento
[Bloco B — 5 a 15 linhas: cenário real + técnico acessível + legal]
---
## [Próxima Sub-funcionalidade]
...
```
---
## Referências
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)
- Workflow: `agents/comercial/workflows/orcamento` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
- Workflow: `global/workflows/otimizar-codigos` (para documentação técnica, não comercial)

189
skills/criar-fluxograma/SKILL.md Normal file
View file

@ -0,0 +1,189 @@
---
type: workflow
name: criar-fluxograma
description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Criar Fluxograma de Decisões
Este workflow cria uma **página interativa de fluxograma** em qualquer aplicação web, usando Mermaid.js instalado como dependência do projeto.
## Princípio
O fluxograma é um artefato vivo. Ele documenta visualmente:
- Os **pontos de entrada** do processo
- As **decisões** tomadas em cada etapa
- Os **registros gerados** (banco, fila, log, e-mail, etc.)
- As **proteções e regras** que governam os estados
Deve ser mantido sempre sincronizado com o código real.
---
## Passos
### 1. Levantar o processo a ser documentado
Ler os arquivos de código relevantes para entender:
- Quais são os **pontos de entrada**? (funções de API, eventos, webhooks, ações do usuário)
- Quais são as **decisões**? (condições `if/else`, guards, validações)
- Quais são os **efeitos colaterais**? (gravações em banco, envios de e-mail, filas, logs)
- Quais são os **estados possíveis**? (status, notas, flags, etapas)
- Existe **hierarquia ou prioridade** entre estados?
### 2. Organizar os diagramas
Dividir o processo em **um diagrama por ponto de entrada**.
Cada diagrama deve mostrar:
- Todos os caminhos possíveis, inclusive early returns e casos de erro
- Registros gerados com ícone indicativo (ex: 🗄️ banco, 📧 e-mail, 🚫 bloqueio)
- Decisões claramente separadas por ramificações
Definir a orientação de cada diagrama:
- `flowchart TD` → vertical (melhor para fluxos sequenciais com poucas ramificações)
- `flowchart LR` → horizontal (melhor para pipelines e fluxos com muitas etapas em linha)
### 3. Instalar o Mermaid
Instalar como dependência do projeto antes de qualquer implementação:
```bash
# npm
npm install mermaid
# pnpm
pnpm add mermaid
```
### 4. Criar a página com Mermaid
Adaptar à plataforma do projeto (Vue, React, HTML puro, etc.), mas garantir:
#### Importação
```js
import mermaid from 'mermaid';
```
#### Inicialização com tema institucional
Adaptar as cores para a identidade visual do projeto:
```js
mermaid.initialize({
startOnLoad: false,
theme: 'base',
themeVariables: {
primaryColor: '#4F46E5', // cor primária do projeto
primaryTextColor: '#1F2933',
primaryBorderColor: '#3730A3', // variação mais escura da primária
lineColor: '#6B7280',
secondaryColor: '#E0E7FF', // variação clara da primária
tertiaryColor: '#F3F4F6',
fontFamily: "'Inter', 'Segoe UI', sans-serif",
fontSize: '13px',
},
});
```
#### Renderização de cada diagrama
```js
// Para cada diagrama:
const { svg } = await mermaid.render(`id-unico-${idx}`, codigoMermaid);
container.innerHTML = svg;
// Tornar o SVG responsivo:
const svgEl = container.querySelector('svg');
if (svgEl) {
svgEl.style.width = '100%';
svgEl.style.height = 'auto';
svgEl.removeAttribute('width');
}
```
### 5. Registrar a rota e adicionar acesso
- Registrar a rota `/fluxograma` (ou equivalente) no sistema de rotas do projeto
- Adicionar botão de navegação na tela de administração ou dashboard
---
## Padrão de sintaxe Mermaid
### Tipos de nó por semântica
| Situação | Sintaxe | Exemplo |
|---|---|---|
| Início / Fim | `A(["Texto"])` | `A(["Início"])` |
| Decisão | `B{"Condição?"}` | `B{"Nota é ativa?"}` |
| Ação / Processo | `C["Texto"]` | `C["Consulta banco"]` |
| Registro em banco | `D[("🗄️ Grava dado")]` | `D[("🗄️ Grava 203_neutro")]` |
| E-mail / notificação | `E["📧 Envia e-mail"]` | `E["📧 Agenda na fila"]` |
| Bloqueio / guard | `F["🚫 Retorna sem ação"]` | `F["🚫 Nota ativa, ignora"]` |
| Proteção / regra | `G["🛡️ Regra aplicada"]` | `G["🛡️ SQL CASE protege"]` |
### Regras para evitar erros de parsing
```
✅ Nós com parênteses → usar aspas:
A["Texto (com parênteses)"]
✅ Labels de arestas com texto especial → usar aspas:
A -- "Label aqui" --> B
✅ Emojis → sempre dentro de aspas:
A["🗄️ Grava registro"]
❌ Não usar < > dentro de labels sem aspas
❌ Não usar & diretamente — usar texto alternativo
```
### Cores de destaque para nós
```
style NomeNo fill:#22C55E,color:#fff → verde sucesso
style NomeNo fill:#DC2626,color:#fff → vermelho erro
style NomeNo fill:#F59E0B,color:#000 → amarelo alerta
style NomeNo fill:#4F46E5,color:#fff → cor institucional (adaptar ao projeto)
style NomeNo fill:#6B7280,color:#fff → cinza neutro
```
---
## Validação antes de finalizar
- [ ] Cada ponto de entrada tem seu próprio diagrama?
- [ ] Todos os registros gerados estão mapeados?
- [ ] Os caminhos de bloqueio e early return estão visíveis?
- [ ] A hierarquia de estados (se existir) está documentada?
- [ ] A data de atualização está registrada na página?
- [ ] A sintaxe Mermaid está correta (sem erros de parsing)?
- [ ] O SVG está responsivo (largura 100%, sem width fixo)?
---
## Manutenção
Sempre que o processo mudar:
1. Identificar qual diagrama é afetado
2. Atualizar o código Mermaid correspondente
3. Atualizar a data de atualização na página
4. Se houver novo estado ou proteção, documentar na legenda
---
## Referência de implementação
Se o projeto já possuir um fluxograma implementado, usar como referência.
Caso contrário, seguir os passos acima para criar a primeira implementação.
## Referências
- Workflow: `global/workflows/otimizar-codigos`
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)

36
skills/criar-landing-page/SKILL.md Normal file
View file

@ -0,0 +1,36 @@
---
name: criar-landing-page
description: Workflow passo a passo para a criação e validação de Landing Pages de alta conversão
---
# Workflow: Criar Landing Page (@land)
## Wireframe & Ordem Obrigatória das Seções
1. **Header Mínimo (Sticky):** Logo + CTA primário (sem menu de navegação).
2. **Hero Section (40% do esforço):** Headline focada em benefício + Subheadline + CTA + Visual real.
3. **Barra de Logos:** 5–8 clientes reais/métricas de impacto posicionados logo abaixo do Hero.
4. **Seção de Problemas:** 3–4 dores específicas do público-alvo.
5. **Seção de Solução:** Transformação Antes vs Depois.
6. **Benefícios:** 3–4 blocos visuais (foco em valor de negócio, não em features).
7. **Como Funciona:** Exatamente 3 passos numerados (①②③) com tempo estimado.
8. **Prova Social:** Depoimentos com foto, cargo, empresa e resultado quantificado.
9. **FAQ:** 5–6 perguntas em acordeão quebrando objeções B2B principais.
10. **CTA Final:** Reversão de risco ("Sem compromisso") + incentivo de ação.
11. **Footer Mínimo:** Contatos e termos de privacidade.
---
## Checklist de Validação Antes da Entrega
### 1. Estrutura & Copy
- [ ] Hero responde às 3 perguntas nos primeiros 5 segundos.
- [ ] Sem menu de navegação no header.
- [ ] Formulações em "Você/Sua empresa" (foco no cliente).
- [ ] Formulário com no máximo 4 campos.
### 2. Design & Performance
- [ ] Screenshots reais do produto utilizados.
- [ ] Imagens otimizadas em WebP (< 200KB).
- [ ] Responsivo mobile-first validado.
- [ ] LCP < 2,5s e CLS < 0,1.

184
skills/criar-schema-zod/SKILL.md Normal file
View file

@ -0,0 +1,184 @@
---
name: criar-schema-zod
scope: global
description: >
Guia operacional para criar, organizar e manter schemas de validação Zod em projetos TypeScript.
---
# Skill: Criar Schema Zod
Use esta skill ao adicionar validação de dados em qualquer ponto de entrada do sistema — API, formulário, webhook, importação, fila ou variáveis de ambiente.
---
## PASSO 1 — Identificar a Entrada Externa
Determinar qual dado externo precisa de validação:
| Tipo de entrada | Onde validar |
|---|---|
| Corpo de requisição (POST/PUT) | Handler da rota, antes de qualquer lógica |
| Query/path params | Handler da rota |
| Formulário frontend | Antes de chamar a API |
| Dados de fila (BullMQ) | No processador da fila |
| Arquivo importado (CSV/JSON) | No parser, linha a linha |
| Variáveis de ambiente | No boot da aplicação |
| Resposta de API externa | Após receber a resposta |
---
## PASSO 2 — Localizar ou Criar o Schema no Pacote Comuns
Schemas compartilhados vivem no pacote `*-comuns`:
```
projeto-comuns/src/tabelas/
├── usuarios/
│ ├── zUsuarioCriar.ts
│ ├── zUsuarioEditar.ts
│ └── index.ts
└── index.ts
```
### 2.1. Verificar se já existe
```bash
rg "z{NomeDaEntidade}" --include='*.ts' -l
```
Se já existir → reutilizar ou compor a partir dele (`.extend()`, `.pick()`, `.partial()`).
### 2.2. Criar o schema
```typescript
import { z } from "zod"
export const zUsuarioCriar = z.object({
nome: z.string().trim().min(1, "Nome é obrigatório"),
email: z.string().email("E-mail inválido"),
ativo: z.boolean().default(true),
})
```
### 2.3. Nomenclatura obrigatória
| Padrão | Uso |
|---|---|
| `z{Entidade}Criar` | Criação |
| `z{Entidade}Editar` | Edição (geralmente `.partial()`) |
| `z{Entidade}Filtro` | Filtros de listagem |
| `z{Entidade}Resposta` | Resposta de API |
| `z{Entidade}Params` | Parâmetros de rota |
| `z{Modulo}Config` | Configuração |
| `z{Modulo}Ambiente` | Variáveis de ambiente |
---
## PASSO 3 — Derivar o Tipo com `z.infer<>`
```typescript
export type tipoUsuarioCriar = z.infer<typeof zUsuarioCriar>
```
**Nunca** criar um `interface` ou `type` manual separado do schema. O tipo **sempre** deriva do schema.
---
## PASSO 4 — Implementar `safeParse` no Ponto de Entrada
### Backend (Express)
```typescript
import { zUsuarioCriar } from "projeto-comuns/tabelas/usuarios"
app.post("/usuarios", async (req, res) => {
const resultado = zUsuarioCriar.safeParse(req.body)
if (!resultado.success) {
return res.status(400).json({ erro: resultado.error.issues[0].message })
}
const usuario = await criarUsuario(resultado.data)
return res.json(usuario)
})
```
### Frontend (Vue)
```typescript
import { zUsuarioCriar } from "projeto-comuns/tabelas/usuarios"
const salvar = async () => {
const resultado = zUsuarioCriar.safeParse(formulario.value)
if (!resultado.success) {
erros.value = resultado.error.flatten().fieldErrors
return
}
await api.post("/usuarios", resultado.data)
}
```
### Variáveis de ambiente
```typescript
const zAmbiente = z.object({
DATABASE_URL: z.string().url(),
REDIS_HOST: z.string().default("localhost"),
NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
})
// Aqui o throw é desejável — a app não deve subir com env inválido
export const ambiente = () => zAmbiente.parse(process.env)
```
---
## PASSO 5 — Compor Schemas Derivados
Quando precisar de variações do mesmo schema, **compor** em vez de duplicar:
```typescript
// Schema base
const zProduto = z.object({
nome: z.string().trim().min(1),
preco: z.coerce.number().positive(),
categoria: z.string(),
})
// Edição: todos os campos opcionais
const zProdutoEditar = zProduto.partial()
// Resposta: base + campos gerados
const zProdutoResposta = zProduto.extend({
codigo: z.string().uuid(),
criadoEm: z.string().datetime(),
})
// Filtro: subset de campos opcionais
const zProdutoFiltro = zProduto.pick({ categoria: true }).partial()
```
---
## PASSO 6 — Validar Tipagem
```bash
npx tsc --noEmit
```
Zero erros = concluído.
---
## Checklist Final
- [ ] O schema está no pacote `*-comuns` (quando compartilhado entre front/back)?
- [ ] O tipo é derivado do schema com `z.infer<>`?
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
- [ ] `tsc --noEmit` passa sem erros?
## Referências
- Rule: `global/rules/zod-validacao-padrao`
- Rule: `global/rules/typescript-sem-any`

188
skills/diagnosticar-antes-corrigir/SKILL.md Normal file
View file

@ -0,0 +1,188 @@
---
name: diagnosticar-antes-corrigir
scope: global
updatedAt: "2026-07-09"
description: >
Protocolo universal de diagnóstico que todo agente deve seguir antes de implementar
correções, mudanças ou refatorações. Define etapas, ferramentas e formato de saída.
---
# Skill: Diagnosticar Antes de Corrigir
Use esta skill **sempre** que receber uma solicitação de correção, ajuste ou mudança. Ela é a implementação operacional da rule `diagnostico-antes-correcao`.
---
## PASSO 1 — Compreender a Solicitação
Antes de qualquer ação, responder internamente:
| Pergunta | Resposta esperada |
|----------|-------------------|
| O que o operador reportou? | Descrição objetiva do problema |
| É um erro de build, runtime, lógica ou visual? | Classificação |
| Qual módulo/pacote é afetado? | `*-back`, `*-front`, `*-comuns`, `*-migracao` |
| O operador já forneceu diagnóstico? | Se sim, validar antes de aceitar |
---
## PASSO 2 — Coletar Evidências
### 2.1. Ler o código afetado (completo)
```sh
# Não ler apenas a linha do erro — ler o arquivo inteiro para contexto
view_file <arquivo_afetado>
# Verificar imports e dependências
rg "import.*from" <arquivo_afetado>
# Verificar quem usa este arquivo
rg "<nome_do_export>" --include='*.ts' --include='*.vue' -l
```
### 2.2. Verificar erros de build (se aplicável)
```sh
# Verificar se o build passa
pnpm --filter <pacote> build 2>&1 | head -50
# Ou checagem de tipos isolada
npx tsc --noEmit -p <caminho>/tsconfig.json 2>&1 | head -30
```
### 2.3. Consultar memória (obrigatório)
```sh
grep -rn "PALAVRAS_CHAVE_DO_PROBLEMA" .
```
### 2.4. Verificar regras de negócio documentadas
```sh
# Buscar .regras-negocio.md no diretório afetado
fd ".regras-negocio.md" <diretorio_do_modulo>
# Buscar comentários explicativos no código
rg "HACK|FIXME|TODO|NOTA|IMPORTANTE|REGRA" <arquivo_afetado>
```
---
## PASSO 3 — Análise de Causa Raiz
### 3.1. Técnica dos 5 Porquês
Aplicar progressivamente até chegar à causa raiz:
```
Por que o campo não salva?
→ Porque a API retorna 400.
Por que a API retorna 400?
→ Porque a validação Zod rejeita o campo.
Por que o Zod rejeita?
→ Porque o schema não inclui esse campo.
Por que o schema não inclui?
→ Porque a migração adicionou a coluna mas o schema não foi atualizado.
CAUSA RAIZ: Schema Zod desatualizado após migração.
```
### 3.2. Classificar a causa
| Categoria | Exemplos |
|-----------|----------|
| **Schema/Tipo** | Zod schema desatualizado, tipo TypeScript incorreto |
| **Banco de dados** | Coluna ausente, migração não executada |
| **Lógica de negócio** | Condição errada, regra não implementada |
| **Integração** | API fora do contrato, fila não processando |
| **Interface** | Componente não reativo, estado inconsistente |
| **Configuração** | Variável de ambiente, tsconfig, dependência |
| **Infraestrutura** | Container, deploy, proxy, certificado |
---
## PASSO 4 — Avaliar Impacto
```sh
# Quais arquivos usam o código afetado?
rg "<simbolo_afetado>" --include='*.ts' --include='*.vue' --include='*.tsx' -l
# Quantos módulos são impactados?
rg "<simbolo_afetado>" --include='*.ts' -l | xargs -I{} dirname {} | sort -u
```
Classificar o impacto:
| Severidade | Critério |
|------------|----------|
| 🔴 Alto | Afeta 3+ módulos, pode causar regressão |
| 🟡 Médio | Afeta 1-2 arquivos, impacto limitado |
| 🟢 Baixo | Isolado, sem dependentes |
---
## PASSO 5 — Declarar Diagnóstico
**OBRIGATÓRIO:** Antes de editar qualquer arquivo, apresentar ao operador:
```markdown
## 🔍 Diagnóstico
**Problema:** [descrição objetiva do problema observado]
**Causa raiz:** [identificação precisa da causa]
**Categoria:** [Schema/Tipo | Banco | Lógica | Integração | Interface | Config | Infra]
**Severidade:** [🔴 Alto | 🟡 Médio | 🟢 Baixo]
### Arquivos afetados
- `caminho/arquivo1.ts` — [o que precisa mudar]
- `caminho/arquivo2.vue` — [o que precisa mudar]
### Plano de correção
1. [Primeiro passo]
2. [Segundo passo]
3. [Verificação]
### Riscos
- [Efeito colateral possível, se houver]
```
---
## PASSO 6 — Executar Correção
Somente após o diagnóstico declarado:
1. Aplicar as mudanças conforme o plano
2. Verificar build após cada mudança significativa
3. Confirmar que o problema original foi resolvido
4. Verificar se não houve regressão nos arquivos afetados
---
## Atalho para Problemas Triviais
Quando o problema é **evidentemente trivial** (typo, import faltando, formatação), o diagnóstico pode ser condensado em uma linha:
```
DIAGNÓSTICO: Import ausente de `zContato` em `_contatos.ts` (linha 5). Adicionando.
```
A etapa de diagnóstico **nunca é eliminada** — apenas simplificada proporcionalmente à complexidade.
---
## Checklist
- [ ] O código afetado foi lido integralmente (não apenas a linha do erro)?
- [ ] A Memória Azteca foi consultada para soluções anteriores?
- [ ] A causa raiz foi identificada (não apenas o sintoma)?
- [ ] O impacto foi avaliado (arquivos e módulos afetados)?
- [ ] O diagnóstico foi declarado ao operador antes da correção?
- [ ] A correção resolve a causa raiz, não apenas o sintoma?
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Skill: `global/skills/diagnosticar-erros-build/SKILL`
- Skill: `agents/refatorar/skills/diagnosticar-code-smells/SKILL`
- Rule: `global/rules/autonomia-agente`

97
skills/diagnosticar-cobertura-testes/SKILL.md Normal file
View file

@ -0,0 +1,97 @@
---
name: diagnosticar-cobertura-testes
description: >
Diagnóstico de cobertura de testes: identificar áreas sem cobertura,
priorizar criação de testes e mapear cenários ausentes.
scope: local
---
# Skill: Diagnosticar Cobertura de Testes
## Objetivo
Mapear a cobertura de testes de um módulo para identificar gaps críticos antes de criar novos testes ou validar correções.
## Etapas
### 1. Inventariar Testes Existentes
```sh
# Listar arquivos de teste
fd "*.spec.ts" <modulo>/ -l
fd "*.test.ts" <modulo>/ -l
# Contar testes por pacote
echo "=== Back ===" && fd "*.spec.ts" <modulo>-back/ | wc -l
echo "=== Front ===" && fd "*.spec.ts" <modulo>-front/ | wc -l
echo "=== Comuns ===" && fd "*.spec.ts" <modulo>-comuns/ | wc -l
```
### 2. Mapear Código Sem Testes
```sh
# Listar arquivos de código sem arquivo de teste correspondente
for f in $(fd "*.ts" <modulo>-back/src/ --exclude "*.spec.ts" --exclude "*.test.ts" --exclude "*.d.ts"); do
base=$(basename "$f" .ts)
if ! fd "${base}.spec.ts" <modulo>/ -q && ! fd "${base}.test.ts" <modulo>/ -q; then
echo "SEM TESTE: $f"
fi
done
```
### 3. Classificar por Criticidade
| Criticidade | O que testar primeiro |
|-------------|----------------------|
| 🔴 Crítico | Lógica de negócio em `servicos/`, schemas Zod, máquinas de estado |
| 🟡 Importante | Rotas de API, processadores de fila, composables complexos |
| 🟢 Desejável | Utils, helpers, componentes de UI puros |
### 4. Verificar Qualidade dos Testes Existentes
```sh
# Detectar testes sem assertions
rg "expect\(|assert\(|toBe\(|toEqual\(" --include='*.spec.ts' <modulo>/ -c | awk -F: '$2==0'
# Detectar testes com descrições vagas
rg "it\('" --include='*.spec.ts' <modulo>/ -n | grep -i "should work\|test\|funciona"
# Verificar mocks sem documentação
rg "mock\(|jest\.fn\(|vi\.fn\(" --include='*.spec.ts' <modulo>/ -n
```
### 5. Gerar Relatório
```markdown
# Diagnóstico de Cobertura — [nome do módulo]
## Resumo
- **Arquivos de código:** N
- **Arquivos de teste:** N
- **Cobertura estimada:** N%
- **Gaps críticos:** N
## Gaps de Cobertura
### 🔴 Sem teste — Lógica Crítica
| Arquivo | Responsabilidade | Risco |
|---------|-----------------|-------|
### 🟡 Sem teste — Funcionalidade Importante
| Arquivo | Responsabilidade | Risco |
|---------|-----------------|-------|
## Testes Existentes com Problemas
| Arquivo de Teste | Problema | Ação |
|-----------------|----------|------|
## Plano de Priorização
1. [Crítico] Criar testes para ...
2. [Crítico] Criar testes para ...
3. [Importante] Criar testes para ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`

145
skills/diagnosticar-code-smells/SKILL.md Normal file
View file

@ -0,0 +1,145 @@
---
name: diagnosticar-code-smells
description: >
Análise sistemática de código para identificar code smells, violações SOLID
e oportunidades de aplicação de Design Patterns GoF.
scope: local
---
# Skill: Diagnosticar Code Smells
## Objetivo
Analisar um arquivo, módulo ou pacote para produzir um relatório de saúde estrutural com:
- Code smells identificados
- Violações SOLID detectadas
- Design Patterns recomendados
- Prioridade de cada refatoração
## Pré-condições
- Código existente para analisar (arquivo, pasta ou pacote)
- Acesso de leitura ao código e seus testes
## Etapas
### 1. Coletar Contexto
```sh
# Identificar tamanho e estrutura
wc -l <arquivo_ou_pasta>/**/*.ts
wc -l <arquivo_ou_pasta>/**/*.vue
# Verificar cobertura de testes
find <pasta_testes> -name "*.spec.ts" -o -name "*.test.ts"
```
### 2. Verificar Smells de Volume
Para cada arquivo, verificar:
| Verificação | Comando/Ação |
|-------------|-------------|
| Linhas > 250 | `wc -l <arquivo>` |
| Funções > 30 linhas | Ler e contar manualmente |
| Parâmetros > 3 por função | `grep_search` por assinaturas |
| Imports excessivos (> 10) | Contar linhas de import |
### 3. Verificar Smells de Acoplamento
| Verificação | Indicador |
|-------------|-----------|
| Feature Envy | Função usa `outro.` mais que `this.` ou dados locais |
| Intimidade Inapropriada | Acesso a internos de outro módulo (não-exportados) |
| Cadeia de Mensagens | `a.b.c.d` com 3+ níveis |
| Import circular | Módulo A importa B que importa A |
### 4. Verificar Conformidade SOLID
Para cada princípio, aplicar o checklist:
```
□ S — Este arquivo tem apenas 1 razão para mudar?
□ O — Posso adicionar nova variação sem editar este arquivo?
□ L — Subtipos são substituíveis pelo tipo base?
□ I — Interfaces são específicas para cada consumidor?
□ D — Lógica de negócio depende de abstrações, não de implementações?
```
### 5. Mapear Oportunidades de Padrão
Cruzar smells detectados com o guia de decisão:
```
switch crescente → Strategy
criação condicional → Factory Method
construção complexa → Builder
comportamento por estado → State
pipeline de validações → Chain of Responsibility
comportamento adicional → Decorator
interface incompatível → Adapter
subsistema complexo → Facade
notificação de mudanças → Observer
```
### 6. Gerar Relatório
Produzir relatório no formato:
```markdown
# Diagnóstico de Code Smells — [nome do módulo]
## Resumo
- **Arquivos analisados:** N
- **Smells encontrados:** N
- **Violações SOLID:** N
- **Padrões recomendados:** N
## Smells Detectados
### 🔴 Crítico
| Arquivo | Smell | Linha(s) | Ação Recomendada |
|---------|-------|----------|-----------------|
### 🟡 Moderado
| Arquivo | Smell | Linha(s) | Ação Recomendada |
|---------|-------|----------|-----------------|
### 🟢 Baixo
| Arquivo | Smell | Linha(s) | Ação Recomendada |
|---------|-------|----------|-----------------|
## Violações SOLID
| Princípio | Arquivo | Descrição | Severidade |
|-----------|---------|-----------|------------|
## Design Patterns Recomendados
| Problema | Padrão | Justificativa | Esforço |
|----------|--------|---------------|---------|
## Plano de Ação (priorizado)
1. [Crítico] ...
2. [Crítico] ...
3. [Moderado] ...
```
## Critérios de Severidade
| Severidade | Critério |
|------------|----------|
| 🔴 Crítico | Violação SOLID + acoplamento alto + afeta 3+ arquivos |
| 🟡 Moderado | Code smell isolado + afeta 1-2 arquivos |
| 🟢 Baixo | Melhoria estética + sem impacto funcional |
## Pós-condições
- Relatório registrado na Memória Azteca (`./memory/`) ou entregue diretamente
- Plano de ação priorizado gerado
- `@testes` notificado sobre trechos sem cobertura
## Referências
- Persona: `agents/refatorar/persona`
- Rule: `agents/refatorar/rules/solid-compliance`
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
- Refactoring.Guru — https://refactoring.guru/pt-br/refactoring/smells

186
skills/diagnosticar-erros-build/SKILL.md Normal file
View file

@ -0,0 +1,186 @@
---
name: diagnosticar-erros-build
scope: global
updatedAt: "2026-06-01"
description: >
Guia operacional para diagnosticar e resolver erros de build em cascata em monorepos TypeScript.
---
# Skill: Diagnosticar Erros de Build em Monorepo TypeScript
Use esta skill quando o build de um monorepo TypeScript falha — especialmente quando erros aparecem em pacotes que não foram diretamente modificados (erros em cascata).
---
## PASSO 1 — Capturar o Erro Completo
Executar o build com output completo e sem truncamento:
```bash
# pnpm (monorepo completo)
pnpm build 2>&1 | head -200
# Pacote específico
pnpm --filter <pacote> build 2>&1
# tsc direto (se disponível)
npx tsc --noEmit --pretty 2>&1 | head -100
```
Identificar:
- **Qual pacote falhou primeiro** (nem sempre é o que aparece no topo)
- **Código do erro** (`TS2304`, `TS2345`, `TS7006`, etc.)
- **Arquivo e linha** do erro original
---
## PASSO 2 — Classificar o Tipo de Erro
### Erros de dependência entre pacotes (cascata)
| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `Cannot find module '@org/xxx'` | Pacote não foi buildado antes | Buildar na ordem correta ou usar `references` |
| `Module has no exported member 'X'` | Tipo renomeado/removido no pacote origem | Atualizar import no consumidor |
| Tipos `any` infiltrados | Pacote exporta sem `.d.ts` | Verificar `declaration: true` no tsconfig |
| `The inferred type cannot be named` | Dependência circular de tipos | Extrair tipo para pacote compartilhado |
### Erros de configuração
| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `Cannot use import statement` | `module` errado no tsconfig | Alinhar `module`/`moduleResolution` |
| `Relative import paths need extensions` | Node16/NodeNext resolution | Adicionar `.js` nos imports ou mudar para `bundler` |
| `rootDir is expected to contain all source files` | Arquivo fora do `rootDir` | Ajustar `rootDir` ou mover arquivo |
| `Referenced project must have setting composite` | Project references sem `composite` | Adicionar `composite: true` no tsconfig referenciado |
### Erros de tipagem
| Sintoma | Causa provável | Solução |
|---------|---------------|---------|
| `TS2304: Cannot find name` | Tipo global não declarado | Criar `d.ts` ou importar explicitamente |
| `TS2345: Argument not assignable` | Tipos incompatíveis entre versões | Alinhar versão da dependência |
| `TS7006: Parameter implicitly has 'any'` | `noImplicitAny` ativado | Tipar o parâmetro explicitamente |
| `TS18046: is of type 'unknown'` | Narrowing ausente | Fazer type guard antes de usar |
---
## PASSO 3 — Identificar a Raiz do Problema
O erro que aparece **primeiro** nem sempre é a raiz. Seguir esta estratégia:
### 3.1. Verificar ordem de build
```bash
# Listar dependências internas para entender ordem correta
rg '"workspace:' --include='package.json' -l | sort
# Se usar turbo, verificar o pipeline
cat turbo.json | jq '.pipeline.build'
```
### 3.2. Rebuild isolado do pacote raiz
```bash
# Buildar APENAS o pacote mais baixo na hierarquia que apresenta erro
pnpm --filter <pacote-raiz> build
# Se esse buildar com sucesso, subir na hierarquia
pnpm --filter <pacote-consumidor> build
```
### 3.3. Verificar checagem de tipos isolada
```bash
# Verificar se a tipagem está correta sem produzir output
npx tsc --noEmit -p <caminho>/tsconfig.json
```
---
## PASSO 4 — Resolver Erros em Cascata
### Estratégia: de baixo para cima
1. Identificar o pacote **mais fundamental** (aquele que não depende de outros internos)
2. Resolver TODOS os erros nesse pacote
3. Rebuildar
4. Subir para o próximo pacote na cadeia de dependência
5. Repetir até o topo
### Armadilhas comuns
```typescript
// ❌ ERRADO: "resolver" com any (viola typescript-sem-any)
const dados = resultado as any
// ✅ CORRETO: tipar adequadamente
const dados: ResultadoEsperado = resultado
// ❌ ERRADO: ignorar erro com @ts-ignore
// @ts-ignore
import { funcao } from '@org/pacote'
// ✅ CORRETO: investigar por que o import falha
// O pacote '@org/pacote' foi buildado? O export existe?
```
---
## PASSO 5 — Verificar Alinhamento de Configuração
Quando erros persistem entre pacotes, verificar alinhamento de tsconfig:
```bash
# Comparar configurações críticas entre pacotes
for f in $(fd tsconfig.json --max-depth 2 --type f); do
echo "=== $f ==="
jq '{target, module, moduleResolution, strict, composite, declaration}' "$f" 2>/dev/null
done
```
Campos que **devem** ser consistentes entre pacotes do mesmo monorepo:
| Campo | Recomendação |
|-------|-------------|
| `target` | Mesmo alvo para todos (ex: `ES2022`) |
| `module` | Consistente (ex: `ESNext` ou `Node16`) |
| `moduleResolution` | Consistente (ex: `bundler` ou `node16`) |
| `strict` | `true` em todos |
| `declaration` | `true` em libs, opcional em apps |
| `composite` | `true` em libs referenciadas |
---
## PASSO 6 — Limpar e Rebuildar
Quando a investigação não revela causa óbvia:
```bash
# Limpar artefatos de build de todos os pacotes
fd -t d 'dist|build|.tsbuildinfo' --exclude node_modules | xargs rm -rf
# Limpar node_modules (último recurso)
fd -t d node_modules --max-depth 2 | xargs rm -rf
# Reinstalar e rebuildar do zero
pnpm install && pnpm build
```
---
## Checklist Final
- [ ] O pacote raiz do erro em cascata foi identificado?
- [ ] O erro original (não o efeito cascata) foi localizado?
- [ ] A solução não usa `any`, `as any` ou `@ts-ignore`?
- [ ] Todos os pacotes na cadeia foram rebuildados após a correção?
- [ ] As configurações de tsconfig estão alinhadas entre pacotes?
- [ ] O build completo passa sem erros?
## Referências
- Rules: `global/rules/typescript-sem-any`
- Workflow: `global/workflows/otimizar-codigos`
- Skill: `global/skills/mapear-codigo-fonte/SKILL`

96
skills/diagnosticar-lacunas-documentacao/SKILL.md Normal file
View file

@ -0,0 +1,96 @@
---
name: diagnosticar-lacunas-documentacao
description: >
Diagnóstico de lacunas de documentação: funções sem JSDoc, módulos sem
regras de negócio documentadas, documentação desatualizada.
scope: local
---
# Skill: Diagnosticar Lacunas de Documentação
## Objetivo
Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.
## Etapas
### 1. Verificar JSDoc em Funções Compartilhadas
```sh
# Listar funções exportadas sem JSDoc
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ -n | while read line; do
file=$(echo "$line" | cut -d: -f1)
lineno=$(echo "$line" | cut -d: -f2)
prev=$((lineno - 1))
if ! sed -n "${prev}p" "$file" | grep -q "*/"; then
echo "SEM JSDOC: $line"
fi
done
```
### 2. Verificar Regras de Negócio Documentadas
```sh
# Listar módulos com lógica complexa
rg "if.*&&|switch|\.length\s*>" --include='*.ts' <modulo>-back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn
# Verificar quais têm .regras-negocio.md
fd ".regras-negocio.md" <modulo>/ -l
# Detectar lógica complexa sem documentação de regras
# (comparar os dois resultados acima)
```
### 3. Verificar Documentação de API
```sh
# Listar rotas sem comentário explicativo
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
# Verificar quais rotas têm JSDoc
rg "/\*\*" --include='*.ts' <modulo>-back/src/rotas/ -c
```
### 4. Detectar Dessincronia Código ↔ Docs
```sh
# Buscar campos mencionados em .regras-negocio.md que não existem no código
# (verificação manual por arquivo)
# Buscar decisões técnicas que deveriam estar na Memória
rg "DECISÃO|ADR|NOTA|IMPORTANTE" --include='*.ts' --include='*.md' <modulo>/ -n
```
### 5. Gerar Relatório
```markdown
# Diagnóstico de Documentação — [nome do módulo]
## Resumo
- **Funções compartilhadas sem JSDoc:** N
- **Módulos complexos sem .regras-negocio.md:** N
- **Rotas sem documentação:** N
## Lacunas Encontradas
### 🔴 Crítico — Lógica Complexa Não Documentada
| Arquivo | Complexidade | O que documentar |
|---------|-------------|-----------------|
### 🟡 Moderado — JSDoc Ausente
| Arquivo | Função | Tipo |
|---------|--------|------|
### 🟢 Baixo — Melhorias
| Arquivo | O que melhorar |
|---------|---------------|
## Plano de Documentação (priorizado)
1. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Rule: `global/rules/jsdoc-padrao`
- Rule: `global/rules/regras-negocio-md`

117
skills/diagnosticar-saude-backend/SKILL.md Normal file
View file

@ -0,0 +1,117 @@
---
name: diagnosticar-saude-backend
description: >
Diagnóstico sistemático de saúde do backend: rotas, queries, schemas, filas,
CRONs e integrações antes de qualquer correção.
scope: local
---
# Skill: Diagnosticar Saúde do Backend
## Objetivo
Analisar a saúde de um módulo backend para identificar problemas antes de corrigi-los. Produz relatório com causa raiz, severidade e plano de ação.
## Pré-condições
- Acesso ao pacote `*-back` do módulo
- Acesso ao pacote `*-comuns` (schemas de contrato)
## Etapas
### 1. Verificar Integridade de Schemas
```sh
# Listar todos os schemas Zod do módulo
rg "export const z" --include='*.ts' <modulo>-comuns/src/tabelas/ -l
# Verificar se schemas do comuns são usados no back
rg "from.*comuns" --include='*.ts' <modulo>-back/src/ | head -20
# Detectar schemas redefinidos no back (violação de fronteiras)
rg "z\.object\(\{" --include='*.ts' <modulo>-back/src/ -l
```
### 2. Verificar Consistência de Rotas
```sh
# Listar todas as rotas definidas
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/ -n
# Verificar validação de entrada em cada rota
rg "zod|parse|safeParse" --include='*.ts' <modulo>-back/src/rotas/ -l
# Detectar rotas sem validação Zod
# (comparar lista de rotas vs lista de validações)
```
### 3. Verificar Saúde de Queries
```sh
# Detectar queries sem tratamento de erro
rg "\.select\(|\.insert\(|\.update\(|\.delete\(" --include='*.ts' <modulo>-back/src/ -n
# Detectar possíveis N+1 (query dentro de loop)
rg "for.*await|forEach.*await|map.*await" --include='*.ts' <modulo>-back/src/ -n
# Verificar transações (queries que deveriam ser atômicas)
rg "\.transaction\(" --include='*.ts' <modulo>-back/src/ -l
```
### 4. Verificar Filas e CRONs
```sh
# Listar processadores de fila
rg "process|worker|queue" --include='*.ts' <modulo>-back/src/filas/ -l
# Verificar tratamento de falha em filas
rg "catch|onFailed|failedReason" --include='*.ts' <modulo>-back/src/filas/ -n
# Listar CRONs agendados
rg "cron|schedule|repeat" --include='*.ts' <modulo>-back/src/ -n
```
### 5. Verificar Tipagem e Build
```sh
# Checar tipos sem gerar saída
npx tsc --noEmit -p <modulo>-back/tsconfig.json 2>&1 | head -30
# Detectar uso de any
rg "as any|: any" --include='*.ts' <modulo>-back/src/ -n
```
### 6. Gerar Relatório
```markdown
# Diagnóstico Backend — [nome do módulo]
## Resumo
- **Rotas analisadas:** N
- **Schemas verificados:** N
- **Problemas encontrados:** N
## Problemas Detectados
### 🔴 Crítico
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|
### 🟡 Moderado
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|
### 🟢 Baixo
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|
## Plano de Correção (priorizado)
1. ...
2. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
- Rule: `global/rules/zod-validacao-padrao`

88
skills/diagnosticar-saude-deploy/SKILL.md Normal file
View file

@ -0,0 +1,88 @@
---
name: diagnosticar-saude-deploy
description: >
Diagnóstico de saúde de deploy e infraestrutura: containers, variáveis
de ambiente, healthchecks, logs e estado dos serviços.
scope: local
---
# Skill: Diagnosticar Saúde de Deploy
## Objetivo
Avaliar o estado de saúde da infraestrutura e pipelines de deploy antes de aplicar mudanças.
## Etapas
### 1. Verificar Estado dos Containers
```sh
# Listar containers ativos
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# Verificar logs recentes de erro
docker logs --tail 50 <container> 2>&1 | grep -i "error\|fatal\|exception\|fail"
# Verificar uso de recursos
docker stats --no-stream
```
### 2. Verificar Variáveis de Ambiente
```sh
# Listar variáveis esperadas (schemas Zod de ambiente)
rg "z\.Ambiente\|process\.env\." --include='*.ts' <modulo>-back/src/ -n
# Verificar se há variáveis sem default ou validação
rg "process\.env\." --include='*.ts' <modulo>-back/src/ -n | grep -v "z\.\|zod\|Ambiente"
```
### 3. Verificar Healthchecks
```sh
# Verificar endpoints de health
rg "health\|alive\|ready" --include='*.ts' <modulo>-back/src/ -n
# Verificar healthcheck no Docker
rg "HEALTHCHECK" Dockerfile* docker-compose* -n
```
### 4. Verificar Build
```sh
# Testar build completo
pnpm build 2>&1 | tail -20
# Verificar migrations pendentes
rg "migration\|migrate" --include='*.ts' <modulo>-migracao/src/ -l
```
### 5. Gerar Relatório
```markdown
# Diagnóstico de Deploy — [nome do módulo]
## Resumo
- **Containers:** N ativos / N esperados
- **Healthchecks:** N configurados
- **Variáveis de ambiente:** N validadas / N sem validação
- **Build:** ✅ OK | ❌ Falha
## Problemas Detectados
### 🔴 Crítico
| Área | Problema | Impacto | Ação |
|------|----------|---------|------|
### 🟡 Moderado
| Área | Problema | Impacto | Ação |
|------|----------|---------|------|
## Plano de Ação
1. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`

108
skills/diagnosticar-saude-frontend/SKILL.md Normal file
View file

@ -0,0 +1,108 @@
---
name: diagnosticar-saude-frontend
description: >
Diagnóstico sistemático de saúde do frontend: componentes, composables,
estados de UI, acessibilidade e integração com API.
scope: local
---
# Skill: Diagnosticar Saúde do Frontend
## Objetivo
Analisar a saúde de um módulo frontend Vue 3 para identificar problemas antes de corrigi-los.
## Etapas
### 1. Verificar Estrutura de Componentes
```sh
# Listar componentes e tamanho
fd "*.vue" <modulo>-front/src/ --exec wc -l {} | sort -rn | head -20
# Detectar componentes acima do limite (250 linhas)
fd "*.vue" <modulo>-front/src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {}
# Verificar se usam defineComponent com setup()
rg "defineComponent" --include='*.vue' <modulo>-front/src/ -l
```
### 2. Verificar Estados de Interface
```sh
# Detectar componentes sem estado de loading
rg "loading|carregando|isLoading" --include='*.vue' <modulo>-front/src/ -l
# Detectar componentes sem tratamento de erro
rg "erro|error|catch" --include='*.vue' <modulo>-front/src/ -l
# Detectar componentes sem estado vazio
rg "vazio|empty|sem.*dados|nenhum" --include='*.vue' <modulo>-front/src/ -l
```
### 3. Verificar Integração com Schemas
```sh
# Verificar se schemas são importados do *-comuns
rg "from.*comuns" --include='*.ts' --include='*.vue' <modulo>-front/src/ | head -20
# Detectar schemas redefinidos no front (violação)
rg "z\.object\(\{" --include='*.ts' --include='*.vue' <modulo>-front/src/ -l
# Detectar uso de any
rg "as any|: any" --include='*.ts' --include='*.vue' <modulo>-front/src/ -n
```
### 4. Verificar Composables
```sh
# Listar composables existentes
fd "use*.ts" <modulo>-front/src/composables/ -l
# Verificar composables duplicando lógica
rg "ref\(|reactive\(|computed\(" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
```
### 5. Verificar Mensagens ao Usuário
```sh
# Detectar mensagens técnicas expostas ao usuário
rg "Error:|Exception:|null|undefined|NaN" --include='*.vue' <modulo>-front/src/ -n
# Verificar se mensagens usam linguagem do domínio
rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts' <modulo>-front/src/ -n
```
### 6. Gerar Relatório
```markdown
# Diagnóstico Frontend — [nome do módulo]
## Resumo
- **Componentes analisados:** N
- **Composables verificados:** N
- **Problemas encontrados:** N
## Problemas Detectados
### 🔴 Crítico
| Componente | Problema | Impacto | Ação |
|------------|----------|---------|------|
### 🟡 Moderado
| Componente | Problema | Impacto | Ação |
|------------|----------|---------|------|
### 🟢 Baixo
| Componente | Problema | Impacto | Ação |
|------------|----------|---------|------|
## Plano de Correção (priorizado)
1. ...
```
## Referências
- Rule: `global/rules/diagnostico-antes-correcao`
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
- Rule: `global/rules/estrutura-vue` (via front)

161
skills/documentar-decisao-tecnica/SKILL.md Normal file
View file

@ -0,0 +1,161 @@
---
name: documentar-decisao-tecnica
scope: global
updatedAt: "2026-06-01"
description: >
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records).
---
# Skill: Documentar Decisão Técnica (ADR)
Use esta skill sempre que uma decisão técnica significativa for tomada — escolha de biblioteca, mudança de arquitetura, padrão de código, migração, ou qualquer decisão que afete múltiplos pacotes ou desenvolvedores.
O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdida em conversas.
---
## Quando usar
- Nova dependência adicionada ao monorepo
- Mudança de padrão arquitetural (ex: de REST para GraphQL)
- Escolha de ferramenta ou lib entre alternativas
- Decisão de breaking change
- Migração de tecnologia
- Mudança de estratégia de deploy ou CI/CD
- Qualquer decisão que alguém pode questionar daqui 3 meses
---
## PASSO 1 — Criar o Diretório de ADRs (se não existir)
```bash
mkdir -p .docs/adrs
```
Convenção de diretório: `.docs/adrs/` na raiz do monorepo.
---
## PASSO 2 — Criar o Arquivo ADR
Nomenclatura: `NNN-titulo-em-kebab-case.md`
```bash
# Encontrar o próximo número
NEXT=$(ls .docs/adrs/*.md 2>/dev/null | wc -l | xargs -I{} expr {} + 1)
NEXT=$(printf "%03d" $NEXT)
echo "Próximo ADR: $NEXT"
```
---
## PASSO 3 — Preencher o Template
```markdown
# ADR-NNN: Título Descritivo da Decisão
**Data:** YYYY-MM-DD
**Status:** proposto | aceito | substituído por ADR-XXX | descontinuado
**Autores:** Nome(s)
## Contexto
Descreva a situação que levou à necessidade de uma decisão.
Inclua:
- O problema enfrentado
- Restrições técnicas ou de negócio
- O que motivou a discussão
## Decisão
Descreva a decisão tomada de forma clara e direta.
Use voz ativa: "Decidimos usar X para Y porque Z."
## Alternativas Consideradas
### Alternativa A: [Nome]
- **Prós:** ...
- **Contras:** ...
- **Motivo da rejeição:** ...
### Alternativa B: [Nome]
- **Prós:** ...
- **Contras:** ...
- **Motivo da rejeição:** ...
## Consequências
### Positivas
- O que melhora com essa decisão
### Negativas
- O que fica mais complexo ou limitado
- Débitos técnicos introduzidos
### Neutras
- Mudanças que não são boas nem ruins, mas afetam o workflow
## Impacto no Monorepo
Listar quais pacotes/módulos são afetados:
- `@org/pacote-a` — precisa migrar de X para Y
- `@org/pacote-b` — sem impacto
```
---
## PASSO 4 — Conectar com o Sistema de Conhecimento
Após criar o ADR, avaliar se a decisão deve gerar:
| A decisão... | Ação |
|-------------|------|
| Cria uma **restrição** permanente (ex: "nunca usar lib X") | Criar/atualizar uma **Rule** em `.agent/local/rules/` |
| Define um **processo** repetível (ex: "para migrar, faça X, Y, Z") | Criar/atualizar um **Workflow** em `.agent/local/workflows/` |
| Refina um **padrão operacional** (ex: "queries agora usam pool separado") | Atualizar a **Skill** correspondente em `.agent/local/skills/` |
| Não gera artefato adicional | Apenas o ADR é suficiente |
---
## PASSO 5 — Validar o ADR
Antes de considerar completo:
- **Teste do "daqui a 6 meses"**: alguém que não participou da conversa consegue entender a decisão?
- **Teste da reversibilidade**: está claro o que seria necessário para reverter essa decisão?
- **Teste do impacto**: todos os pacotes afetados estão listados?
---
## Exemplos de ADRs Reais
### Bom ✅
> **ADR-003: Usar Zod para validação de schemas em vez de Joi**
>
> **Contexto:** O projeto usava Joi para validação no backend, mas ao compartilhar schemas entre back e front em um monorepo, Joi se mostrou pesado para o bundle do frontend (280KB gzipped).
>
> **Decisão:** Migrar para Zod em todos os pacotes. Zod oferece inferência nativa de tipos TypeScript, é 10x menor, e elimina a necessidade de manter tipos e schemas separados.
### Ruim ❌
> **ADR-003: Usar Zod**
>
> Decidimos usar Zod porque é melhor.
---
## Checklist Final
- [ ] O contexto explica o "porquê" da decisão?
- [ ] As alternativas consideradas estão documentadas?
- [ ] As consequências (positivas e negativas) estão claras?
- [ ] Os pacotes impactados estão listados?
- [ ] O status está definido (proposto/aceito)?
- [ ] A decisão gerou rules/workflows/skills quando aplicável?
- [ ] Alguém de fora do contexto entenderia este ADR?
## Referências
- Workflow: `global/workflows/aprimorar-IA` (seção de classificação de artefatos)
- Workflow: `global/workflows/otimizar-codigos`

131
skills/documentar-dominio-modulo/SKILL.md Normal file
View file

@ -0,0 +1,131 @@
---
name: documentar-dominio-modulo
scope: global
updatedAt: "2026-06-01"
description: >
Guia para documentar o domínio científico/técnico de cada módulo SaaS,
garantindo que o agente compreenda a terminologia e as regras do domínio
ao gerar código, texto e interface.
---
# Skill: Documentar Domínio de um Módulo
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, gases de efeito estufa, resíduos, projetos, etc.). O agente precisa de uma **base factual do domínio** para gerar labels, mensagens, regras de negócio e textos comerciais corretos.
---
## PASSO 1 — Identificar o Domínio do Módulo
Determinar qual área da ciência/gestão o módulo aborda:
| Exemplo de módulo | Domínio |
|---|---|
| Licenciamento | Licenciamento ambiental (LP, LI, LO, condicionantes) |
| GEE | Gases de Efeito Estufa (inventário, emissões, fatores) |
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, classificação) |
| Outorga | Outorga de uso de recursos hídricos |
| Flora/Fauna | Monitoramento de biodiversidade |
| Projetos | Gestão de projetos ambientais e consultorias |
---
## PASSO 2 — Criar o Arquivo de Domínio
Criar documento no arquivo `.regras-negocio.md` do módulo:
```markdown
# Domínio: <Nome do Módulo>
## Área de Conhecimento
Breve descrição da disciplina (1-3 linhas).
## Glossário do Módulo
| Termo | Definição | Sigla |
|---|---|---|
| Licença Prévia | Autorização para planejamento do empreendimento | LP |
| Licença de Instalação | Autorização para início das obras | LI |
| ... | ... | ... |
## Entidades Principais
Lista das entidades de negócio do módulo com descrição e relações:
- **Empreendimento**: unidade física onde ocorre a atividade potencialmente poluidora
- **Licença**: autorização ambiental vinculada a um empreendimento
- **Condicionante**: obrigação imposta pelo órgão ambiental na licença
- ...
## Legislação Aplicável
| Norma | Descrição | Relevância |
|---|---|---|
| Lei 6.938/1981 | Política Nacional do Meio Ambiente | Base legal do licenciamento |
| Resolução CONAMA 237/1997 | Regulamenta o licenciamento ambiental | Tipos de licença, prazos |
| ... | ... | ... |
## Regras de citação legal
- Formato: "Resolução CONAMA nº 237/1997, art. 8º, inciso I"
- Toda sigla na primeira ocorrência com nome por extenso
- Legislação federal > estadual > municipal (hierarquia)
## Fluxos do Domínio
Descrever os processos-chave que o módulo implementa:
1. Solicitação de licença → Análise técnica → Emissão → Monitoramento
2. Cadastro de condicionante → Acompanhamento de prazo → Cumprimento
## Vocabulário de Interface
Termos que devem ser usados em labels, botões e mensagens:
| Contexto | ❌ Genérico | ✅ Correto para o módulo |
|---|---|---|
| Campo de nome | "Nome" | "Razão Social do Empreendedor" |
| Status | "Ativo/Inativo" | "Vigente/Vencida/Suspensa" |
| Ação principal | "Criar novo" | "Solicitar nova licença" |
| Lista vazia | "Nenhum registro" | "Nenhuma licença cadastrada" |
```
---
## PASSO 3 — Validar com o Operador
Antes de consolidar:
- [ ] Os termos do glossário estão corretos para o contexto do módulo?
- [ ] As entidades cobrem os conceitos centrais?
- [ ] A legislação listada é a principal (não exaustiva)?
- [ ] O vocabulário de interface reflete como o usuário fala no dia a dia?
---
## PASSO 4 — Conectar com as Rules
Após documentar o domínio:
1. Verificar se labels e mensagens no código usam o vocabulário definido (rule `mensagens-usuario`)
2. Verificar se schemas Zod têm mensagens de erro no idioma do domínio (rule `zod-validacao-padrao`)
3. Verificar se os arquivos `.ajuda.md` usam termos do glossário (workflow `adicionar-ajuda.md`)
4. Verificar se textos comerciais citam a legislação corretamente (workflow `comercial`)
---
## Checklist Final
- [ ] Arquivo `.regras-negocio.md` do módulo criado e validado?
- [ ] Glossário com pelo menos os 10 termos centrais do módulo?
- [ ] Entidades principais listadas com descrição?
- [ ] Legislação base documentada com formato de citação?
- [ ] Vocabulário de interface definido (labels, status, ações, empty states)?
- [ ] Operador validou a terminologia?
## Referências
- Rule: `global/rules/mensagens-usuario`
- Rule: `global/rules/regras-negocio-md`
- Workflow: `agents/comercial/workflows/comercial`
- Workflow: `agents/front/workflows/adicionar-ajuda`

105
skills/documentar-regras-negocio/SKILL.md Normal file
View file

@ -0,0 +1,105 @@
---
type: workflow
name: documentar-regras-negocio
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md co-localizado com um módulo TypeScript e garantir consistência entre código e documentação
scope: global
updatedAt: "2026-06-01"
---
# Workflow: Documentar Regras de Negócio de um Módulo
Use este workflow com `/documentar-regras-negocio.global` para criar ou atualizar o arquivo
`{modulo}.regras-negocio` de qualquer módulo TypeScript com lógica de negócio não-trivial.
---
[1] Ler o módulo TypeScript completamente
Identificar e anotar:
- Nome do arquivo e localização exata
- Funções exportadas e suas responsabilidades
- Todos os `if` que representam critérios de decisão
- Campos lidos e gravados (especialmente JSONB e campos de status)
- Queries de banco: tabelas acessadas, filtros aplicados, joins
- Caminhos alternativos (revisão manual, erros, skips)
- Dependências externas (filas, e-mails, serviços)
---
[2] Verificar se já existe um `.regras-negocio`
```bash
ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
```
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
- **Não existe** → ir para o passo [3]
---
[3] Criar o arquivo `.regras-negocio`
Nomenclatura: `{nome-sem-_inicial}.regras-negocio` na mesma pasta do módulo.
Preencher com o template da skill `documentar-regras-negocio.global`:
- Contexto
- Critérios de Entrada
- Regras de Processamento (numeradas)
- Casos de Revisão Manual
- Estratégia de Saída / Fusão de Campos
- Dependências Externas
---
[4] Adicionar ou verificar a referência no `.ts`
Garantir que a primeira linha útil do arquivo TypeScript seja:
```typescript
// Regras de negócio: ver {modulo}.regras-negocio.md
```
Se já existia e está correto → sem mudança necessária.
---
[5] Simplificar JSDoc que duplicam as regras
Percorrer cada função do módulo:
- JSDoc com lista de regras de negócio → substituir por referência ao ``
- Manter apenas `@param` e `@returns` com informação técnica precisa
- Comentários inline (`//`) explicando lógica pontual são aceitos → manter
---
[6] Verificar consistência — código ↔ ``
Para cada regra listada no ``:
- [ ] Existe `if` correspondente no código
- [ ] A ordem de avaliação bate entre `` e código
- [ ] Campos com separador de concatenação batem entre `` e código
- [ ] `null` como neutro está implementado corretamente (`!= null`)
- [ ] Queries têm `orderBy` quando a posição dos resultados importa
---
[7] Validar tipagem
// turbo
```bash
npx tsc --noEmit
```
Zero erros = concluído.
---
[8] Registrar no sistema de conhecimento (se regras novas)
Se o workflow revelou novos padrões de negócio relevantes ao projeto:
- Criar ou atualizar ADR via skill `documentar-decisao-tecnica`
- Verificar se alguma rule precisa ser atualizada

160
skills/mapear-codigo-fonte/SKILL.md Normal file
View file

@ -0,0 +1,160 @@
---
name: mapear-codigo-fonte
scope: global
updatedAt: "2026-06-01"
description: >
Guia operacional para mapear, navegar e compreender a estrutura de um monorepo TypeScript.
---
# Skill: Mapear Código-Fonte de Monorepo TypeScript
Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em novo projeto, ou quando precisar localizar rapidamente onde uma funcionalidade vive no código.
---
## PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes
Localize os arquivos que definem a estratégia de monorepo:
```bash
# Identificar o gerenciador e workspace config
ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.base.json 2>/dev/null
```
Elementos a extrair:
- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
- **Apps/serviços**: diretórios de aplicações deployáveis
- **TSConfig base**: herança de configuração TypeScript entre pacotes
---
## PASSO 2 — Mapear a Árvore de Pacotes
```bash
# Listar todos os pacotes do workspace com nomes e caminhos
# pnpm
pnpm ls --depth -1 -r --json 2>/dev/null | jq '.[].name'
# Alternativa genérica: encontrar todos os package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(dirname {}): $(jq -r .name {})"'
```
Organizar os pacotes em categorias:
| Categoria | Padrão de nome | Exemplo |
|-----------|---------------|---------|
| **Libs compartilhadas** | `@org/common`, `*-comuns`, `*-shared` | Tipos, utils, schemas |
| **Backend** | `*-back`, `*-api`, `*-server` | Serviços Node/Express/Fastify |
| **Frontend** | `*-front`, `*-web`, `*-app` | Apps Vue/React/Angular |
| **Ferramentas** | `*-cli`, `*-scripts`, `*-tools` | Scripts de build, migrations |
| **Configs** | `*-config`, `*-eslint-config` | Configs compartilhadas |
---
## PASSO 3 — Mapear Dependências Internas
Identificar o grafo de dependências entre pacotes internos:
```bash
# Para cada package.json, listar deps internas (que apontam para workspace:)
rg '"workspace:' --include='package.json' -l | while read f; do
echo "=== $(jq -r .name "$f") ==="
jq -r '.dependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
jq -r '.devDependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
done
```
Anotar:
- Quais pacotes são **folha** (não dependem de outros internos)
- Quais são **raiz** (ninguém depende deles — geralmente apps)
- Quais são **núcleo** (muitos dependem deles — geralmente libs compartilhadas)
---
## PASSO 4 — Mapear Arquitetura de Cada Pacote
Para cada pacote relevante, identificar a estrutura interna:
```bash
# Visão geral rápida (2 níveis de profundidade)
eza --tree --level=2 --icons --group-directories-first <caminho-do-pacote>/src/
# ou
tree -L 2 -I node_modules <caminho-do-pacote>/src/
```
Padrões comuns a procurar:
| Diretório | Responsabilidade típica |
|-----------|----------------------|
| `src/routes/` ou `src/api/` | Endpoints/rotas HTTP |
| `src/services/` | Lógica de negócio |
| `src/models/` ou `src/entities/` | Modelos de dados |
| `src/utils/` ou `src/helpers/` | Funções utilitárias |
| `src/types/` ou `src/typings/` | Definições de tipos TS |
| `src/schemas/` | Schemas de validação (Zod, Joi) |
| `src/migrations/` | Migrações de banco |
| `src/components/` | Componentes de UI (frontend) |
| `src/composables/` ou `src/hooks/` | Lógica reutilizável (Vue/React) |
| `src/stores/` | Gerenciamento de estado |
---
## PASSO 5 — Identificar Pontos de Entrada e Exportações
```bash
# Encontrar exports públicos de cada pacote
rg "export " --include='index.ts' --include='index.tsx' -l
# Encontrar entry points no package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(jq -r .name {}):" && jq "{main, module, types, exports}" {}'
```
---
## PASSO 6 — Documentar o Mapa
Produzir um resumo estruturado com:
```markdown
# Mapa do Monorepo: <nome>
## Gerenciador: pnpm | npm | yarn
## Build System: tsc | turbo | nx
## Pacotes
### Libs Compartilhadas
- `@org/types` → tipos compartilhados (depende de: nenhum)
- `@org/utils` → funções utilitárias (depende de: @org/types)
### Aplicações
- `@org/api` → backend Express (depende de: @org/types, @org/utils)
- `@org/web` → frontend Vue (depende de: @org/types)
## Fluxo de dados
Descrever como os dados fluem entre pacotes.
## Scripts importantes
- `pnpm build` → Build de todos os pacotes
- `pnpm dev` → Inicia dev server
- `pnpm test` → Roda testes
```
---
## Checklist Final
- [ ] O gerenciador de pacotes e workspace strategy estão identificados?
- [ ] Todos os pacotes foram categorizados (lib/app/tool)?
- [ ] O grafo de dependências internas foi mapeado?
- [ ] Os pontos de entrada de cada pacote estão claros?
- [ ] A arquitetura interna dos pacotes principais foi documentada?
- [ ] Scripts de build/dev/test foram identificados?
## Referências
- Rules: `global/rules/typescript-sem-any`
- Workflow: `global/workflows/otimizar-codigos`

209
skills/marketing/SKILL.md Normal file
View file

@ -0,0 +1,209 @@
---
type: workflow
name: marketing
description: Criar peças de marketing digital para funcionalidades e módulos do sistema
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Criar Peças de Marketing
Este workflow gera peças de marketing digital prontas para uso em canais como LinkedIn, Instagram, WhatsApp e E-mail. O resultado é salvo na pasta `./COMERCIAL/` junto ao arquivo comercial do módulo correspondente, ou em arquivo separado `./COMERCIAL/<nome-do-modulo>-marketing.md`.
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural`) em toda produção textual deste workflow.
O agente deve atuar como **especialista em marketing digital voltado para o setor do produto (venda entre empresas)**, aplicando técnicas comprovadas de texto persuasivo e engajamento.
## Público-Alvo das Peças
As peças serão lidas pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
Regra geral: nenhum dos perfis-alvo tem obrigação de conhecer termos de tecnologia. A linguagem deve ser **acessível, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso na primeira ocorrência.
---
## Pré-requisitos
Antes de gerar peças de marketing, o arquivo comercial do módulo (`./COMERCIAL/<nome-do-modulo>.md`) já deve existir com os blocos A (Resumo) e B (Detalhamento). Se não existir, aplicar primeiro o workflow `/comercial.global`.
---
## Passos
### 1. Identificar o módulo e o canal
Perguntar ao usuário:
- Qual módulo ou funcionalidade será divulgado?
- Quais canais deseja? (LinkedIn, Instagram, WhatsApp, E-mail, ou todos)
### 2. Ler o contexto comercial
Ler o arquivo `./COMERCIAL/<nome-do-modulo>.md` para extrair:
- O problema e impacto (Bloco A)
- Os cenários de uso e referências legais (Bloco B)
### 3. Redigir as peças de marketing
---
## Princípios de Engajamento
1. **Abrir com uma provocação ou dado concreto** — nunca com o nome do produto. A primeira frase deve fazer o leitor parar de rolar as publicações.
2. **Falar a língua do decisor** — usar o vocabulário do público-alvo do produto, não termos de tecnologia.
3. **Criar urgência sem desespero** — mostrar o custo da inação (multa, retrabalho, perda de prazo) sem tom alarmista.
4. **Fechar com uma chamada para ação clara** — sempre direcionar para o próximo passo: demonstração, contato, link ou agendamento.
5. **Adaptar ao canal** — o mesmo conteúdo não funciona igual no LinkedIn, Instagram, WhatsApp e e-mail. Cada peça deve respeitar o formato e tom do canal.
---
## Técnicas Obrigatórias
| Técnica | Como aplicar |
|---|---|
| **Frase de abertura impactante** | Pergunta retórica, dado alarmante ou afirmação provocativa nas primeiras 10 palavras |
| **Prova social** | Mencionar o tipo de cliente que já usa (prefeituras, indústrias, consultorias), sem inventar números |
| **Contraste antes/depois** | Mostrar o cenário ruim (planilha, papel, multa) ao lado do cenário com a solução |
| **Especificidade** | Trocar "economiza tempo" por "reduz 4 horas semanais de consolidação manual" |
| **Chamada para ação conectada ao problema** | A frase final deve se conectar ao problema apresentado, não ser genérica |
---
## Formatos por Canal
### LinkedIn (Carrossel ou Post)
- 3 a 5 parágrafos curtos (1-2 linhas cada)
- Abrir com frase de abertura forte na primeira linha (antes do "ver mais")
- Usar quebras de linha para facilitar a leitura
- Emojis como marcadores (⚠️, ✅, 📊), no máximo 1 por parágrafo
- Fechar com chamada para ação + hashtags relevantes (no máximo 5)
*Exemplo de LinkedIn:*
```
⚠️ Sua equipe ainda controla [processo crítico] em planilha?
A maioria das operações só descobre o problema
quando o órgão regulador notifica.
Nessa hora, a multa já está lavrada.
Com [nome do produto], cada registro é feito digitalmente
com cálculo automático. Se o valor ultrapassar
o limite autorizado, um alerta dispara na hora.
✅ Controle em tempo real
✅ Alertas automáticos de limite
✅ Relatórios prontos para auditoria
Quer ver funcionando? Fale com a gente.
#Hashtag1 #Hashtag2 #Hashtag3
```
### Instagram (Stories / Reels / Carrossel)
- Frases de impacto (no máximo 15 palavras por slide)
- Visual > texto — cada slide deve ter uma ideia única
- Usar contrastes visuais (❌ antes / ✅ depois)
- Chamada para ação no último slide: "Link na bio" ou "Fale com nosso time"
*Exemplo de Instagram:*
```
Slide 1: "Sua operação está em conformidade?"
Slide 2: ❌ "Planilhas manuais. Registros esquecidos. Consolidação no fim do mês."
Slide 3: ⚠️ "[Citação legal relevante]"
Slide 4: ✅ "Registro digital com cálculo automático."
Slide 5: ✅ "Alerta em tempo real quando o limite é atingido."
Slide 6: "Conheça [nome do produto]. Link na bio."
```
### WhatsApp (Mensagem de prospecção)
- No máximo 4 linhas + 1 chamada para ação
- Tom pessoal, sem parecer mensagem em massa
- Mencionar o contexto do destinatário (setor, dificuldade conhecida)
*Exemplo de WhatsApp:*
```
Oi [Nome], tudo bem?
Vi que vocês trabalham com [contexto do destinatário].
Queria mostrar como estamos ajudando operações como a de vocês
a [benefício principal da solução].
Posso te mandar um vídeo rápido de 2 min mostrando como funciona?
```
### E-mail (Prospecção ou Nutrição)
- Assunto: direto, com gancho de dificuldade real (no máximo 60 caracteres)
- Corpo: 3 parágrafos curtos — problema → solução → chamada para ação
- Evitar formatação visual pesada — preferir texto limpo e direto
*Exemplo de E-mail:*
```
Assunto: [Pergunta sobre dificuldade real do destinatário]
Olá [Nome],
[Parágrafo 1: descrever a dificuldade que o destinatário provavelmente enfrenta]
[Parágrafo 2: como a solução resolve, com dados concretos]
Se fizer sentido, posso agendar 15 minutos para mostrar como funciona
na prática. Qual o melhor horário para você?
[Assinatura]
```
---
## Checklist de Qualidade
Antes de finalizar qualquer peça, validar:
- [ ] A primeira frase **provoca, questiona ou surpreende**?
- [ ] O texto fala a **língua do decisor** (público-alvo do produto), não de desenvolvedor?
- [ ] Existe **contraste claro** entre o cenário sem e com a solução?
- [ ] Os benefícios são **específicos** (números, tempo, ações concretas)?
- [ ] Tem **chamada para ação clara** e conectada ao problema apresentado?
- [ ] O tom está **adaptado ao canal** (LinkedIn ≠ WhatsApp ≠ E-mail)?
- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
- [ ] Menções legais são usadas como **argumento de urgência**, não como decoração?
---
## Formato de Saída
O resultado deve ser salvo em `./COMERCIAL/<nome-do-modulo>-marketing.md` ou adicionado ao final do arquivo comercial existente, conforme preferência do usuário.
```markdown
# Marketing — [Nome do Módulo]
## LinkedIn
[Post pronto para publicação]
## Instagram
[Roteiro de slides para carrossel ou legenda para post]
## WhatsApp
[Mensagem de prospecção]
## E-mail
[Template de prospecção ou nutrição]
```
---
## Referências
- Workflow: `agents/comercial/workflows/comercial` (gera os blocos A e B que alimentam o marketing)
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)

134
skills/orcamento/SKILL.md Normal file
View file

@ -0,0 +1,134 @@
---
type: workflow
name: orcamento
description: Criar texto de orçamento pronto para copiar e colar em peças de orçamento/proposta
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Criar Texto de Orçamento
Este workflow gera textos prontos para **copiar e colar dentro de documentos de orçamento e propostas comerciais**. O resultado é salvo na pasta `./COMERCIAL/` com o sufixo `-orcamento` (ex: `./COMERCIAL/<nome-do-modulo>-orcamento.md`).
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural`) em toda produção textual deste workflow.
---
## Público-Alvo
O documento de orçamento será lido pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
A linguagem deve ser **acessível, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso na primeira ocorrência.
---
## Pré-requisitos
Antes de gerar o texto de orçamento, o agente deve ler o código-fonte do módulo para entender quais funcionalidades existem de fato. Se já existir o arquivo comercial (`./COMERCIAL/<nome-do-modulo>.md`), usá-lo como base para extrair contexto.
---
## Passos
### 1. Identificar o módulo
Perguntar ao usuário qual módulo ou funcionalidade será orçado.
### 2. Levantar contexto
Ler o código-fonte e os componentes relacionados para mapear:
- Quais **funcionalidades** o módulo oferece de fato?
- Existe **legislação ou norma** relevante que o módulo atende?
- Quem são os **usuários diretos**? (consultor, gestor, técnico de campo)
### 3. Redigir o texto de orçamento
O texto deve ser **autocontido** — pronto para colar diretamente dentro de um documento de orçamento sem necessidade de edição. Estrutura obrigatória:
#### Apresentação do Módulo (2 a 4 linhas)
Texto que descreve o módulo de forma direta, mostrando **o que ele faz** e **qual problema resolve**. Se houver legislação ou norma relevante, **citar aqui** para demonstrar conformidade regulatória e fortalecer o argumento.
Regras:
- Começar pelo que o módulo entrega, não pelo problema
- Se houver lei/norma relevante, citar com nome por extenso e artigo
- Tom confiante e profissional — adequado para documento formal
- Não usar termos de tecnologia
#### Lista de Funcionalidades
Após a apresentação, listar as funcionalidades do módulo em formato de **itens curtos** (1 a 2 linhas cada). Cada item deve:
- Descrever **o que a funcionalidade faz na prática** (ação concreta, não conceito abstrato)
- Ser compreensível por alguém que **nunca viu o sistema**
- Ser suficientemente específico para justificar o valor cobrado
Regras para cada item:
- Começar com o **nome da funcionalidade** em negrito
- Seguir com uma descrição curta do que ela faz
- Opcionalmente, incluir o benefício direto entre parênteses ou traço
### 4. Revisar contra o checklist de qualidade
Antes de entregar, validar:
- [ ] A apresentação do módulo é autocontida e compreensível isoladamente?
- [ ] Cada funcionalidade está descrita de forma concreta (o que faz, não o que é)?
- [ ] O texto está **pronto para copiar e colar** sem edição?
- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
- [ ] Legislação/norma relevante está **citada na apresentação** com nome por extenso?
- [ ] O tom é profissional e adequado para um documento formal de orçamento?
- [ ] É compreensível pelo **público-alvo do produto** sem conhecimento de TI?
---
## Regras de Redação
- **Sem jargões de TI**: trocar termos técnicos por equivalentes acessíveis (ex: "painel" em vez de "dashboard", "código QR" em vez de "QR Code")
- **Siglas por extenso**: toda sigla deve vir acompanhada do nome por extenso na primeira ocorrência
- **Tom formal mas acessível**: adequado para um documento de orçamento/proposta enviado a um diretor ou secretário
- **Funcionalidades concretas**: "Registro de leituras com cálculo automático de volume", não "Módulo de coleta de dados parametrizável"
---
## Formato de Saída
O arquivo `./COMERCIAL/<nome-do-modulo>-orcamento.md` deve seguir esta estrutura:
```markdown
# [Nome do Módulo]
[Apresentação do módulo — 2 a 4 linhas com legislação relevante, se aplicável]
## Funcionalidades incluídas
- **[Nome da funcionalidade 1]**: [descrição curta do que faz na prática]
- **[Nome da funcionalidade 2]**: [descrição curta do que faz na prática]
- **[Nome da funcionalidade 3]**: [descrição curta do que faz na prática]
- ...
```
*Exemplo:*
```markdown
# [Nome do Módulo]
[Apresentação do módulo com descrição direta do que faz, qual problema resolve e,
se aplicável, legislação ou norma relevante citada por extenso.]
## Funcionalidades incluídas
- **[Funcionalidade 1]**: [descrição curta do que faz]
- **[Funcionalidade 2]**: [descrição curta do que faz]
- **[Funcionalidade 3]**: [descrição curta do que faz]
- ...
```
---
## Referências
- Workflow: `agents/comercial/workflows/comercial` (descrição comercial detalhada — Resumo e Detalhamento)
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing digital)
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)

177
skills/orquestrar-agentes/SKILL.md Normal file
View file

@ -0,0 +1,177 @@
---
name: orquestrar-agentes
description: >
Protocolo de colaboração e handoff entre agentes especializados do ecossistema Azteca.
Define como agentes passam contexto, comunicam resultados e resolvem dependências.
scope: global
---
# Skill: Orquestrar Agentes
Use esta skill sempre que uma tarefa exigir a colaboração de dois ou mais agentes especializados, ou quando precisar entender quem deve fazer o quê em uma implementação complexa.
---
## PASSO 1 — Identificar os agentes envolvidos
Antes de qualquer implementação, mapear quais agentes são necessários:
| Tarefa | Agente responsável |
|--------|-------------------|
| Definir arquitetura, contratos de API, schemas | `@arquiteto` |
| Implementar backend (rotas, serviços, banco) | `@back` |
| Implementar frontend (telas, componentes, fluxos) | `@front` |
| Garantir qualidade e criar testes | `@testes` |
| Configurar infraestrutura e deploy | `@deploy` |
| Criar/atualizar documentação | `@documentacao` |
| Revisar e melhorar UX | `@ux` |
| Criar materiais de venda e marketing | `@comercial` |
---
## PASSO 2 — Definir a sequência de handoff
Toda tarefa complexa segue uma ordem de precedência:
```
1. @arquiteto → define e especifica
2. @back → implementa backend + schemas *-comuns
3. @front → implementa frontend (consome *-comuns)
4. @ux → revisa experiência (paralelo com front)
5. @testes → valida qualidade
6. @deploy → empacota e publica
7. @documentacao → documenta (pode ser paralelo)
8. @comercial → cria materiais (após documentação)
```
Agentes podem trabalhar em paralelo quando não há dependência direta:
- `@ux` e `@front` podem colaborar em paralelo
- `@documentacao` pode trabalhar em paralelo com `@testes`
- `@comercial` é sempre o último da cadeia
---
## PASSO 3 — Formato de mensagem entre agentes
Quando um agente precisa comunicar resultado ou delegar tarefa para outro, usar o formato:
```markdown
**De:** @arquiteto
**Para:** @back
**Tipo:** especificação | resultado | bloqueio | revisão
## Contexto
[O que foi decidido/implementado/identificado]
## Entrega
[O que o agente destinatário precisa fazer ou receber]
## Dependências
[Arquivos, schemas, endpoints ou decisões que o destinatário precisa conhecer]
## Critérios de aceite
[Como saber que a tarefa do destinatário está completa]
```
---
## PASSO 4 — Regras de escopo entre agentes
### Permitido ✅
```
@arquiteto → pode delegar para qualquer agente
@back → pode enviar schemas e endpoints para @front (via *-comuns)
@front → pode solicitar revisão de @ux
@ux → pode propor melhorias para @front
@testes → pode reportar bugs para @back e @front
@documentacao → pode documentar artefatos de qualquer agente
@deploy → recebe builds de @back e @front
```
### Proibido ❌
```
@front ✗ não importa código de @back diretamente
@back ✗ não cria componentes Vue ou lógica de interface
@comercial ✗ não promete features que @arquiteto não aprovou
@testes ✗ não modifica código de produção
@ux ✗ não implementa código Vue — apenas orienta @front
```
---
## PASSO 5 — Resolução de conflitos
Quando dois agentes têm visões diferentes:
1. **Técnico vs. UX:** `@arquiteto` arbitra, priorizando viabilidade técnica com mínimo impacto na UX
2. **Back vs. Front (sobre contrato de API):** `@arquiteto` define o contrato no schema `*-comuns`
3. **Documentação vs. Implementação:** O código é a verdade — `@documentacao` atualiza para refletir o código
4. **Comercial vs. Produto:** `@arquiteto` define o que existe; `@comercial` comunica apenas o real
---
## PASSO 6 — Fluxos típicos de colaboração
### Fluxo: Nova feature completa
```
@arquiteto → especifica schema e contrato de API
↓
@back → implementa endpoint + atualiza *-comuns
↓
@front → implementa tela consumindo *-comuns
↓ (paralelo)
@ux → revisa UX da tela
↓
@testes → valida back + front
↓
@deploy → publica
↓ (paralelo)
@documentacao → documenta
↓
@comercial → cria material de divulgação
```
### Fluxo: Correção de bug crítico
```
@testes → identifica e documenta bug
↓
@back ou @front → corrige
↓
@testes → valida correção
↓
@deploy → hotfix
```
### Fluxo: Melhoria de UX
```
@ux → identifica problema e propõe melhoria
↓
@arquiteto → avalia impacto técnico
↓
@front → implementa
↓
@ux → valida
```
---
## Checklist de orquestração
- [ ] Agentes necessários identificados?
- [ ] Sequência de handoff definida?
- [ ] Dependências entre agentes mapeadas?
- [ ] Critérios de aceite definidos para cada entrega?
- [ ] Conflitos potenciais identificados e árbitro definido?
---
## Referências
- Rule: `global/rules/autonomia-agente`
- Rule: `global/rules/fronteiras-monorepo`
- Personas: `agents/*/persona`

71
skills/otimizar-codigos/SKILL.md Normal file
View file

@ -0,0 +1,71 @@
---
type: workflow
name: otimizar-codigos
description: Agente especialista em limpeza e refatoração de código
scope: global
updatedAt: "2026-06-03"
---
Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
## Regras principais
1. Não altere regras de negócio.
2. Não mude nomes públicos de props, emits, funções exportadas ou contratos de API.
3. Não remova validações existentes.
4. Não altere layout visual sem necessidade.
5. Nenhum arquivo `.vue`, `.ts`, `.tsx` ou `.jsx` deve ultrapassar 250 linhas.
6. Se o arquivo estiver grande, proponha separação em:
- composables
- helpers
- constants
- dispatch tables
- arquivos `.css` separados
7. O `setup()` de componentes Vue não deve ser separado do componente.
8. CSS pode ser separado em:
- `NomeDoArquivo.vue`
- `NomeDoArquivo.css`
9. Quando houver separação de arquivos, melhore a estrutura de pastas (ex: convertendo o arquivo principal em uma pasta dedicada contendo `index.vue` ou `index.ts` junto com seus arquivos auxiliares e subcomponentes).
## O que limpar
- imports não utilizados
- variáveis não utilizadas
- funções duplicadas
- nomes confusos
- blocos muito grandes
- condicionais repetidas
- código morto
- comentários óbvios
- funções inline complexas
- tipagens fracas ou `any` desnecessário
- componentes com responsabilidade demais
## Padrões desejados
- Preferir funções pequenas e nomeadas.
- Usar `computed`, `ref` e `reactive` de forma clara.
- Usar `PropType<T>` quando a prop tiver tipo complexo.
- Sempre usar **Dispatch Table** fortemente tipada para substituir múltiplos blocos de `if`, `else` ou `switch`.
- Sempre dar prioridade para uso de enums.
- Manter tipagens existentes sempre que possível.
- Criar nomes claros e objetivos.
- Preservar compatibilidade com Vue 3 e TypeScript.
## Saída esperada
Para cada arquivo analisado, retorne:
1. Problemas encontrados
2. Melhorias aplicadas
3. Código final refatorado
4. Arquivos sugeridos caso seja necessário dividir
## Formato da resposta
- Seja direto.
- Não explique conceitos básicos.
- Entregue o código pronto.
- Quando separar arquivos, mostrar o conteúdo completo de cada arquivo.

204
skills/reels/SKILL.md Normal file
View file

@ -0,0 +1,204 @@
---
type: workflow
name: reels
description: Criar cadeia de roteiros de Reels para divulgação de funcionalidades e módulos
scope: local
updatedAt: "2026-06-01"
---
# Workflow: Criar Roteiros de Reels
Este workflow gera **cadeias de roteiros de Reels** (vídeos curtos de 30 a 60 segundos) organizados por tema. Os roteiros são escritos em tom provocativo, informal e direto — prontos para gravar falando para a câmera ou com narração em off. O resultado é salvo em `./COMERCIAL/<nome-do-modulo>-reels.md`.
É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural`) em toda produção textual deste workflow.
---
## Público-Alvo dos Reels
Os vídeos serão assistidos pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
Regra geral: a linguagem deve ser **coloquial, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso quando citadas pela primeira vez.
---
## Pré-requisitos
Antes de gerar roteiros, o agente deve entender as funcionalidades reais do módulo. Se já existir o arquivo comercial (`./COMERCIAL/<nome-do-modulo>.md`), usá-lo como base. Caso contrário, ler o código-fonte para mapear o que o módulo entrega de fato.
---
## Passos
### 1. Identificar o tema
Perguntar ao usuário:
- Qual módulo ou funcionalidade será o tema dos reels?
- Quantos roteiros deseja na cadeia? (padrão: 6)
- Algum tom específico? (provocativo, educativo, humorístico)
### 2. Levantar contexto
Mapear:
- Quais **funcionalidades** do módulo geram mais impacto visual e prático?
- Quais **dores reais** o público-alvo enfrenta sem a solução?
- Existe **legislação ou norma** que possa ser usada como argumento de urgência?
- Quais **comparações do dia a dia** fazem sentido para o público?
### 3. Redigir a cadeia de roteiros
Cada cadeia deve conter **4 a 8 roteiros**, todos conectados pelo mesmo tema mas com abordagens diferentes. Cada roteiro segue a estrutura abaixo.
---
## Estrutura de um Roteiro
Cada roteiro deve ter entre **6 e 12 frases curtas**, organizadas em 4 blocos:
### Bloco 1 — Abertura (1-2 frases)
A primeira frase é a mais importante. Ela decide se o espectador para ou rola.
Técnicas obrigatórias (usar pelo menos uma por roteiro):
| Técnica | Exemplo |
|---|---|
| **Provocação direta** | "Se você ainda faz isso manual… tá perdendo dinheiro." |
| **Referência pop** | "Tá mais perdido que timeline de fofoca da Virgínia?" |
| **Formato "Plot twist"** | "Plot twist: você perde cliente não é pelo preço…" |
| **Convocação** | "Se sua proposta fosse convocada hoje… ela jogaria?" |
| **Contraste chocante** | "Expectativa: vou organizar meus processos. Realidade: caos." |
| **Pergunta retórica** | "Quantas horas você perdeu esse mês montando relatório?" |
| **Afirmação polêmica** | "A maioria dos consultores está jogando dinheiro fora." |
### Bloco 2 — Dor / Cenário ruim (2-3 frases)
Descrever o cenário do público-alvo SEM a solução. Usar linguagem do dia a dia — como se estivesse conversando com um colega.
Regras:
- Frases curtas e ritmadas (máximo 12 palavras por frase)
- Usar repetição para ritmo ("proposta pra um lado, orçamento pra outro…")
- Descrever ações reais, não conceitos ("anota no papel, perde foto, esquece detalhe")
- Pode usar humor leve e ironia
### Bloco 3 — Virada / Solução (2-3 frases)
Apresentar o produto como a virada. O nome do produto aparece aqui — naturalmente, sem parecer propaganda.
Regras:
- O produto é mencionado **uma única vez**, pelo nome
- Descrever o que o produto faz em **ações concretas**, não em conceitos
- Usar verbos de ação: "monta", "registra", "envia", "centraliza"
- Mostrar resultado imediato: "menos retrabalho", "mais fechamento"
### Bloco 4 — Fechamento / Desafio (1-2 frases)
Fechar com uma pergunta ou desafio que provoque o espectador a agir.
Técnicas:
- **Desafio direto**: "Quer ser titular ou continuar no banco?"
- **Escolha binária**: "Você decide em qual nível quer jogar."
- **Pergunta provocativa**: "Você tá otimizando ou só se ocupando?"
- **Chamada para ação suave**: "Começa a jogar no nível profissional."
---
## Estilos de Roteiro
Cada cadeia deve variar os estilos para manter o conteúdo diverso. O agente deve usar **pelo menos 4 estilos diferentes** numa cadeia de 6 roteiros.
| Estilo | Descrição | Ritmo |
|---|---|---|
| **Plot twist** | Começa com uma crença comum e inverte | Surpreendente |
| **Mais perdido que...** | Analogia cômica + caos do dia a dia | Humorístico |
| **Convocação** | Metáfora de seleção/time/jogo | Competitivo |
| **Raiz vs Smart** | Dois perfis contrastados | Comparativo |
| **Tempo é dinheiro** | Foco em produtividade e custo de oportunidade | Urgência |
| **Expectativa vs Realidade** | Contraste entre o plano e o caos | Identificação |
| **Se eu te contasse** | Narrativa de revelação progressiva | Curiosidade |
| **Checklist do fracasso** | Lista irônica do que NÃO fazer | Irônico |
---
## Regras de Entonação
O roteiro deve indicar **como falar** cada trecho. Usar marcações simples:
| Marcação | Significado |
|---|---|
| Texto normal | Tom de conversa, olhando pra câmera |
| *Texto em itálico* | Tom irônico ou de provocação |
| **Texto em negrito** | Ênfase, falar mais forte |
| `[pausa]` | Pausa dramática de 1-2 segundos |
| `[rápido]` | Falar em ritmo acelerado |
| `[sussurrando]` | Tom baixo, como se contasse um segredo |
---
## Regras de Redação
- **Frases curtas**: máximo 15 palavras por frase. Idealmente 8-12
- **Sem jargões de TI**: trocar termos técnicos por equivalentes do dia a dia
- **Tom coloquial**: "tá", "pra", "gente", "bobo" são permitidos e desejáveis
- **Referências culturais**: usar quando fizerem sentido para o público (futebol, reality, memes do momento). Marcar como `[ref: atualizar]` se a referência puder ficar datada
- **Uma ideia por frase**: cada frase deve ser compreensível isoladamente
- **Sem "Olá pessoal"**: nunca abrir com saudação genérica
- **Produto natural**: o nome do produto aparece no máximo 1 vez por roteiro, no bloco de solução
- **Siglas**: toda sigla usada pela primeira vez deve vir acompanhada do nome por extenso
---
## Checklist de Qualidade
Antes de entregar, validar **cada roteiro**:
- [ ] A primeira frase **para o scroll**? (provocação, surpresa ou identificação)
- [ ] O cenário da dor é **real e reconhecível** pelo público-alvo?
- [ ] O produto aparece **naturalmente**, sem parecer propaganda forçada?
- [ ] O fechamento **provoca ação** (pergunta, desafio ou escolha)?
- [ ] O roteiro tem entre **6 e 12 frases**?
- [ ] Cada frase tem no **máximo 15 palavras**?
- [ ] O tom é **coloquial e direto** (não institucional)?
- [ ] A cadeia usa **pelo menos 4 estilos diferentes**?
- [ ] Está **LIVRE** de jargões de TI?
- [ ] O roteiro funciona sendo **falado em voz alta**? (ler em voz alta para validar)
---
## Formato de Saída
O arquivo `./COMERCIAL/<nome-do-modulo>-reels.md` deve seguir esta estrutura:
```markdown
# Reels — [Nome do Módulo]
> Cadeia de [N] roteiros sobre [tema]
> Tom: [provocativo / educativo / humorístico]
> Duração média: 30-60 segundos por reel
---
## 🎥 Roteiro 1 – "[Título criativo]"
"[Primeira frase — abertura impactante]
[Bloco de dor — 2-3 frases curtas]
[Bloco de solução — 2-3 frases com o produto]
[Fechamento — pergunta ou desafio]"
---
## 🎥 Roteiro 2 – "[Título criativo]"
...
```
---
## Referências
- Workflow: `agents/comercial/workflows/comercial` (descrição comercial detalhada — base de contexto)
- Workflow: `agents/comercial/workflows/marketing` (peças de marketing por canal)
- Rule: `global/rules/escrita-natural` (padrão obrigatório de redação)

134
skills/refatorar-modulo/SKILL.md Normal file
View file

@ -0,0 +1,134 @@
---
type: workflow
name: refatorar-modulo
description: Fluxo completo de refatoração de um módulo, do diagnóstico à verificação
scope: local
updatedAt: "2026-06-19"
---
# Workflow: Refatorar Módulo
## Objetivo
Conduzir a refatoração de um módulo do ecossistema de forma segura, rastreável e fundamentada nos princípios do Refactoring.Guru.
## Gatilho
- Solicitação explícita de refatoração
- Módulo identificado com 3+ code smells em diagnóstico
- Preparação para nova feature que exige código limpo como pré-requisito
## Fluxo
```
┌─────────────┐ ┌───────────────┐ ┌──────────────┐
│ 1. DIAGNÓS- │───▶│ 2. SOLICITAR │───▶│ 3. PLANEJAR │
│ TICAR │ │ TESTES │ │ AÇÕES │
└─────────────┘ └───────────────┘ └──────────────┘
│
┌─────────────┐ ┌───────────────┐ ┌──────┴───────┐
│ 6. DOCUMEN- │◀───│ 5. VERIFICAR │◀───│ 4. EXECUTAR │
│ TAR │ │ TESTES │ │ REFAT. │
└─────────────┘ └───────────────┘ └──────────────┘
```
### Etapa 1: Diagnosticar
**Agente:** `@refatorar`
Executar a skill `diagnosticar-code-smells`:
- Listar code smells encontrados
- Identificar violações SOLID
- Recomendar Design Patterns aplicáveis
- Classificar por severidade (🔴 🟡 🟢)
**Saída:** Relatório de diagnóstico com plano de ação priorizado.
### Etapa 2: Solicitar Testes
**Agente:** `@refatorar` → `@testes`
Para cada trecho que será refatorado:
- Verificar se há testes cobrindo o comportamento
- Se não há: solicitar ao `@testes` criação de testes
- Aguardar confirmação de que testes passam
**Regra:** Nenhuma refatoração avança sem cobertura de testes. Sem exceções.
### Etapa 3: Planejar Ações
**Agente:** `@refatorar`
Para cada item do plano de ação:
1. Nomear a técnica de refatoração (ex: "Extract Method", "Replace Conditional with Strategy")
2. Identificar o princípio SOLID que será atendido
3. Estimar arquivos afetados
4. Definir ordem de execução (itens independentes primeiro)
**Formato:**
```markdown
| # | Técnica | Princípio | Arquivos | Dependência |
|---|---------|-----------|----------|-------------|
| 1 | Extract Method | S — SRP | servico.ts | Nenhuma |
| 2 | Strategy Pattern | O — OCP | calculador.ts, tipos.ts | Após #1 |
```
### Etapa 4: Executar Refatoração
**Agente:** `@refatorar`
Para cada item do plano, em ordem:
1. Aplicar a mudança em **passos pequenos**
2. Verificar que testes passam após cada passo
3. Não misturar refatoração com feature
**Passos típicos de uma refatoração:**
```
4.1 Extrair função/composable
4.2 Mover para arquivo adequado
4.3 Atualizar imports
4.4 Verificar testes → ✅
4.5 Próximo item
```
### Etapa 5: Verificar Testes
**Agente:** `@refatorar` + `@testes`
- Executar todos os testes do módulo
- Confirmar zero regressões
- Se algum teste falha: reverter último passo e investigar
### Etapa 6: Documentar
**Agente:** `@refatorar` → `@documentacao`
- Atualizar JSDoc se interfaces mudaram
- Registrar decisão em `.regras-negocio.md` se refatoração foi significativa
- Informar `@documentacao` sobre mudanças estruturais
**Formato do commit:**
```
refactor(<módulo>): <técnica aplicada>
- Problema: <code smell identificado>
- Solução: <padrão/técnica aplicada>
- Princípio: <princípio SOLID atendido>
```
## Critérios de Sucesso
- [ ] Todos os code smells críticos (🔴) resolvidos
- [ ] Todos os testes passam (zero regressões)
- [ ] Nenhum arquivo acima de 250 linhas
- [ ] Nenhum `any`/`as any` introduzido
- [ ] Fronteiras de pacote respeitadas
- [ ] Decisões documentadas
## Referências
- Skill: `agents/refatorar/skills/diagnosticar-code-smells/SKILL`
- Rule: `agents/refatorar/rules/refatoracao-segura`
- Rule: `agents/refatorar/rules/solid-compliance`
- Rule: `agents/refatorar/rules/design-patterns-pragmatico`
- Workflow global: `global/workflows/otimizar-codigos`

246
skills/ux/SKILL.md Normal file
View file

@ -0,0 +1,246 @@
---
type: workflow
name: ux
description: Revisar e otimizar UX de componentes e telas Vue (Frontend)
scope: global
updatedAt: "2026-06-01"
---
# Workflow: Revisão de UX
Guia de revisão e otimização de interfaces Vue 3 + Vuetify 3 no ecossistema Azteca — para usuários corporativos com baixa familiaridade tecnológica.
---
## Perfil do Usuário
O público-alvo das interfaces é corporativo e diversificado em experiência técnica:
- Gestores públicos e ambientais
- Técnicos de campo
- Consultores ambientais
- Operadores administrativos
**Premissa central**: o usuário não tem familiaridade avançada com tecnologia. A interface precisa ser autoexplicativa, sem dependência de treinamento prévio.
---
## Paleta de Cores Institucional
Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta** (primária), **Âmbar terroso** (apoio/aviso), **Cinza musgo** (neutros). Semânticas independentes para garantir reconhecimento universal.
### Escala primária — Verde floresta
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-primaria-bg` | `#EEF3D0` | 50 | Fundo de cards destacados, linhas ativas, hover suave |
| `--cor-eli-primaria-zebra` | `#F6F9E8` | 30 | Linha zebrada de tabelas (quase branco esverdeado) |
| `--cor-eli-primaria-suave` | `#BFC99C` | — | **Cabeçalho de tabela** — sage/olive mudo, sem limão, texto escuro |
| `--cor-eli-primaria-clara` | `#D4E290` | 100 | Badges, chips, seleção, fundo de hover em listas |
| `--cor-eli-primaria-media` | `#ADCC44` | 200 | Tags, indicadores secundários |
| `--cor-eli-primaria-acao` | `#8AAF00` | 400 | Ação secundária, ícones ativos |
| `--cor-eli-primaria` | `#688C00` | 600 | **Botões principais, links ativos, destaques — CTA principal** |
| `--cor-eli-primaria-escura` | `#4A6500` | 800 | Hover em botões, bordas ativas, títulos com ênfase |
| `--cor-eli-primaria-texto` | `#2E3F00` | 900 | Texto escuro sobre fundos claros da paleta primária |
### Escala de apoio — Âmbar terroso
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-alerta-bg` | `#FAF3DF` | 50 | Fundo de banners de aviso |
| `--cor-eli-alerta-clara` | `#F5DC8A` | 100 | Badges de atenção, chips de alerta |
| `--cor-eli-alerta` | `#DDB847` | 200 | Ícones de aviso, bordas de alerta |
| `--cor-eli-alerta-forte` | `#8C6A00` | 600 | Texto sobre fundo de alerta, status pendente |
### Escala neutra — Cinza musgo
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-fundo` | `#F2F3EE` | 50 | Background geral de páginas |
| `--cor-eli-borda` | `#D5D8CC` | 100 | Bordas padrão de containers |
| `--cor-eli-borda-forte` | `#B5BAA8` | 200 | Bordas de foco, divisores |
| `--cor-eli-neutro` | `#5E6553` | 600 | Textos secundários, ícones inativos |
| `--cor-eli-neutro-escuro` | `#3E4436` | 800 | Texto de label, cabeçalhos de tabela |
| `--cor-eli-superficie` | `#FFFFFF` | — | Cards, modais, popovers |
### Cores semânticas
| Token | Hex | Uso |
|---|---|---|
| `--cor-eli-sucesso` | `#2e7d32` | Confirmações, status positivo |
| `--cor-eli-sucesso-bg` | `#E8F5E9` | Fundo de mensagens de sucesso |
| `--cor-eli-erro` | `#c62828` | Erros, ações destrutivas |
| `--cor-eli-erro-bg` | `#FFEBEE` | Fundo de mensagens de erro |
| `--cor-eli-info` | `#1565c0` | Informações auxiliares |
| `--cor-eli-info-bg` | `#E3F2FD` | Fundo de banners informativos |
### Regras de contraste
- Texto sobre `--cor-eli-primaria` (`#688C00`) deve ser **branco** (`#ffffff`) — contraste 4.6:1 ✓
- Texto sobre `--cor-eli-primaria-bg` (`#EEF3D0`) deve ser `--cor-eli-primaria-texto` (`#2E3F00`) — contraste 12:1 ✓
- Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓
- Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓
- Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓
- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`.
- Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold).
---
## Passos
### 1. Identificar o escopo da revisão
Determinar qual componente, tela ou modal será revisado. Pode ser:
- Um componente isolado (ex: `EliTabela`, `EliCartao`)
- Uma página completa (ex: `PaginaCadastro.vue`)
- Um modal ou drawer (ex: `EliTabelaModalFiltroAvancado.vue`)
- Uma interação específica (ex: fluxo de filtro, paginação, menu de ações)
### 2. Mapear o estado atual
Antes de alterar, entender o que já existe:
- Ler o template (`<template>`) para entender a estrutura visual
- Ler o CSS/SCSS associado para mapear os tokens de design em uso
- Identificar quais componentes Vuetify estão sendo utilizados (ex: `v-btn`, `v-dialog`, `v-select`)
- Verificar se existem estilos inline que deveriam migrar para classes CSS
### 3. Avaliar contra os critérios de UX
Para cada elemento da interface, avaliar:
#### Clareza
- [ ] O propósito de cada elemento é óbvio sem instrução?
- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
- [ ] Ícones acompanham texto quando a ação não é universalmente reconhecível?
- [ ] O estado vazio (empty state) orienta o usuário sobre o próximo passo?
#### Hierarquia visual
- [ ] O olho do usuário é guiado para a ação principal primeiro?
- [ ] Ações primárias usam `--cor-eli-primaria` (`#688C00`) com destaque?
- [ ] Ações secundárias são visuais mas não competem com a primária?
- [ ] Ações destrutivas (Excluir, Limpar) usam `--cor-eli-erro` com variante `text` ou `outlined`?
#### Feedback e estados
- [ ] Botões têm estados claros de hover (`--cor-eli-primaria-escura`), focus e disabled (`--cor-eli-borda-forte`)?
- [ ] Carregamentos exibem indicador visual (spinner, skeleton, barra de progresso)?
- [ ] Erros de formulário aparecem próximos ao campo com mensagem descritiva, usando `--cor-eli-erro` + `--cor-eli-erro-bg`?
- [ ] Sucesso de operações tem confirmação visual (snackbar, toast, badge) com `--cor-eli-sucesso`?
#### Densidade e espaçamento
- [ ] O espaçamento segue múltiplos de 4px (4, 8, 12, 16, 24, 32)?
- [ ] Em desktop, o espaço horizontal é bem aproveitado? (ex: grids de 2+ colunas para formulários largos)
- [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
- [ ] Modais têm largura proporcional ao conteúdo?
#### Tipografia
- [ ] Tamanhos de fonte seguem a escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading)?
- [ ] Textos longos usam `line-height: 1.5` para legibilidade?
- [ ] Labels de formulário são visualmente distintos do conteúdo preenchido?
#### Acessibilidade básica
- [ ] Elementos interativos têm `aria-label` quando o texto visual não é suficiente?
- [ ] Foco via teclado (`Tab`) segue uma ordem lógica?
- [ ] Cores não são o único meio de comunicar estado (ex: ícone + cor para erro)?
- [ ] Todo texto sobre cor primária ou escura usa branco (`#FFFFFF`)?
- [ ] Todo texto sobre `--cor-eli-primaria-bg` usa `--cor-eli-primaria-texto` (`#2E3F00`)?
### 4. Aplicar padrões Vue/Vuetify do projeto
Ao implementar melhorias, seguir os padrões do ecossistema:
#### Componentes Vuetify
- Usar `v-btn` com variantes do tema (`color="primary"`) em vez de classes CSS manuais para botões
- Usar `v-dialog` para modais, `v-menu` para popovers contextuais
- Usar `v-text-field`, `v-select` etc. para inputs sempre que possível
- Aproveitar props de Vuetify: `density`, `variant`, `rounded`, `elevation`
#### Iconografia — Lucide (obrigatório)
Todos os ícones do projeto devem vir exclusivamente da biblioteca **`@lucide/vue`** (dependência já instalada no `package.json`).
**Proibido**:
- SVG inline manual (hardcoded no template)
- Ícones de `@mdi/font` ou Material Design Icons em componentes do projeto
- Bibliotecas alternativas (Font Awesome, Heroicons, etc.)
**Como usar**:
```vue
<template>
<!-- Uso direto como componente -->
<Filter :size="18" :stroke-width="2" />
<!-- Dentro de botão -->
<button>
<Plus :size="15" :stroke-width="2.5" />
Adicionar
</button>
</template>
<script lang="ts">
import { Filter, Plus, X, Trash2, Eye } from "@lucide/vue"
</script>
```
**Props úteis**: `:size` (número em px), `:stroke-width` (espessura do traço, padrão 2), `:color` (cor do ícone).
**Catálogo de referência**: https://lucide.dev/icons — buscar pelo nome do ícone em inglês.
> Os tokens CSS estão documentados nas tabelas da seção **Paleta de Cores Institucional** acima.
> No código, usar `var(--token, #fallback)` — sempre com fallback hardcoded em componentes de biblioteca.
- Classes devem seguir BEM: `eli-componente__elemento--modificador`
- Evitar `!important` — resolver especificidade via seletor mais específico
- Usar `var(--cor-eli-primaria)` em vez de valores hex hardcoded no CSS dos componentes
- Transições padrão: `transition: all 0.2s ease` para hover/focus
#### Composição de componentes
- Componentes filhos devem receber dados via `props` e emitir eventos via `$emit`
- Evitar acessar o DOM diretamente; preferir `ref` do Vue
- Não duplicar CSS entre componentes — extrair para classe utilitária ou CSS do componente pai
### 5. Implementar melhorias prioritárias
Ordenar as melhorias por impacto no usuário:
1. **Crítico**: elementos que causam confusão ou impedem o uso (falta de feedback, botão invisível, estado vazio sem orientação)
2. **Alto**: melhorias que reduzem atrito (espaçamento, hierarquia de botões, responsividade)
3. **Médio**: refinamentos visuais (transições, micro-animações, consistência de cores)
4. **Baixo**: polish (sombras sutis, arredondamentos, tipografia refinada)
### 6. Validar resultado
Após implementar:
- [ ] A tela renderiza sem erros no console?
- [ ] Os estados (vazio, carregando, erro, com dados) estão todos cobertos?
- [ ] A paleta de cores está coerente com a base `#688C00`?
- [ ] Todos os tokens usados estão definidos na escala primária, de apoio ou neutra?
- [ ] Nenhuma cor está hardcoded no CSS do componente (usar `var(--token, #fallback)`)?
- [ ] Tokens novos têm fallback hardcoded? (ex: `var(--cor-eli-primaria-suave, #BFC99C)`)?
- [ ] Contraste de texto validado: branco sobre `--cor-eli-primaria` e `--cor-eli-primaria-escura`; `--cor-eli-neutro-escuro` sobre `--cor-eli-primaria-suave`?
- [ ] Nenhuma ação ficou sem feedback visual?
- [ ] O layout não quebra em larguras menores que 1024px?
- [ ] Componentes Vuetify recebem props de tema (`color`, `variant`) em vez de override CSS?
- [ ] Efeito zebra de tabelas tem fundo branco explícito nas linhas normais (para funcionar sobre qualquer fundo de página)?
---
| ❌ Anti-padrão | ✅ Alternativa |
|---|---|
| Botão sem label de texto | Botão com ícone + texto, ou `aria-label` descritivo |
| Cor vermelha para ação primária | Vermelho apenas para destrutivas; primária usa `--cor-eli-primaria` |
| Modal com scroll extenso | Dividir em etapas ou usar drawer lateral |
| Tabela com 15+ colunas visíveis | Usar modal de colunas para ocultar secundárias |
| Estilos inline em template | Usar `<style scoped>` com tokens CSS e fallback |
| Cor hex hardcoded | Usar `var(--cor-eli-primaria, #688C00)` com fallback |