archive

Visão geral da skill archive

O que a archive faz bem

A skill archive é voltada para equipes e builders solo que querem transformar conhecimento pontual de uma sessão em memória reutilizável do projeto. Em vez de deixar correções enterradas no histórico do chat, ela salva resoluções de debugging, notas de deploy e aprendizados de processo em .archive/YYYY-MM-DD/ como markdown estruturado, e depois mantém um índice leve em .archive/MEMORY.md.

Quem deve instalar a archive

Esta skill archive é mais indicada para quem volta repetidamente aos mesmos problemas de infraestrutura, CI, release ou debugging e quer recuperar contexto com mais rapidez no futuro. Ela é especialmente útil quando o trabalho se espalha por várias sessões, múltiplos agentes ou vários colaboradores que precisam de um registro compartilhado de “o que aconteceu da última vez?”.

A necessidade real que ela resolve

Os usuários não precisam de mais um hábito de anotações. Eles precisam de uma forma confiável de capturar contexto técnico de alto valor logo depois que uma tarefa relevante termina e de trazer esse contexto à tona antes da próxima tarefa parecida começar. A archive foi desenhada para esse fluxo de trabalho, não para documentação genérica.

Por que a archive é diferente de um prompt comum

Um prompt comum pode pedir para a IA “resumir o que fizemos”. A skill archive adiciona um padrão de armazenamento repetível, uma atualização obrigatória do índice de memória e um hook de início de sessão que carrega .archive/MEMORY.md automaticamente quando o arquivo existe. Isso torna archive for Knowledge Bases algo prático: o arquivo passa a fazer parte do contexto de trabalho futuro, e não vira apenas mais um markdown esquecido.

Tradeoffs principais antes de instalar

A archive é intencionalmente simples. Ela não oferece banco de dados, busca vetorial nem pipeline automatizado de categorização. O valor dela vem de estrutura de arquivos disciplinada, tags pesquisáveis e um índice de memória. Se sua equipe não vai manter .archive/MEMORY.md, a skill archive perde boa parte da vantagem.

Como usar a skill archive

archive install e os arquivos do repositório para ler primeiro

Um caminho prático de archive install é:

1. Adicionar a skill do repositório ReScienceLab/opc-skills no seu sistema de skills.
2. Ler primeiro skills/archive/SKILL.md para entender o fluxo.
3. Ler skills/archive/references/TEMPLATE.md para ver o formato obrigatório do archive.
4. Ler skills/archive/hooks/hooks.json e skills/archive/hooks/load-memory.py se startup context loading for importante para você.
5. Conferir skills/archive/.factory-plugin/plugin.json para confirmar o comportamento pretendido.

Se você for passar rápido por apenas um arquivo de apoio, escolha references/TEMPLATE.md; ele mostra como é uma “boa saída de archive” na prática.

O que a skill archive precisa como entrada

A skill archive funciona melhor quando você fornece:

• a tarefa ou incidente concluído
• o resultado principal
• os passos-chave executados
• os comandos críticos, mudanças de configuração ou decisões de código
• os pontos de falha e as correções finais
• a categoria e as tags mais prováveis
• qualquer entrada antiga de archive relacionada

Sem essas informações, o archive tende a ficar vago demais para ajudar depois.

Quando acionar o uso da archive

Use archive depois de:

• um deploy bem-sucedido
• uma sessão de debugging complicada
• uma migração ou mudança de infraestrutura
• a conclusão de uma funcionalidade importante
• qualquer instrução do usuário como “archive this”

Não use para toda edição pequena. A skill foi feita para aprendizados duráveis, não para logs barulhentos de atividade.

Como o uso da archive funciona na prática

O fluxo esperado é:

1. Verificar .archive/MEMORY.md em busca de trabalho anterior relacionado.
2. Criar ou reutilizar .archive/YYYY-MM-DD/.
3. Escrever um archive em markdown usando a estrutura do template e YAML frontmatter.
4. Adicionar uma linha de índice em .archive/MEMORY.md.
5. Ligar entradas relacionadas com o campo related.

