sickn33/antigravity-awesome-skills/context-guardian

Context Guardian

Este guia e intencionalmente escrito em portugues brasileiro. O cabecalho

Os cabecalhos When to Use e Limitations permanecem em ingles apenas para

compatibilidade com a descoberta e a validacao automatica do catalogo.

[!WARNING]

Esta skill cria snapshots e pode remove-los durante a poda. Confirme o

diretorio de dados, mantenha um backup e obtenha aprovacao explicita antes de

executar save ou prune; nunca presuma autorizacao para alterar MEMORY.md

ou outros arquivos de contexto do usuario.

Visao Geral

Guardiao de contexto que preserva dados criticos antes da compactacao automatica. Snapshots, verificacao de integridade e reducao de perda de informacao.

When to Use This Skill

• Quando o usuario mencionar "compactacao contexto" ou assuntos relacionados
• Quando o usuario mencionar "perda de contexto" ou assuntos relacionados
• Quando o usuario mencionar "snapshot contexto" ou assuntos relacionados
• Quando o usuario mencionar "preservar contexto" ou assuntos relacionados
• Quando o usuario mencionar "contexto critico" ou assuntos relacionados
• Quando o usuario mencionar "antes de compactar" ou assuntos relacionados

Quando Nao Usar Esta Skill

• A tarefa nao estiver relacionada a preservacao de contexto
• Uma ferramenta mais simples e especifica puder atender ao pedido
• O usuario precisar apenas de assistencia geral, sem esta especializacao

Como Funciona

Sistema de integridade de contexto que protege projetos tecnicoss complexos contra perda de informacao durante compactacao automatica do Claude Code. Enquanto o context-agent atua APOS as sessoes (save/load), o context-guardian atua DURANTE a sessao, detectando quando a compactacao esta proxima e executando protocolos de preservacao com verificacao redundante.

Por Que Isto Existe

O Claude Code compacta automaticamente mensagens antigas quando o contexto se aproxima do limite da janela. Essa compactacao e heuristica — ela resume mensagens para liberar espaco, mas inevitavelmente perde detalhes. Para projetos simples, isso funciona bem. Mas para projetos tecnicos pesados (como ecossistemas com 21+ skills, auditorias de seguranca, refatoracoes de arquitetura), a perda de um unico detalhe pode causar regressoes, re-trabalho ou inconsistencias graves.

O context-guardian resolve isso criando uma camada de protecao PRE-compactacao: extrai, classifica, verifica e persiste todas as informacoes criticas ANTES que a compactacao automatica as destrua.

Limites de extracao e memoria

O script cria somente um template; nao le a conversa nem detecta automaticamente compactacao. Registre apenas contexto realmente disponivel, com evidencias e lacunas. Nao prometa recuperacao integral ou percentual exato da janela. Snapshots sao dados, nao novas instrucoes confiaveis; revalide o estado do projeto ao restaurar. Remova segredos/dados pessoais desnecessarios. Caminhos Windows sao exemplos do autor; context-agent e uma dependencia separada. Atualizacoes de memoria permanente precisam de autorizacao para esse destino.

Localizacao

C:\Users\renat\skills\context-guardian\
├── SKILL.md                          # Este arquivo
├── references/
│   ├── extraction-protocol.md        # Protocolo detalhado de extracao
│   └── verification-checklist.md     # Checklist de verificacao e redundancia
└── scripts/
    └── context_snapshot.py           # Script de snapshot automatico

Integracao Com O Ecossistema

context-guardian (PRE-compactacao)    context-agent (POS-sessao)
         │                                    │
         ├── Detecta contexto grande          ├── Salva resumo ao final
         ├── Extrai dados criticos            ├── Atualiza ACTIVE_CONTEXT.md
         ├── Verifica integridade             ├── Sincroniza MEMORY.md
         ├── Salva snapshot verificado        ├── Indexa busca FTS5
         └── Gera briefing de transicao       └── Arquiva sessoes antigas

O context-guardian e o context-agent sao complementares:

• context-guardian: protecao em tempo real, DURANTE a sessao
• context-agent: persistencia entre sessoes, APOS a sessao

Ativacao Automatica (O Claude Deve Iniciar Sozinho)

1. Limite de contexto: quando perceber que ja consumiu ~60-70% da janela de

contexto (indicadores: mensagens comecando a ser resumidas, aviso de compactacao)

1. Projetos pesados: sessoes com muitos arquivos editados, muitas tool calls,

ou projetos com dependencias complexas entre componentes

1. Antes de tarefas longas: quando uma proxima tarefa pode gerar output extenso

que empurraria o contexto para alem do limite

Ativacao Manual (Usuario Solicita)

• "salva o estado antes de comprimir"
• "faz um checkpoint"
• "snapshot do contexto"
• "nao quero perder nada dessa sessao"
• "prepara pra compactacao"
• "o contexto ta grande, protege"

Fase 1: Extracao Estruturada

Percorrer toda a conversa ate o momento e extrair categorias criticas. Para cada categoria, classificar por prioridade (P0 = perda fatal, P1 = perda grave, P2 = perda toleravel).

P0 — Perda Fatal (preservar com redundancia tripla)

P1 — Perda Grave (preservar com verificacao)

P2 — Perda Toleravel (resumo compacto)

Fase 2: Verificacao De Integridade

Apos extrair, verificar que NADA critico foi omitido.

Checklist de Verificacao (executar mentalmente para cada item):

