.agent/workflows/aprimorar-IA.global.md

---
type: workflow
name: aprimorar-IA
description: Dois comandos para extrair conhecimento das conversas e aplicá-lo nas estruturas do ecossistema de agentes
scope: global
updatedAt: "2026-07-02"
---

# Workflow: Aprimorar IA Global

## 🎯 Visão Geral

Este workflow opera em **duas fases independentes**, cada uma com um comando próprio:

| Comando | Fase | O que faz |
|---------|------|-----------|
| `aprimorar-ia-global` | **Captura** | Lê a conversa, extrai conhecimento e registra na Memória Corporativa |
| `aplicar-aprimorar-ia-global` | **Aplicação** | Lê a Memória Corporativa e atualiza as estruturas do ecossistema (rules, workflows, skills, agent.json) |

As fases são **intencionalmente desacopladas**: a captura pode ocorrer em qualquer conversa; a aplicação pode ser executada depois, inclusive em sessão separada.

---

## FASE 1 — `aprimorar-ia-global`

### Objetivo

Varrer a conversa atual, identificar conhecimento útil e registrá-lo na Memória Azteca (`https://memoria-ia.idz.one`) sem modificar nenhum arquivo do ecossistema.

### Quando executar

- Ao final de qualquer conversa em que houve:
  - Decisões arquiteturais ou técnicas novas
  - Padrões definidos ou alterados
  - Bugs encontrados e resolvidos
  - Regras de negócio descobertas
  - Qualquer conhecimento que beneficiaria sessões futuras

### Passo 1 — Analisar a conversa

Ler integralmente o histórico da conversa atual e identificar cada item de conhecimento extraível:

```
Para cada item descoberto, classificar:
  - É uma DECISÃO arquitetural? → categoria: decisoes, tipo: adr
  - É um PADRÃO técnico?        → categoria: tecnologias, tipo: referencia
  - É uma SOLUÇÃO de problema?  → categoria: solucao-problemas, tipo: solucao-problemas
  - É uma REGRA DE NEGÓCIO?     → categoria: regras-negocio, tipo: referencia
  - É info de MÓDULO/CONTEXTO?  → categoria: modulos, tipo: referencia
```

### Passo 2 — Buscar duplicatas antes de registrar

Para cada item identificado, verificar se já existe na memória:

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"termo": "PALAVRAS_CHAVE_DO_ITEM"}' | jq '.items[].titulo'
```

- Se existir: **editar** (`/api/memorias/editar`) em vez de criar novo
- Se não existir: **criar** novo registro

### Passo 3 — Registrar na Memória Corporativa

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "titulo": "Título claro e pesquisável",
    "conteudo": "Descrição detalhada com contexto, decisão e motivo",
    "resumo": "Síntese de 10-500 chars — alimenta a busca vetorial",
    "categoria": "CATEGORIA_ADEQUADA",
    "tipo": "TIPO_ADEQUADO",
    "tags": ["aprimorar-ia", "tag-adicional"],
    "contexto": "Nome do módulo ou projeto",
    "criado_por": "@ag-agente"
  }' | jq '{codigo: .codigo, titulo: .titulo}'
```

> **`resumo` é obrigatório** — sem ele a API retorna erro 400.
>
> **`aprimorar-ia` é a tag padrão** — toda memória registrada por este workflow DEVE incluí-la. Ela é o identificador que permite à Fase 2 recuperar exatamente esses registros.

### Passo 4 — Criar vínculos (quando aplicável)

Se o item registrado está relacionado a memórias já existentes:

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo_memoria_a": NOVO_ID,
    "codigo_memoria_b": EXISTENTE_ID,
    "relacao": "{mem:NOVO_ID} expande o padrão de {mem:EXISTENTE_ID}",
    "criado_por": "@ag-agente"
  }'