Essa atualização do índice não é burocracia opcional. É o que torna a consulta futura rápida.

Um prompt melhor para a skill archive

Prompt fraco:

• “Archive esta sessão.”

Prompt melhor:

• “Use the archive skill to document today’s ECS deploy issue. Include the IAM permission error, the CloudWatch clue, the exact fix, final deploy status, tags for ecs, iam, deploy, category infrastructure, and add a one-line entry to .archive/MEMORY.md. If a related archive exists, link it.”

A versão mais forte dá estrutura suficiente para o modelo produzir algo que você realmente consiga reutilizar.

Como transformar um objetivo vago em um pedido completo de archive

Se seu objetivo bruto é “salvar o que aprendemos”, expanda para:

• o que aconteceu
• por que isso importou
• o que falhou
• o que resolveu
• o que deve ser checado primeiro na próxima vez
• em que categoria isso se encaixa
• como alguém deve encontrar isso depois pelas tags

Esta skill recompensa escrita orientada à recuperação de informação, não escrita narrativa.

Os campos do template archive que mais importam

De references/TEMPLATE.md, os campos mais importantes são:

• tags: para recuperação via grep
• category: para organização do índice
• related: para conectar incidentes ao longo do tempo

No corpo, as seções mais valiosas costumam ser:

• Summary
• Issues Encountered & Solutions
• Key Changes

Se você pular os detalhes concretos da correção, o archive perde muito da utilidade.

Como o hook de memória no início da sessão muda o uso

O hook carrega .archive/MEMORY.md para o contexto da sessão no início, quando o arquivo existe. Isso significa que a skill archive não serve só para escrever; ela também melhora a recuperação futura automaticamente. Em termos de adoção, esse é um dos motivos mais fortes para instalar a skill em vez de usar um arquivo de notas improvisado.

archive for Knowledge Bases e memória de equipe

Para archive for Knowledge Bases, pense em .archive/MEMORY.md como um sumário e em cada arquivo markdown datado como o registro de um incidente ou tarefa. Isso funciona bem para:

• problemas operacionais recorrentes
• checklists de release com pegadinhas
• correções específicas de ambiente
• decisões de design com consequências

É menos adequado para documentação ampla de produto ou manuais voltados ao usuário.

Fluxo prático de busca e consulta

A skill archive oferece suporte explícito a busca leve:

• revisar .archive/MEMORY.md
• usar grep -ri "keyword" .archive/

Isso já basta para muitas equipes de engenharia, porque o conteúdo armazenado é mais estreito, técnico e estruturado. Use tags que as pessoas realmente pesquisariam depois: nomes de serviços, strings de erro, nomes de plataformas e nomes de componentes.

FAQ da skill archive

Vale a pena instalar a archive se eu já faço anotações?

Sim, se suas anotações atuais são difíceis de encontrar ou nunca voltam para o contexto do agente. A skill archive é útil porque padroniza localização, estrutura, indexação e carregamento de memória no início da sessão.

Esta skill archive é amigável para iniciantes?

Sim, em grande parte. O fluxo é simples: markdown mais um arquivo de índice. O principal risco para iniciantes é escrever resumos abstratos demais. A skill fica mais fácil de usar se você copiar o template e preencher correções específicas, comandos e aprendizados.

Quando eu não devo usar a archive?

Não use archive para:

• edições triviais
• brainstorming temporário
• documentação longa
• conhecimento que deveria estar em documentação permanente do repositório, como README.md ou runbooks

Se a informação deve orientar todos os colaboradores o tempo todo, talvez ela pertença à documentação padrão, e não apenas em .archive/.

Como a archive é diferente da documentação normal do projeto?

