Handoff
Handoff imprime um instantâneo: o resumo de forma fixa que a próxima sessão lê primeiro. Ele não arquiva nada para o instantâneo em si, pois o instantâneo é redirecionável a partir do branch padrão, PRs mesclados e notas de lançamento, e uma issue permanente que apenas repete isso é ruído. Ele abre uma issue apenas para trabalho que alguém fará: cada item do próximo ciclo se torna um, verificado contra issues abertas primeiro. Qualquer coisa adiada por decisão é registrada com sua razão onde a decisão já reside, porque essa razão é a única coisa que a próxima sessão não pode reconstruir.
O harness já retoma o histórico completo de uma sessão com --continue ou --resume e mantém a memória automática local da máquina, então o instantâneo carrega apenas o que esses não podem: próximos passos e decisões que outra máquina ou pessoa precisa encontrar no repositório ou em suas issues. Verdictos de gate e tabelas de contagem estão deliberadamente fora dele: ambos são reexecutados em segundos contra o SHA registrado, e um número reexecutado não pode ser fabricado como um número copiado.
Esta skill pode abrir e fechar issues, portanto nunca é acionada sozinha. Execute-a apenas quando solicitado, e apenas no ponto em que uma sessão está realmente terminando.
Caminho padrão
- Colete o estado da árvore: SHA, limpeza, worktrees, PRs abertos.
- Liste o que foi enviado desde a última tag de release, ou desde o início da sessão se não houver tag.
- Declare uma descoberta principal, com a evidência para ela.
- Escreva a lista do próximo ciclo: ordenada, concreta, cada item com sua justificativa.
- Para cada item do próximo ciclo, verifique issues abertas por uma que já o cubra; abra uma nova issue apenas quando nenhuma existir, e registre seu número.
- Para qualquer coisa adiada por decisão, registre a razão onde a decisão já reside (o CHANGELOG, um registro de decisão, o comentário de código no local); arquive uma issue fechada como "não planejada" apenas quando tal lugar não existir. Nunca faça isso para algo simplesmente não feito; isso permanece como item do próximo ciclo ou desaparece silenciosamente.
- Limpeza legada: se uma issue aberta intitulada "Session carryover" existir, feche-a com um comentário apontando para as issues nas quais seu conteúdo foi dividido.
- Imprima o instantâneo na resposta: o aviso de desatualização, estado da árvore, enviado, descoberta principal, lista do próximo ciclo com números das issues, e itens adiados por decisão com onde cada um está registrado.
Colete o estado da árvore
Execute estes comandos contra o branch padrão do repositório, não qualquer branch em que a sessão esteja:
git rev-parse HEAD
git status --short
git worktree list
gh pr list --state open
Registre o SHA exato, se a árvore está limpa, quantos worktrees existem e quantos PRs estão abertos. Uma afirmação vaga como "as coisas estão em bom estado" não é estado da árvore; o SHA é o fato que permite que a próxima sessão confirme que nada se moveu por baixo dele, e é contra ele que todo gate e contagem são reexecutados, razão pela qual nenhum desses resultados é arquivado em lugar algum.
Liste o que foi enviado
Da última tag de release (ou, se não houver nenhuma, do início da sessão) até o HEAD atual, liste cada PR que foi mesclado, uma linha cada: número e o que fez. Se nada foi mesclado, escreva "Nenhum" sob este cabeçalho. Não omita o cabeçalho porque a lista está vazia; uma seção ausente é lida como "ninguém verificou", não como "nada foi enviado".
Declare a descoberta principal
Uma descoberta, declarada como uma decisão com a evidência por trás dela, não um resumo de tudo que aconteceu. Se nada nesta sessão atingiu esse patamar, escreva "Nenhuma descoberta principal nesta sessão" em vez de inflar uma observação menor para preencher o espaço.
Escreva a lista do próximo ciclo e transforme cada item em uma issue
Uma lista ordenada de ações concretas seguintes, cada uma com a justificativa de uma linha que a motiva. "Comece aqui" significa que o primeiro item é genuinamente onde a próxima sessão deve começar, não apenas a primeira coisa que vem à mente.
Para cada item, pesquise issues abertas antes de abrir uma nova:
gh issue list --search "<resumo do item>" --state open
Se uma issue aberta já cobrir o item, use o número dessa issue. Caso contrário, abra uma:
gh issue create --title "<item>" --body "<a justificativa de uma linha>"
Uma issue existe para trabalho que alguém fará; um item do próximo ciclo que nunca se torna uma issue é uma lista em prosa que a próxima sessão precisa confiar em vez de um rastreador que pode ser executado.
Registre adiado por decisão onde a decisão reside
Algo que esta sessão escolheu não fazer, de propósito, não é o mesmo que algo que simplesmente não chegou a esta sessão. Apenas o primeiro tipo é registrado, com sua razão, no lugar onde a decisão já reside: a entrada do CHANGELOG que foi enviada em torno dele, um registro de decisão, ou o comentário de código no local. Aponte para esse lugar no instantâneo. Apenas quando tal lugar não existir, arquive como uma issue aberta fechada:
gh issue create --title "<item>" --body "Adiado por decisão: <a razão>"
gh issue close <N> --reason "not planned"
A razão é a única linha que a próxima sessão não consegue reconstruir por conta própria; uma coisa simplesmente não feita não precisa de registro, pois ou ainda é um item do próximo ciclo ou nunca foi um compromisso.
Legado: aposente uma issue de carryover aberta
Se uma issue intitulada "Session carryover" ainda estiver aberta desde antes desta prática mudar, feche-a em vez de deixá-la aberta para sempre:
gh issue list --search "Session carryover" --state open
gh issue close <N> --comment "Aposentada: dividida em <números das issues deste handoff>."
Pule esta etapa quando nenhuma issue desse tipo permanecer.
Imprima o instantâneo
Abra com o aviso de desatualização, textualmente em espírito: "Verifique qualquer coisa aqui antes de confiar, isto é um instantâneo e o repositório se move." Em seguida, em ordem: estado da árvore, PRs enviados, descoberta principal, lista do próximo ciclo com o número da issue de cada item, itens adiados por decisão com onde cada um está registrado. Imprima isso na resposta; nunca é arquivado.
Saídas de emergência
- Sem CLI
gh, ou ela não está autenticada. Imprima o instantâneo e os itens do próximo ciclo e adiados por decisão de qualquer forma, diga que nenhuma issue pôde ser aberta e deixe a pessoa arquivá-los manualmente. - Nada enviado, nenhuma descoberta principal, nenhum item do próximo ciclo, ou nada adiado por decisão. Diga isso claramente nessa seção, em vez de omiti-la ou preenchê-la.
Não faça
- Não execute isso por conta própria. Pode abrir e fechar issues e é acionado apenas mediante solicitação.
- Não copie um veredito de gate ou uma tabela de contagens para o instantâneo; eles são reexecutados a partir do SHA registrado, e um leitor confia na reexecução, não na cópia.
- Não abra uma issue para um item do próximo ciclo sem verificar se já existe uma que o cobre.
- Não abra uma issue para algo simplesmente não feito; isso não é o mesmo que adiado por decisão.
- Não pule o aviso de desatualização porque a sessão parece atual; o próximo leitor não tem como saber isso sem que seja declarado.
- Não infle uma descoberta principal ausente ou uma lista enviada vazia para fazer o instantâneo parecer mais substancial do que a sessão foi.
- Não deixe uma issue "Session carryover" aberta depois que este handoff for executado.