sdd-handoff

SDD Handoff

Na primeira resposta desta skill, comece com esta linha, uma vez só: sdd-handoff v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Quick start

Registrar o estado do trabalho e preparar a retomada, de forma que a próxima sessão — que não viu nada desta conversa — consiga continuar sem redescobrir o que já foi decidido.

1. Inferir o modo pelo contexto (continuar ou entregar) e confirmar em uma linha.
2. Resolver a família: já existe handoff desta feature? Atualizar, não criar outro.
3. Reunir o estado a partir da conversa — buscando agora os dados que faltarem.
4. Preencher a ficha e a seção da etapa (seis seções).
5. Classificar as pendências em 🐛 bug fix e ✨ feature improvement.
6. No modo entregar, percorrer o checklist de fechamento (que não bloqueia nada).
7. Gravar o arquivo — ou, sem filesystem, entregar no chat dizendo o que fazer com ele.
8. Gerar o prompt de retomada, com todo dado colado.

Consultar references/handoff-protocol.md para as regras de decisão. Para os artefatos, usar obrigatoriamente assets/HANDOFF_TEMPLATE.md e assets/SESSION_PROMPT_TEMPLATE.md como moldes. O arquivo assets/HANDOFF_EXAMPLE.md mostra o nível de detalhe esperado.

Quando usar / Quando não usar

Usar quando o usuário sinalizar que vai parar, que o contexto está no limite, que terminou uma etapa, ou pedir explicitamente para documentar/passar o bastão. Usar também ao final de um fluxo SDD, depois do Build.

Não usar para escrever documentação de produto, manual de uso ou README — o handoff é registro de trabalho em andamento, não documentação de entrega. Não usar para publicar/implantar nada: esta skill documenta o ciclo, não executa release.

Dados necessários

Entrada mínima:

• a conversa atual, com o trabalho que foi feito.

Entradas opcionais:

• arquivo de handoff anterior da mesma feature;
• artefatos do fluxo SDD (Brainstorm, Define, Design, Build Report);
• acesso ao projeto para conferir nomes de arquivo, dados e estado.

Não exigir acesso a filesystem, repositório ou sistema externo. Quando algo não estiver acessível, registrar a limitação em vez de inventar.

Assets obrigatórios de saída

assets/HANDOFF_TEMPLATE.md é o molde oficial do documento de handoff e assets/SESSION_PROMPT_TEMPLATE.md é o molde do prompt de retomada. São assets de saída, não material conceitual: sempre reutilizá-los para montar o resultado final, em vez de reconstruir a estrutura de memória.

Procedimento passo a passo

1. Inferir o modo e confirmar

Identificar pelo contexto qual dos dois modos se aplica (tabela de sinais em references/handoff-protocol.md § 1):

• continuar — o trabalho segue depois. Entrega ficha + prompt de retomada.
• entregar — a etapa terminou. Entrega o mesmo, mais o checklist de fechamento.

Confirmar em uma linha e seguir. Não abrir menu de escolha, não fazer pergunta de múltipla escolha sobre isso: quem pede um handoff normalmente está sem contexto ou sem tempo. Sem sinal claro, assumir continuar e dizer que assumiu.

2. Resolver a família da feature

Antes de criar qualquer arquivo, verificar se já existe handoff desta feature — buscando por domínio, não por nome exato. Se existir, atualizar o arquivo existente, acrescentando a etapa nova no topo. Em dúvida, perguntar mostrando o que encontrou. Detalhes em references/handoff-protocol.md § 2.

Um handoff por feature. Etapas são seções dentro dele, nunca arquivos separados.

3. Reunir o estado

Varrer a conversa e reconstruir:

• O que foi feito — o que foi construído, decidido, corrigido. Com nomes de arquivo e decisões explícitas.
• Casos e testes em aberto — o que estava sendo testado, com os dados reais: qual cliente, qual arquivo, qual data, qual identificador.
• Pendências — o que está quebrado (🐛) e o que é incremento planejado (✨).
• Próximos passos — lista ordenada, cada item com o dado exato e o critério de pronto.
• Alertas — o que não pode quebrar; o que está fora de escopo.
• Onde está o trabalho — pasta, projeto, branch.

Se faltar um dado que você consegue buscar agora, busque agora. A próxima sessão não terá como. Um handoff que diz "o cliente que estava com erro" obriga a próxima sessão a redescobrir qual era.

4. Preencher a ficha

Usar assets/HANDOFF_TEMPLATE.md. A ficha do topo é o estado agregado da feature:

• Objetivo — estável entre etapas; o que a feature entrega quando estiver pronta.
• Status — 🔨 em andamento · ✅ completa · ⏸️ pausada.
• Feito / Falta — o que já saiu e o que resta.
• Pronto quando — critério verificável de conclusão (§ 6 do protocolo). Só marcar ✅ completa quando ele estiver objetivamente satisfeito.

Etapa nova entra como seção no topo das etapas anteriores. Etapas antigas já fechadas podem ser resumidas em poucas linhas.

Mudança de escopo, pausa ou replanejamento → linha nova em ## Eventos, com data e motivo. Nunca reescrever "Falta" em silêncio.

5. Classificar as pendências

Separar sempre em duas listas: 🐛 bug fix (quebrado, parcial, comportamento errado) e ✨ feature improvement (incremento, melhoria, próxima etapa). Categoria sem itens recebe "nenhuma" — a ausência declarada também é informação.

Registrar mesmo quando não há pendência alguma. Um handoff de "etapa fechada, nada pendente" continua documentando o que foi feito. Não perguntar se vale a pena registrar: registrar é incondicional.