```

### Checklist da Fase 1

- [ ] Conversa lida integralmente
- [ ] Todos os itens de conhecimento identificados e classificados
- [ ] Duplicatas verificadas antes de criar
- [ ] `resumo` preenchido em todos os registros
- [ ] Vínculos criados entre memórias relacionadas
- [ ] Nenhum código-fonte, log ou dado sensível foi registrado

---

## FASE 2 — `aplicar-aprimorar-ia-global`

### Objetivo

Ler os registros recentes da Memória Corporativa e traduzir o conhecimento acumulado em mudanças concretas nas estruturas do ecossistema: `global/rules/`, `global/workflows/`, `global/skills/`, `agents/*/persona`, `agents/*/agent.json`.

### Quando executar

- Quando houver registros na memória que ainda não foram aplicados ao ecossistema
- Após um conjunto de conversas de aprendizado (`aprimorar-ia-global`) acumular massa crítica
- Antes de atualizar projetos que usam o ecossistema como submodulo

### Passo 1 — Consultar registros relevantes da memória

A tag `aprimorar-ia` é o filtro primário — recupera exatamente os registros capturados pela Fase 1:

```bash
# Buscar todos os registros pendentes de aplicação (tag aprimorar-ia, sem tag aplicado-no-ecossistema)
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"tags": ["aprimorar-ia"], "limite": 50}' | jq '.items[] | {codigo, titulo, resumo, tags}'
```

Se precisar filtrar por categoria específica:

```bash
# Apenas decisões arquiteturais ainda não aplicadas
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"tags": ["aprimorar-ia"], "categoria": "decisoes", "limite": 20}' | jq '.items[] | {codigo, titulo, resumo}'
```

> Registros com a tag `aplicado-no-ecossistema` já foram processados e podem ser ignorados.

### Passo 2 — Classificar cada item pelo tipo de mudança

Para cada registro da memória, determinar o impacto:

```
ITEM DA MEMÓRIA → AÇÃO NO ECOSSISTEMA
─────────────────────────────────────────────────────────────────
Convenção que agentes DEVEM respeitar sempre  → CRIAR/ATUALIZAR rule em global/rules/
Processo repetível com etapas definidas       → CRIAR/ATUALIZAR workflow em global/workflows/
Guia operacional complexo e reutilizável      → CRIAR/ATUALIZAR skill em global/skills/
Escopo ou comportamento de um agente          → ATUALIZAR persona do agente em agents/*/persona
Padrão novo sem impacto em artefatos          → Nenhuma ação (permanece só na memória)
```

### Passo 3 — Aplicar mudanças nos artefatos

#### Criar ou atualizar uma rule global

Arquivo em `global/rules/<nome-em-kebab-case>`:

```markdown
---
type: rule
name: nome-da-rule
description: O que a rule faz em uma linha
scope: global
trigger: always_on | context_match | file_match
priority: alta | normal
updatedAt: "AAAA-MM-DD"
---

# Regra: Nome

## Contexto
Quando se aplica.

## Regra
Definição objetiva e obrigatória.

## Exemplos
✅ Correto
❌ Incorreto

## Impacto
Problema que evita.

## Referências
- Memória: https://memoria-ia.idz.one (código: MEM_ID)
```

#### Criar ou atualizar um workflow global

Arquivo em `global/workflows/<nome>.global.md`.

#### Criar ou atualizar uma skill global

Arquivo em `global/skills/<nome>/SKILL` (sem extensão).

### Passo 4 — Regenerar os `agent.json`

Após qualquer mudança em `global/rules/` ou personas:

```bash
# No repositório raiz do ecossistema
sh adaptadores/antigravity/gerar-agent-json.sh

# Para um agente específico
sh adaptadores/antigravity/gerar-agent-json.sh ag-back
```

### Passo 5 — Verificar consistência

```bash
# Nenhum arquivo acima de 250 linhas
sh verificar-linhas.sh

# Regenerar manifesto
sh gerar-manifesto.sh
```

### Passo 6 — Atualizar memórias após aplicação

Após aplicar cada item ao ecossistema, avaliar a relevância contínua da memória e agir conforme o caso:

#### Caso A — Memória ainda relevante (manter)

Se o conhecimento ainda é útil para consultas futuras (contexto histórico, referência de padrão, ADR):

1. **Remover a tag `aprimorar-ia`** — ela não precisa mais ser reprocessada
2. **Atualizar o conteúdo** se houver informação complementar gerada durante a aplicação
3. **Adicionar `aplicado-no-ecossistema`** para rastreabilidade

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/editar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo": "CODIGO_DA_MEMORIA",
    "tags": ["aplicado-no-ecossistema"],
    "atualizado_por": "@ag-agente"
  }'
```

> **Atenção:** ao editar `tags`, envie **apenas as tags que devem permanecer** — a tag `aprimorar-ia` é removida simplesmente por não ser incluída na lista.

#### Caso B — Memória sem mais relevância (remover ou ocultar)

Se o conhecimento foi totalmente absorvido pelo ecossistema e não agrega valor como referência futura (itens pontuais, contexto temporário, bugs já superados):

**Opção 1 — Exclusão lógica** (preferida: mantém histórico, oculta das buscas)

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/excluir" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{"codigo": "CODIGO_DA_MEMORIA"}'
```

**Opção 2 — Sinalizar como obsoleta** (quando há valor histórico, mas não operacional)

```bash
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/sinalizar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
  -d '{
    "codigo": "CODIGO_DA_MEMORIA",
    "obsoleto": true,
    "motivo": "Conhecimento integrado ao ecossistema em AAAA-MM-DD",
    "sinalizado_por": "@ag-agente"
  }'
```

#### Critérios de decisão

| Situação | Ação |
|----------|------|
| Decisão arquitetural (ADR), padrão ou regra de negócio duradoura | **Manter** — remove `aprimorar-ia`, adiciona `aplicado-no-ecossistema` |
| Solução de problema genérica (workaround reutilizável) | **Manter** — idem acima |
| Contexto pontual de uma conversa, já registrado em artefato | **Excluir** logicamente |
| Bug específico já resolvido e sem valor futuro | **Excluir** logicamente |
| Item com valor histórico mas sem uso operacional | **Sinalizar** como obsoleta |

### Checklist da Fase 2

- [ ] Memória consultada e registros relevantes identificados
- [ ] Cada item classificado pelo tipo de mudança (rule/workflow/skill/persona)
- [ ] Artefatos criados ou atualizados com frontmatter correto
- [ ] Nenhuma duplicação entre `global/` e `agents/*/`
- [ ] Referências cruzadas apontam para caminhos válidos (sem extensão)
- [ ] `agent.json` regenerados após mudanças em rules ou personas
- [ ] `manifesto.json` regerado via `sh gerar-manifesto.sh`
- [ ] Cada memória tratada após aplicação (Caso A ou Caso B do Passo 6)
- [ ] Alterações informadas ao usuário para commit

---

## Tipos de Artefatos — Referência Rápida

| Artefato | Local | Responsabilidade |
|----------|-------|------------------|
| **Rule** | `global/rules/<nome>` | Restrições que agentes **devem respeitar sempre** |
| **Workflow** | `global/workflows/<nome>.global.md` | Processos sequenciais acionados por comando |
| **Skill** | `global/skills/<nome>/SKILL` | Guias operacionais completos e reutilizáveis |
| **Persona** | `agents/<nome>/persona` | Identidade, escopo e comportamento do agente |
| **agent.json** | `agents/<nome>/agent.json` | Compilado: persona + rules globais + rules locais |

### 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 → **Skill**
- Se é **comportamento ou escopo de um agente** → **Persona**

---

## Referências

- Skill: `global/skills/memoria-persistente/SKILL` (API completa da Memória Azteca)
- Rule: `global/rules/usar-memoria-persistente`
- Rule: `global/rules/autonomia-agente`
- Script: `adaptadores/antigravity/gerar-agent-json.sh`
- Script: `gerar-manifesto.sh`