handover

Você vai destilar uma tarefa inacabada em artefatos duráveis, para que uma sessão NOVA retome sem reexplicação.

LEIA ISTO PRIMEIRO. Esta skill já foi 182 linhas de prosa. O resultado eram handovers de 5 minutos, com desvios inventados no meio do caminho e os mesmos bugs voltando — porque prosa é advisory: cada sessão reinterpreta e improvisa. Vinte rodadas de correção adicionaram mais prosa e pioraram tudo. O mecânico agora é código (handover.py), que EXECUTA a regra em vez de interpretá-la. Sua parte é pequena e é só julgamento. Não reimplemente à mão o que o script faz; não invente etapas que não estão aqui.

As 3 camadas (por que existe handover, e não só memória)

Detalhe mora só no handover. Nunca duplique.

Onde o handover mora — e por que não é dentro do projeto. Sempre em ~/.claude/projects/<slug>/handovers/, ao lado de memory/, derivado do slug e nunca do CWD. O handover.py trava isso; você não escolhe o caminho. Antes era <raiz>/documentacao, o que fazia o local depender de onde a sessão abriu (um projeto com handovers em backend/documentacao ficou com dois lugares e nenhum certo) e punha texto com nome de cliente dentro do repo. Pastas legadas são lidas — o collect avisa que existem e que estão fora do corpus indexado — e nunca escritas; python handover.py migrate as esvazia.

O fluxo — 5 passos, nesta ordem

0. Pergunte o escopo, antes de tocar em qualquer arquivo

AskUserQuestion, uma pergunta, três opções mutuamente exclusivas:

• A — Handover simples: só grava handover + memória.
• B — Handover + commit: grava e roda git commit das mudanças pendentes.
• C — Handover + commit + push: B, e depois git push do remote/branch atual.

A resposta decide o que o Passo 5 faz. Não assuma — cada saída pode ter escopo diferente.

1. TodoWrite com estas 4 etapas, antes de qualquer outra coisa

Progresso invisível é o defeito nº 1 desta skill. Marque in_progress/completed um por vez, em tempo real — nunca um lote no fim.

2. python <pasta-desta-skill>/handover.py collect

O handover.py fica na mesma pasta deste SKILL.md — normalmente ~/.claude/skills/handover/handover.py (instalação global) ou <projeto>/.claude/skills/handover/handover.py (project-local). Rode de dentro do projeto: ele descobre a raiz, o slug da memória, o repo git e o o1mem_rag.py a partir do seu CWD.

Devolve num bloco só: git (branch/HEAD/tree/remotes em sincronia), caminhos já validados, handovers existentes, o snapshot da sessão, a RETOMADA atual e a contagem de (Anterior ...). Não colete nada disso à mão.

O snapshot é a sua fonte bruta — leia antes de redigir. O hook grava, sem pedir nada a ninguém, o que a sessão realmente fez: as perguntas do usuário na ordem, os arquivos tocados e os comandos rodados (~/.claude/projects/<slug>/snapshots/). Ele não é um handover e não tenta ser: não tem o porquê, não tem o próximo passo, não entra na memória e não é indexado. Ele existe porque a captura é barata e o julgamento é caro — e porque, quando alguém dá /clear sem passar por aqui, o snapshot é a única coisa que sobra. Se o collect mostrar um, leia-o em vez de reconstruir o fio de memória: reconstruir é exatamente o custo que este produto existe para não pagar.

TRAVA DE VALOR — decida com o que o collect mostrou. Handover só vale se houver pelo menos UM de: (a) estado pendente que importa, (b) raciocínio caro de reconstruir, (c) plano de vários passos não executado. Tarefa concluída e verificada → NÃO escreva handover. Grave só a memória e diga que basta. Não "encontre" trabalho para justificar o arquivo.

3. Escreva os dois arquivos de julgamento (esta é a SUA parte)

body.md — só o que git+código+memória não contam sozinhos:

## Onde paramos
1 parágrafo: o estado atual, na língua de quem vai retomar.

## Próximo passo EXATO
A PRIMEIRA ação concreta. Sem ambiguidade.

## Decisões + porquê
A RAZÃO, não o quê. Inclua a alternativa descartada e por quê.

## Estado pendente
O que falta, com o critério de "pronto".

## Riscos / colaterais em backlog
Problemas conhecidos NÃO resolvidos, com severidade.

## Caveat de estado vivo (REVERIFICAR antes de afirmar)
SÓ no modo verificada. Itens concretos e checáveis que a retomada vai EXECUTAR:
backend de pé? qual PID/porta? o processo rodando TEM o patch (mtime vs. start)?
env flags? `git diff --stat` bate? store/cache no estado assumido?

