Log de sessão
Escreve um registro durável de uma sessão de trabalho. Esses logs são tratados como verdade absoluta por quem os lê em seguida — incluindo você, daqui a seis semanas, sem nenhum deste contexto. Precisão importa mais que polimento.
Quando executar isto
- Um ciclo de construção, correção, auditoria ou pesquisa acabou de terminar
- Uma sessão está terminando e há estado que a próxima precisaria
- Algo foi diagnosticado e o mecanismo vale a pena ser mantido
Não execute para trabalho trivial. Uma correção de uma linha não precisa de um log.
Onde ele vai
Onde quer que o projeto mantenha seus registros de sessão — um diretório docs/sessions/, um vault de notas, um wiki. Pergunte uma vez se não for óbvio, depois mantenha a consistência.
Um nome de arquivo com a data e uma descrição curta facilita a ordenação e a leitura: YYYY-MM-DD Descrição Curta.md.
Passos
1. Reúna os fatos antes de escrever
Não escreva baseado apenas na memória da conversa. Colete:
- Números de PR, SHAs de commits, timestamps de migração, IDs de deploy
- O que foi realmente verificado, e por qual comando
- O que falhou, e o que ainda está aberto
- Qualquer coisa que apenas um humano pode fazer
Se um fato não puder ser confirmado, marque-o como não confirmado em vez de omiti-lo ou afirmá-lo.
2. Escreva o corpo
# YYYY-MM-DD — <o que foi diagnosticado ou entregue>
<Uma linha nomeando como o trabalho foi executado: quem planejou, quem construiu, quem revisou.>
## O que aconteceu
- Mecanismo primeiro. Por que isso aconteceu, não apenas o quê.
- Evidências concretas: números de PR, SHAs, timestamps, contagens de linhas, linhas de log.
- Distinga o provado do inferido, explicitamente.
## Correção
1. Passos numerados. Cada um declara o que foi verificado e como.
## Regras de NÃO FAZER permanentes
<Apenas se a sessão produziu proibições. Baseie cada uma no incidente que a causou.>
## Itens restantes — precisa de um humano
- [ ] Coisas que apenas eles podem fazer
Links: <documentos relacionados>
Se o sistema de notas usar frontmatter, inclua um campo outcome: uma frase completa afirmando o que agora é verdadeiro que não era antes. É a linha mais lida do arquivo. Faça dela uma afirmação real, não um rótulo.
3. As duas seções que todo mundo esquece
## Itens restantes e o rodapé de links são obrigatórios. São as duas seções que carregam valor para frente e as duas mais frequentemente omitidas — em um vault, medido em 230 logs existentes, apareceram em apenas ~21% e ~28% deles.
Escreva ambas, toda vez. Se nada estiver genuinamente retido para um humano, escreva Nenhum — nada está retido. em vez de deletar o cabeçalho.
4. Marque cada afirmação
Rotule cada uma como VERIFICADA (como) ou ASSUMIDA (por que não verificada) inline. Não as misture.
"Verificada" deve significar que um humano ou um comando realmente confirmou. Uma afirmação sobre produção requer uma consulta contra a produção — não um teste bem-sucedido, não um PR mesclado, não um deploy verde.
5. Resolva cada link antes de salvar
Verifique cada destino de link contra um arquivo real antes de escrevê-lo. Um sistema de notas acumula rapidamente referências quebradas, e um log cheio de links mortos é um log em que ninguém confia.
6. Atualize o estado do projeto
Se o trabalho alterou o status de um projeto, adicione uma seção de estado datada ao documento principal desse projeto — mais novo primeiro, prefixe, nunca sobrescreva o histórico.
Se o trabalho avançou um programa com um documento de passagem, atualize-o no lugar para que a próxima sessão continue corretamente.
7. Alimente as lições de volta
Se o usuário corrigiu algo durante a sessão, escreva a lição em algum lugar durável — um arquivo de regras, um armazenamento de memória, este próprio skill. É assim que correções param de se repetir.
Estilo da casa
- Específico e falseável. Resumos vagos são piores que nada aqui.
- Nunca afirme um status sem dizer como foi verificado.
- Comece pelas más notícias. Não as enterre.
- Escreva para um leitor sem nenhum do seu contexto.
Não faça
- Não sobrescreva um log existente. Leia primeiro, depois edite.
- Não escreva em diretórios gerados por máquina.
- Não crie arquivos temporários ou saída de build junto com as notas.