Skill de Handoff de Sessão
Propósito
Janelas de contexto grandes degradam a adesão a instruções, a precisão do raciocínio e a exatidão das ferramentas à medida que o número de tokens se acumula. Sessões longas se enchem de planos obsoletos, rascunhos abortados e rastros de erro repetitivos. Reiniciar para uma sessão nova restaura o desempenho, mas descartar o contexto cegamente introduz perda de estado, progresso alucinado e erros repetidos.
A skill session-handoff padroniza como um agente captura o estado ativo. Ela traduz a memória de trabalho efêmera em um documento de ponte acionável e verificável para a próxima sessão.
Fluxo de Trabalho: Encerrando uma Sessão (6 Passos)
Execute esta sequência quando uma sessão de agente atingir os limites operacionais ou ao interromper o trabalho:
-
Audite o Estado do Git e do Workspace Execute
git status -segit diff --statpara estabelecer a realidade fundamentada. Nunca confie na memória do chat para saber o que foi modificado. Identifique arquivos modificados, não rastreados e em staged. -
Capture a Meta vs. a Realidade Implementada Defina o objetivo original em uma frase. Documente precisamente o que foi verificado como funcional (com comandos de teste ou verificações em tempo de execução bem-sucedidos) versus o que permanece parcial ou não verificado.
-
Registre Decisões Tomadas e Caminhos Descartados Liste as decisões arquiteturais e de design tomadas durante a sessão, juntamente com a justificativa concreta. Registre explicitamente decisões negativas (abordagens testadas e descartadas) para evitar que o próximo agente tente novamente soluções que falharam.
-
Catalogue Arquivos Tocados e Símbolos Relevantes Liste os principais caminhos de arquivo, funções, classes e definições de esquema modificados ou referenciados. Inclua referências de linha quando relevante.
-
Isole Loops Abertos com Responsáveis e Verificações Liste todos os casos extremos não tratados, testes com falha, tarefas adiadas e restrições de ambiente. Cada loop aberto deve especificar quem o resolve (Humano ou Agente) e como a conclusão é verificada.
-
Especifique a Próxima Ação Imediata Elabore uma instrução única, atômica e inequívoca para o próximo agente executar no primeiro turno. Não forneça uma lista ampla; especifique o comando exato a ser executado ou o arquivo a ser editado primeiro.
Regras Operacionais
- Separe Fatos de Especulação: Um teste que passou é um fato; supor que o código funciona porque compilou é especulação. Rotule suposições não testadas explicitamente como
[NÃO VERIFICADO]. - Exija Responsáveis e Verificações para Loops Abertos: Cada loop aberto deve declarar um responsável (
HumanoouAgente) e um critério de verificação determinístico (ex.:pytest tests/auth/test_token.py:test_refresh_rotation passa). - Proíba Continuações Vagas: Nunca escreva "continue trabalhando em auth" ou "finalize componentes do frontend." Indique o símbolo, arquivo e modo de falha exatos.
- Referencie Identificadores Reais do Workspace: Todas as referências a código devem usar caminhos de arquivo e nomes de símbolos exatos. Não use descrições de pseudocódigo generalizado.
Exemplo de Uso: Nota de Handoff de Sessão
# Handoff de Sessão: Implementação de Rotação de JWT
### Meta e Estado Atual
- **Meta Alvo**: Implementar rotação e revogação de refresh token no serviço de autenticação FastAPI.
- **Estado Atual**: Migração do banco de dados de refresh token aplicada e endpoint de rotação criado. A geração de tokens e a persistência no banco de dados funcionam. O cache da lista de revogação ainda não está conectado ao validador de dependência.
- **Verificação**: `pytest tests/test_auth_tokens.py` passa (4/4 testes).
### Decisões Tomadas (Com Motivos)
- **Usamos Redis para a Lista de Revogação de Tokens**: Selecionamos Redis em vez de consultas ao Postgres para tokens JTI revogados, a fim de manter a latência abaixo de 5ms em rotas protegidas.
- **Rejeitamos Refresh Tokens Stateless**: Inicialmente avaliamos a expiração deslizante em claims JWT sem persistência, mas descartamos porque tokens comprometidos não poderiam ser revogados antes da expiração natural.
- **Formato do Token**: Escolhemos UUIDv4 para o claim `jti` para manter compatibilidade com os esquemas de armazenamento de sessão existentes.
### Arquivos Alterados
- `src/services/auth.py`: Adicionada função `rotate_refresh_token(old_token: str)` e chamada de invalidação no Redis.
- `src/models/tokens.py`: Adicionada tabela `RefreshTokenRecord` (SQLModel) para rastrear famílias de tokens.
- `alembic/versions/20261005_add_token_families.py`: Migração criando a tabela `token_records`.
- `tests/test_auth_tokens.py`: Adicionados testes unitários para geração de famílias de tokens e rotação.
### Loops Abertos
- [Agente] Conectar `verify_token_not_revoked` em `src/api/deps.py` -> Verificar verificando se `tests/test_auth_deps.py` falha em token na lista negra.
- [Agente] Tratar rollback do banco de dados se o Redis estiver inacessível durante a rotação -> Verificar simulando falha de conexão Redis em teste unitário.
- [Humano] Definir o segredo `REDIS_AUTH_URL` em `.env.test` para execução em CI.
### Próxima Ação
Abra `src/api/deps.py` e importe `is_token_blacklisted` de `src.services.auth`. Insira a verificação em `get_current_user` imediatamente após a verificação de decodificação do JWT.
### Cuidados
- Não modifique o tempo de expiração do `access_token` existente (atualmente 15 minutos) em `src/core/config.py`.
- A migração Alembic `20261005_add_token_families.py` deve ser executada antes de iniciar o servidor da API localmente (`alembic upgrade head`).
Antipadrões
- O Despejo de Transcrição do Chat: Colar logs de conversa brutos na nota de handoff. A janela de contexto da próxima sessão é imediatamente poluída com o próprio ruído de conversação do qual você pretendia escapar.
- A Aprovação Fantasma: Marcar um módulo como "concluído" quando ele foi apenas escrito, não executado ou testado.
- O Beco Sem Saída Omitido: Deixar de fora soluções que falharam. O próximo agente lerá o código, verá o mesmo caminho aparente e reimplementará a abordagem que falhou.
- O Próximo Passo Abstrato: Terminar com "Próximo: Implementar testes restantes." O novo agente gasta de 3 a 5 turnos desnecessários descobrindo o que precisa ser testado.
Limitações
- Esta skill produz apenas um handoff escrito; ela não pode preservar estado ativo, como processos em execução, saída de terminal não confirmada ou contexto de depuração na memória — registre qualquer coisa importante explicitamente na nota.
- A qualidade do handoff é limitada pelo que a sessão de saída registra: decisões, becos sem saída ou alterações de arquivo que não são escritas não podem ser recuperadas pela próxima sessão.
- Ela não substitui o controle de versão ou o rastreamento de issues; faça commit do trabalho primeiro e referencie commits ou tickets na nota em vez de duplicá-los.