---
type: workflow
name: aprimorar-IA
description: Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação
scope: global
updatedAt: "2026-06-01"
---

# Workflow: Aprimorar Conhecimento da Aplicação

## 🎯 Objetivo

Garantir que **toda decisão tomada** seja imediatamente incorporada ao conhecimento estruturado da aplicação, mantendo o sistema de rules, workflows e skills **coerente, atualizado, não redundante e sem contradições**.

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** | — | `.agent/memoria/` | Registros históricos, contexto do projeto, fatos e decisões importantes |

### 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 (herdadas de `.agent/base/`):

| Skill | Escopo |
|-------|--------|
| `mapear-codigo-fonte` | Mapear e navegar a estrutura de qualquer monorepo TS |
| `diagnosticar-erros-build` | Diagnosticar erros de build em cascata entre pacotes |
| `documentar-decisao-tecnica` | Registrar decisões técnicas como ADRs |

### Skills de projeto (criadas localmente em cada monorepo):

Cada projeto pode criar skills adicionais específicas em `.agent/local/skills/<nome>/SKILL`.
Essas skills focam nos padrões e domínios exclusivos daquele projeto.

Exemplos de skills de projeto:

| Skill | Escopo |
|-------|--------|
| `criar-funcao-api` | Função de API end-to-end (comuns → back → front) |
| `criar-componente-vue3` | Componente Vue 3 com padrões obrigatórios do projeto |
| `consultar-banco-knex` | Queries Knex com padrões de leitura/escrita/JSONB |
| `implementar-permissoes` | Controle de acesso específico do domínio |

---

## 5️⃣ Atualização da Memória (Obrigatória quando aplicável)

### 5A — Memória Local (arquivos)

Sempre que decisões críticas sobre a arquitetura da aplicação ou o contexto do domínio precisarem ser arquivadas temporária ou permanentemente de maneira descritiva (e não diretamente injetável em código ou regra de lint):

* Registre o novo documento no formato adequado mantendo a pasta limpa em `.agent/memoria/`.
* Exemplo: Manter diário de pendências (`diario-pendencias-modulo-x`) ou ADR (`adr-001-migracao-nuxt-4`).
* Atenção! Tudo que puder ser abstraído para formato técnico estrito deve virar **Skill** ou **Rule**. Use a Memória local apenas como extensão de base factual.

### 5B — Memória Corporativa (API Azteca — OBRIGATÓRIO)

**Todo conhecimento gerado durante a sessão DEVE ser registrado na Memória Corporativa** (`https://memoria-ia.idz.one`) seguindo a rule `global/rules/coleta-automatica-memorias`.

#### Gatilhos automáticos de registro:

| Evento na sessão | Categoria | Tipo | Registrar? |
|-------------------|-----------|------|:---:|
| Bug resolvido não trivial | `solucao-problemas` | `solucao-problemas` | 🔴 Obrigatório |
| Decisão arquitetural tomada | `decisoes` | `adr` | 🔴 Obrigatório |
| Regra de negócio descoberta/alterada | `regras-negocio` | `nota` | 🔴 Obrigatório |
| Novo módulo ou funcionalidade | `modulos` | `referencia` | 🔴 Obrigatório |
| Padrão técnico definido/alterado | `tecnologias` | `referencia` | 🔴 Obrigatório |
| Migração de banco executada | `tecnologias` | `referencia` | 🟡 Recomendado |
| Componente/padrão de UI definido | `tecnologias` | `referencia` | 🟡 Recomendado |
| Refatoração significativa | `decisoes` | `adr` | 🟡 Recomendado |

#### Protocolo:

1. **Buscar antes de criar** — evitar duplicatas (`POST /api/busca`)
2. **Criar com qualidade** — `titulo` pesquisável, `resumo` obrigatório, mínimo 3 `tags`, `criado_por` com @
3. **Vincular** — relacionar com memórias existentes via `/api/vinculos/criar`
4. **Contextualizar** — preencher `contexto` com nome do projeto/módulo

#### Exemplo de registro automático:

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "titulo": "MODULO — Descrição clara do que foi feito/decidido",
    "conteudo": "### Contexto\n...\n### Decisão\n...\n### Impacto\n...",
    "resumo": "Síntese curta e pesquisável (10-500 chars)",
    "categoria": "CATEGORIA",
    "tipo": "TIPO",
    "tags": ["modulo", "tag2", "tag3"],
    "contexto": "NOME-DO-PROJETO",
    "criado_por": "@HANDLE_DO_AGENTE"
  }'
```

> ⚠️ **Anti-padrão:** Encerrar sessão do workflow `aprimorar-IA` sem ter registrado na Memória Corporativa é considerado **trabalho incompleto**.

---

## 6️⃣ 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
* [ ] **Conhecimento da sessão foi registrado na Memória Corporativa** (API Azteca)
* [ ] **Memórias criadas possuem `resumo`, `tags` (≥3) e `criado_por` com @**
* [ ] **Memórias relacionadas foram vinculadas** via `/api/vinculos/criar`

---

## ⚠️ 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.