Risco que foi conscientemente aceito — algo que se decidiu ignorar por ora — entra como pendência com o motivo. Risco conhecido não pode evaporar entre sessões.

6. Checklist de fechamento (somente no modo entregar)

Percorrer as quatro perguntas com o usuário e registrar o que foi conferido:

1. O código roda?
2. Os critérios de aceite combinados passam?
3. As mudanças estão salvas onde deveriam?
4. O que quebrou está anotado?

Este checklist não bloqueia a entrega. Item não confirmado vira pendência e o handoff sai do mesmo jeito. Apresentar como inventário do que foi conferido — sem ✅/❌ pareados, sem contagem que se leia como nota, sem vermelho, sem a palavra "reprovado". Ver references/handoff-protocol.md § 7.

7. Entregar o documento

Onde salvar. Grave em sdd/ na raiz do projeto — pasta visível, igual em qualquer agente. Se o projeto já tiver .claude/sdd/, continue nela. Os documentos das cinco fases ficam lado a lado, sem subpastas.

Se houver filesystem de projeto gravável, salvar como sdd/HANDOFF_{FEATURE}.md (ou .claude/sdd/HANDOFF_{FEATURE}.md quando essa pasta já existir), sem sobrescrever silenciosamente um arquivo existente — quando já existir handoff da mesma feature, atualizar seu conteúdo (passo 2).

Se não houver filesystem acessível, entregar o Markdown completo no chat e fechar com estas três informações, nesta ordem:

1. que o documento não foi gravado;
2. o nome de arquivo sugerido (HANDOFF_{FEATURE}.md);
3. o que fazer com ele — salvar junto do projeto e reenviar no início da próxima sessão.

Nunca falhar em silêncio nem dar a entender que gravou.

8. Gerar o prompt de retomada

Usar assets/SESSION_PROMPT_TEMPLATE.md, entregue em bloco pronto para copiar.

Regra de ouro: nada de "como discutimos". Todo identificador, caminho, comando e dado vai colado no prompt. Se uma linha não tem valor concreto, ou você busca o valor agora, ou apaga a linha.

O prompt precisa funcionar sozinho: mesmo que o arquivo de handoff se perca, os dados nele devem bastar para continuar.

Quando a feature estiver ✅ completa e não houver continuação, o prompt de retomada pode ser omitido — basta registrar o fechamento.

Validações e checklist de qualidade

Antes de declarar o handoff concluído, verificar:

• Modo inferido e confirmado em uma linha, sem menu.
• Família resolvida: atualizou o handoff existente, ou é feature genuinamente nova.
• Ficha preenchida: Objetivo · Status · Feito · Falta · Pronto quando.
• "Pronto quando" é verificável, não uma opinião.
• As seis seções da etapa preenchidas.
• Todo caso citado tem o dado concreto junto, não só o apelido.
• Pendências separadas em 🐛 e ✨, com "nenhuma" declarado quando for o caso.
• Mudança de escopo registrada em ## Eventos.
• Próximos passos ordenados, cada um com critério de pronto.
• Modo entregar: checklist percorrido e apresentado como inventário, sem reprovação.
• Documento gravado — ou, sem filesystem, entregue no chat com as três informações.
• Prompt de retomada se sustenta sozinho.
• Nenhum {placeholder} sobrou no resultado final.
• Nenhuma frase do tipo "como discutimos" ou "continue de onde paramos".

Quando houver filesystem, o script scripts/validate_handoff.py confere mecanicamente parte disso:

python3 scripts/validate_handoff.py HANDOFF_{FEATURE}.md

Saída PASS com código 0; problemas listados com código 2.

Tratamento de exceções

• Usuário com pressa ("só me dá o prompt"): entregar o prompt primeiro, e registrar a ficha logo em seguida — sem transformar isso em negociação. Documentar é incondicional.
• Não há handoff anterior mas a feature parece antiga: perguntar antes de criar, mostrando o que procurou.
• Trabalho de várias features na mesma conversa: um handoff por feature. Perguntar qual documentar, ou documentar cada uma em seu arquivo.
• Sem filesystem: entregar no chat com as três informações do passo 7. Nunca fingir que gravou.
• Nada foi concluído na sessão: ainda assim registrar — o que foi tentado, o que não funcionou e por quê é informação valiosa para a próxima sessão.
• Feature terminou de vez: marcar ✅ completa somente com o "Pronto quando" satisfeito; o prompt de retomada pode ser omitido.
• Usuário não sabe dizer o critério de pronto: ajudar a formular a partir do que ele quer conseguir fazer no fim, em vez de deixar o campo vago.

Examples

Contexto acabando Estou no limite do contexto, documenta pra eu continuar em outra sessão.

Modo continuar. Registrar o estado, gerar o prompt com todos os dados colados.

Etapa concluída Terminei essa parte, quero fechar.

Modo entregar. Registrar o estado, percorrer o checklist de fechamento como inventário e gerar o prompt caso ainda reste trabalho.

Continuação de feature existente Vamos parar por hoje — isso aqui é continuação do controle de honorários da semana passada.

Localizar o handoff existente, acrescentar a etapa nova no topo, atualizar a ficha agregada.

Sem filesystem (no chat da web, sem projeto acessível) Passa o bastão.

Entregar o documento completo no chat, dizendo que não foi gravado, sugerindo o nome do arquivo e explicando que ele deve ser salvo e reenviado na próxima sessão.

Next Step

Fluxo SDD concluído. Guarde o arquivo de handoff junto do projeto e comece a próxima sessão com o prompt de retomada.

---

Parte do SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open