O que Handoff faz?
Fecha uma sessão de trabalho escrevendo em disco um arquivo que a sessão seguinte lê para retomar exatamente de onde paramos. Deve ser usado no lugar de /compact, nunca junto com ele.
Por que não /compact
/compact lê toda a conversa para escrever um resumo e substitui o histórico por esse resumo. O prefixo muda, então o cache que já estava construído morre, e a partir daí cada turno reconstrói o cache sobre um resumo de quarenta turnos. Não compra economia, compra continuidade e cobra caro por ela.
Um arquivo de handoff faz o oposto em três frentes:
- Custa menos. O arquivo são algumas centenas de tokens para escrever e outros tantos para ler, e a sessão nova recomeça com um prefixo pequeno e limpo.
- O usuário escolhe o que sobrevive.
/compactdecide sozinho e descarta a coisa mais valiosa: os caminhos já testados que não funcionaram. Nenhum resumo automático os preserva. - Fica no disco. A terceira sessão sobre o mesmo trabalho sabe o que a primeira e a segunda fizeram. Um compact vive e morre dentro da sua sessão.
Procedimento
1. Reconstrua sozinho, não pergunte o que você pode ver. O que foi tocado, o que foi testado, o que falhou e por quê, quais decisões foram tomadas, onde paramos: estão todas na conversa. Em um repositório git, adicione git status --short e git log --oneline -5.
2. Pergunte apenas as duas lacunas que você não pode deduzir. São o objetivo (o que está sendo construído e por quê, não o que foi feito hoje) e o próximo passo desejado, que nem sempre é o próximo passo óbvio. Se faltarem, pergunte em uma única pergunta, já com sua hipótese incluída, para que baste responder "sim". Todo o resto não se pergunta: se uma seção está vazia, escreva nenhum e siga em frente, sem inventar problemas resolvidos que não existiram.
3. Decida onde escrever. Em um repositório de código: docs/handoff/{YYYY-MM-DD}-{slug}.md. Em um vault ou pasta de notas (como este mesmo projeto, il-tuo-os): uma pasta handoffs/ dentro do projeto ao qual o trabalho pertence. O {slug} são duas ou três palavras sobre o trabalho, não sobre a data. Se já existir um handoff com o mesmo slug, não o sobrescreva: o novo arquivo incrementa um campo seq e coloca o anterior em prev, assim a cadeia pode ser lida para trás.
4. Escreva o arquivo com este frontmatter — type: handoff, date, status, seq, prev, tags — e estas seções, nesta ordem:
- Objetivo: o que está sendo construído e por quê, duas ou três linhas, incluindo a razão.
- Onde estamos: o estado real agora. O que funciona, o que está pela metade, o que não foi iniciado.
- O que tentamos que NÃO funcionou: a seção mais importante do arquivo. Cada caminho descartado com o motivo. Serve para impedir que a sessão seguinte tente novamente do zero.
- Problemas encontrados e como os resolvemos: apenas aqueles que se repetiriam. Sintoma, causa, correção.
- Decisões tomadas: o que foi escolhido e o que foi descartado, com uma linha do porquê. Uma decisão sem a alternativa descartada será rediscutida do zero na semana seguinte.
- Arquivos tocados: caminhos, com uma linha sobre o que mudou em cada um.
- Onde queremos chegar: o próximo passo, escrito no imperativo. Depois o seguinte, se já estiver claro.
- Coisas a saber antes de tocar em algo: armadilhas, comandos que devem ser executados de uma certa maneira, coisas que parecem quebradas e não estão. Se não houver,
nenhuma.
5. Finalize imprimindo no chat a linha de retomada, pronta para ser colada em uma nova sessão: Leia {caminho} e retome de "Onde queremos chegar". Mais uma linha para dizer que neste ponto pode-se usar /clear e que a retomada custará apenas aquele arquivo.
Quando NÃO usar
Uma skill que se usa sempre é uma skill que se usa ao acaso.
- Mudança de tarefa sem continuidade →
/clear, não precisa de handoff. - Seguiu um caminho errado nos últimos turnos →
/rewind, que volta a um ponto que o cache já conhece. - Vai retomar em breve e sem atualizações no meio →
/renamemais/resume. - O trabalho continua por outro dia ou outra semana → esta skill.
Esta skill não executa /clear no lugar do usuário: apenas sugere que ele o faça.