## Refs — arquivo:linha
Pontos de entrada para achar rápido. NÃO é o diff.

❌ Não liste "arquivos tocados" (o git diff já mostra) · ❌ não cole código (aponte arquivo:linha) · ✅ o porquê, o que falta, o próximo passo, os riscos.

⚠️ Anti-segredo, sem exceção: o handover vai pro disco e normalmente pro git. Nunca grave credencial, .env, chave, token, URL assinada ou dado pessoal. Se o caveat depende de segredo, referencie só o nome da variável (AWS_SECRET_ACCESS_KEY está setada?) ou o local (ver secrets manager) — nunca o valor.

breadcrumb.txt — o texto novo da linha RETOMADA: estado + próximo passo + [[link]]. TERSO: aponta, não repete. O modo não vai aqui (está na 1ª linha do handover).

4. python <pasta-desta-skill>/handover.py write --task <slug> --mode rapida|verificada --body body.md --breadcrumb breadcrumb.txt

O script grava o handover, promove a RETOMADA anterior aplicando cap=2 + decay=30d, preserva os [[links]] e o fim de linha do arquivo, indexa o RAG checando o exit code de verdade, e imprime o que fez. Ele também recusa modo incoerente: verificada exige a seção de caveat, rapida a proíbe. Se ele recusar, o modo está errado — não contorne.

Depois: crie/atualize 1 project_*.md em memory/ com o fato durável apontando pro handover, e ajuste a linha-índice do MEMORY.md.

Invariante do MEMORY.md: densifique a prosa, mas nunca drope um [[link]] — cada um é load-bearing pro protocolo de save achar o arquivo que cobre um fato. Para economizar, encurte o TEXTO do link ([↗](x.md)), não o remova.

Passo 5 — Execute o escopo do Passo 0, depois libere o /clear

Se a resposta do Passo 0 foi B ou C: rode git add do que mudou (handover, memória, e o trabalho da sessão) e git commit com mensagem que descreve a sessão — confira antes que a mensagem não cite dado sensível (ver [[feedback_nao_citar_cliente_em_mensagem_de_commit_publico]]). Se foi C: depois do commit, git push do remote/branch em uso. Se A: nenhum dos dois.

Diga que é seguro dar /clear, o que foi gravado (e commitado/pushado, se aplicável), e em uma frase qual será a primeira ação da retomada. Termine com:

PRONTO E OPERANTE THIAGO!

Para limpar a sessão: você digita /clear. Zera o contexto desta conversa — o handover e a memória já estão em disco, nada se perde. Para retomar depois: sessão NOVA, peça "retomar o handover". Ela lê a linha RETOMADA, abre o handover indicado e segue o modo gravado.

🔴 Este bloco é EXCLUSIVO da saída. Emiti-lo ao retomar cria o loop que já queimou 5 sessões: /clear → retomar → a retomada reapresenta o handover e manda dar /clear de novo, sem uma linha de trabalho ter andado. Se você sentir vontade de assinar ao retomar, é sinal de que não fez nada.

Na RETOMADA (sessão nova) — o modo está no arquivo

TodoWrite primeiro, aqui também. Leia a linha RETOMADA, abra o handover, leia a linha retomada:.

• Decay: se a data da RETOMADA tem mais de 30 dias, o breadcrumb pode estar dormente — reconfira antes de tratar como atual.
• PROMOÇÃO (sempre permitida; rebaixamento nunca): se o próximo passo toca runtime — como escrito OU como evoluiu — trate como verificada mesmo que o arquivo diga rapida.
• verificada: execute o caveat item por item (paralelize com subagentes Haiku: Agent, model: "haiku", subagent_type: "general-purpose", todos no MESMO bloco). Reporte ✅/⚠️/❌ pelo que encontrou, não pelo que o handover afirmava; divergência vem ANTES de propor agir, e se ela afeta integridade, corrija primeiro. A reconciliação é sua, nunca do subagente.

REGRA DE OURO: EXECUTE, não reapresente. O produto de uma retomada é trabalho feito. Faça tudo do próximo passo que não exige o olho ou a mão do usuário (commit, push, rodar a suíte, aplicar o fix já acordado). Só o que é fisicamente dele volta como pedido — um, no fim. Perguntar "posso?" sobre algo que o handover já registrou como decidido é o que trava o ciclo. Nunca feche uma retomada com o bloco de fechamento nem com convite a /clear.

O que esta skill NÃO é

Não é dump de conversa (é destilação) · não executa /clear · não substitui a memória (é índice + arquivo) · não roda para tarefa concluída · não afirma runtime pela memória · não reimplementa à mão o que handover.py faz.