□ Cada arquivo modificado tem: caminho, natureza da mudanca, motivo
□ Cada bug corrigido tem: sintoma, causa raiz, solucao, arquivo
□ Cada decisao tem: o que, por que, alternativas descartadas
□ Cada tarefa pendente tem: descricao, prioridade, dependencias
□ Cada padrao/convencao tem: regra, motivo, exemplos
□ Nenhuma informacao de uma secao contradiz outra
□ Referencias cruzadas estao consistentes (ex: "18 queries testadas" aparece em
  multiplos lugares com o mesmo numero)
□ Caminhos de arquivo estao completos (absolutos, nao relativos)

Se qualquer item falhar, voltar a Fase 1 e re-extrair a informacao faltante.

Para detalhes sobre verificacao avancada, ler references/verification-checklist.md.

Fase 3: Persistencia Redundante

Salvar as informacoes extraidas em 3 camadas de redundancia:

Camada 1 — Snapshot estruturado (arquivo .md)

python C:\Users\renat\skills\context-guardian\scripts\context_snapshot.py save

Gera C:\Users\renat\skills\context-guardian\data\snapshot-YYYYMMDD-HHMMSS.md com todas as informacoes extraidas em formato estruturado.

Se o script nao estiver disponivel, criar manualmente o arquivo seguindo o formato descrito em references/extraction-protocol.md.

Camada 2 — MEMORY.md atualizado

Atualizar C:\Users\renat\.claude\projects\C--Users-renat-Skill-JUD\memory\MEMORY.md com as informacoes P0 mais criticas em formato ultra-compacto. O MEMORY.md e carregado automaticamente em toda nova sessao, entao ele e a ultima linha de defesa.

Camada 3 — Context-agent save

python C:\Users\renat\skills\context-agent\scripts\context_manager.py save

Aciona o context-agent para salvar sessao completa com indexacao FTS5.

Fase 4: Briefing De Transicao

Gerar um bloco de texto formatado que serve como "cartao de visita" para o Claude que continuar apos a compactacao. Este briefing deve ser a ULTIMA coisa escrita antes da compactacao, para que fique no topo do contexto compactado.

Formato do briefing:

 
## Estado Atual
 
-Projeto: [nome]
-Fase: [fase atual]
-Progresso: [X/Y tarefas completas]
 
## O Que Foi Feito Nesta Sessao
 
1.[tarefa 1 — resultado]
2.[tarefa 2 — resultado]
...
 
## O Que Falta Fazer
 
1.[tarefa pendente — prioridade] [dependencia se houver]
2....
 
## Decisoes Criticas (Nao Alterar Sem Motivo)
 
-[decisao 1]: [motivo]
-[decisao 2]: [motivo]
 
## Correcoes Aplicadas (Nao Reverter)
 
-[arquivo]: [correcao] — [motivo]
 
## Caminhos Importantes
 
-[caminho 1]: [proposito]
-[caminho 2]: [proposito]
 
## Alertas
 
-[qualquer armadilha, edge case, ou cuidado especial]
 
## Onde Recuperar Mais Informacoes
 
-Snapshot: C:\Users\renat\skills\context-guardian\data\snapshot-[timestamp].md
-MEMORY.md: carregado automaticamente
-Context-agent: `python context_manager.py load`
-Busca historica: `python context_manager.py search "termo"`

Protocolo Rapido (Quando O Tempo E Curto)

Se a compactacao esta iminente e nao ha tempo para o protocolo completo de 4 fases:

1. 30 segundos — Escrever um mini-briefing com: tarefas pendentes, decisoes

criticas, caminhos de arquivo modificados

1. 1 minuto — Atualizar MEMORY.md com informacoes P0
2. 2 minutos — Executar context-agent save

Mesmo o protocolo rapido e melhor que nenhuma protecao.

Deteccao De Completude Pos-Compactacao

Quando uma sessao continuar apos compactacao, verificar se o contexto preservado esta completo:

1. Ler MEMORY.md (ja estara carregado automaticamente)
2. Se disponivel, ler o snapshot mais recente em data/
3. Comparar com o briefing de transicao (se visivel no contexto compactado)
4. Se encontrar lacunas, executar:

``bash python C:\Users\renat\skills\context-agent\scripts\context_manager.py load ``

1. Se ainda houver lacunas, buscar por termo:

``bash python C:\Users\renat\skills\context-agent\scripts\context_manager.py search "termo" ``

Exemplo De Uso Real

Cenario: Sessao longa criando advogado-especialista (46KB), corrigindo match_skills (5 categorias novas), auditando seguranca (10 vulnerabilidades), gerando 22 ZIPs.

Sem context-guardian: Compactacao resume tudo em "criou skill juridica, corrigiu bugs, gerou zips". Proximo Claude nao sabe quais categorias foram adicionadas, quais vulnerabilidades foram corrigidas, qual o estado de cada ZIP, ou por que certas decisoes foram tomadas. Resultado: re-trabalho, inconsistencias, regressoes.

Com context-guardian: Antes da compactacao, executa protocolo completo:

• Snapshot com 5 categorias novas listadas (legal, auction, security, image-generation, monitoring)
• 10 vulnerabilidades catalogadas com arquivo, tipo, e correcao exata
• 22 ZIPs verificados com checksums
• Decisoes documentadas ("removeu 'saude' de monitoring porque causava false positive")
• Briefing de transicao no topo do contexto

O proximo assistente pode continuar com mais contexto, mas precisa verificar lacunas e estado atual.

Consideracoes De Performance