.agent/global/skills/aprimora-ia/SKILL.md

type	name	description	scope	updatedAt
workflow	aprimora-ia	Otimizar o ecossistema da IA conforme identificado durante a conversa e registrar eventos na memória	global	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/rules/	.agent/rules/	Restrições e convenções que o agente deve respeitar sempre
Workflows	.agent/workflows/	.agent/workflows/	Processos sequenciais com passos numerados para tarefas bem definidas
Skills	.agent/skills/	.agent/skills/	Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes
Memória das Ações da IA	—	<base_projeto>/memorias-ia/	Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai)

🧩 Polimorfismo do .agent e Identidade por Projeto: O .agent é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do .agent:

• ./memorias-ia/modulo.yml (na raiz do projeto pai): Arquivo mandatório com modulo-id, modulo-caminho, modulo-descricao, modulo-tipo, modulo-acesso e modulo-wiki.
• ./memorias-ia/: Registros de ações, sessões e decisões da IA.
• <modulo-wiki>/<modulo-id>/: Documentação funcional com acesso dos usuários na aplicação VitePress (fallback de wiki: ../wiki/).
• <modulo-wiki>/dev/<modulo-id>/: Documentação técnica com acesso interno dev na aplicação VitePress.

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:

# 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:

---
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.