A documentação normal descreve o sistema pretendido. O uso de archive registra o que realmente aconteceu durante uma tarefa ou incidente: os caminhos que falharam, a correção exata e o contexto que normalmente se perde. É uma camada histórica de memória operacional, não um substituto para a documentação canônica.

A archive exige tooling especial?

Não muito. O formato central é composto por arquivos markdown mais .archive/MEMORY.md. O repositório também inclui um hook que carrega a memória no início da sessão, mas mesmo sem isso a skill archive ainda funciona como um padrão disciplinado de armazenamento.

Quais são os limites deste guia sobre archive?

Este guia da archive reflete o que o repositório oferece: archives baseados em arquivos, memória indexada, categorias simples, links relacionados e recuperação via hook. Ele não promete pipelines automatizados de sumarização, busca semântica ou sincronização com knowledge bases externas.

Como melhorar a skill archive

Escreva entradas de archive para recuperação, não para storytelling

A melhor saída de archive é fácil de escanear depois. Coloque o problema, a correção e os comandos críticos onde um leitor futuro consiga localizar rápido. Uma narrativa polida vale menos do que um registro direto e pesquisável.

Use tags que as pessoas realmente vão buscar

Boas tags:

• nomes de serviços ou ferramentas
• nomes exatos de subsistemas
• nomes de plataformas de deploy
• palavras-chave de erro
• nomes dos ambientes afetados

Tags ruins:

• palavras vagas como issue, work ou update

Esta é uma das melhorias de maior impacto na qualidade de uso da archive.

Faça do MEMORY.md algo útil, não apenas protocolar

Uma entrada fraca de índice diz:

• “Fixed deployment issue”

Uma entrada forte diz:

• “ECS deploy failed due to missing IAM permission for secret access; resolved by updating task role policy”

O índice deve ajudar alguém a decidir qual archive abrir em seguida.

Registre tentativas que falharam quando elas mudarem decisões futuras

Se a equipe tentou duas correções erradas antes da certa, inclua isso quando ajudar a evitar desperdício no futuro. É aqui que a skill archive muitas vezes supera a documentação padrão: ela preserva os becos sem saída que realmente importam.

Forneça entradas melhores para obter uma saída melhor de archive

Antes de pedir para a skill arquivar algo, reúna:

• o texto exato do erro
• os comandos relevantes
• os arquivos ou configurações alterados
• o estado final validado
• por que a correção final funcionou

Esses detalhes melhoram de forma concreta a reutilização futura e a encontrabilidade.

Modos de falha comuns no uso da skill archive

Problemas típicos incluem:

• falta de atualização em .archive/MEMORY.md
• tags genéricas demais
• ausência de categoria clara
• resumo sem detalhe operacional
• entradas de archive sem relação com incidentes anteriores

A maioria dos resultados ruins com archive vem de entrada incompleta, não do template em si.

Itere depois do primeiro rascunho de archive

Depois do primeiro rascunho, verifique:

• Alguém encontraria isto com termos de busca prováveis?
• O resumo deixa claro o resultado e a causa?
• Os comandos-chave ou mudanças de configuração estão incluídos?
• Um agente futuro saberia o que tentar primeiro?
• Isso deveria se ligar a uma entrada relacionada mais antiga?

Uma segunda passada curta costuma elevar bastante a qualidade do archive.

Use a archive junto com a documentação permanente, não no lugar dela

Se a sessão revelou uma regra permanente, atualize também a documentação canônica. A skill archive deve preservar conhecimento no nível do evento; ela não deve virar o único lugar onde orientações críticas da equipe ficam registradas.

Melhore a adoção da archive com um gatilho claro de equipe

As equipes têm resultados melhores quando definem gatilhos explícitos, como:

• todo deploy em produção com surpresas
• todo incidente com correção não óbvia
• toda migração
• todo pedido do usuário para “save this for next time”

Isso mantém a archive valiosa sem enchê-la de ruído.