session-handoff — criar e retomar handoffs de sessão

Dois modos. Sem argumento → CRIAR. resume (ou load <arquivo>) → RETOMAR. O diferencial: antes de gravar, o usuário cura e prioriza o que entra no handoff.

Scripts determinísticos em scripts/ (PowerShell, saída JSON) fazem o trabalho repetitivo (scrape git, achar handoffs, staleness, validar). O modelo faz o julgamento: sumarizar a sessão, conduzir a curadoria com o humano, e verificar o workspace.

Modo CRIAR (default)

1. Coletar estado (determinístico)

pwsh -NoProfile -File "scripts/new-handoff.ps1" -ProjectRoot "<raiz>" -Slug "<tema curto>"

Devolve JSON: branch/head, status (working tree), recentCommits, targetDir, convention, useStatusHeader, suggestedPath, existingHandoffs. Use esses valores — não invente git state.

2. Sumarizar a sessão e levantar tópicos candidatos

A partir do contexto desta conversa, monte a lista de candidatos a entrar no handoff: decisões (com razão), pendências/próximos passos, arquivos tocados, gotchas, padrões descobertos, blockers. Seja específico (file:line, comando exato). Chame falhas pelo nome.

3. ⭐ Curadoria priorizada com o usuário (o coração da skill)

Sempre faça 1 rodada. Apresente os tópicos candidatos e use AskUserQuestion (multiSelect) para o usuário escolher o que conservar e a prioridade. Pergunte também se vale ligar seções opcionais (arquivos-chave / gotchas / padrões). Não grave nada antes disso.

4. Escrever o .md padronizado

Grave em suggestedPath seguindo references/handoff-template.md:

• Base enxuta: Status · Resumo · Decisões · Pendências · Como retomar. Seções opcionais só se a curadoria pediu.
• Header **Status:** ativo … apenas se useStatusHeader: true (convenção docs/handoffs/); no fallback .claude/handoffs/, mantenha branch/HEAD/criado sem o Status:.
• Linha de authority + unknowns explícitos ("not recorded this session" — nunca afirme que testou se não testou). Zero secrets. Crie targetDir se não existir.

5. Validar (determinístico)

pwsh -NoProfile -File "scripts/validate-handoff.ps1" -File "<caminho>"

Corrija o que vier: todos (placeholders), secretsSuspected, missingHeadings, withinBudget. Não finalize com secret suspeito ou TODO sobrando.

6. Fechar

• Se a pasta tem README.md de índice (convenção do projeto), ofereça adicionar a linha-ponteiro + **Status:** ativo.
• Reporte: caminho do arquivo, score da validação, e o próximo passo #1 que a próxima sessão fará.

Modo RETOMAR (/session-handoff resume · ... load <arquivo>)

1. Achar o handoff (determinístico)

pwsh -NoProfile -File "scripts/resume-handoff.ps1" -ProjectRoot "<raiz>" -Latest
# ou um específico:  -File "<caminho do .md>"

JSON: handoffs[] (título, status, recordedBranch/Head, created, staleness, commitsSince), gitNow, selected. Vários handoffs ativo? confirme qual com o usuário.

2. Ler e verificar (julgamento)

Leia o .md selecionado inteiro (Read). Siga references/resume-checklist.md: confira staleness, rode git status, compare com o Status gravado, e verifique o workspace de verdade — o log da conversa ≠ o estado do código. Se STALE/VERY_STALE, reconcilie antes.

3. Retomar

Reconstrua o contexto em 1-2 frases (de onde retoma + staleness), depois comece pelo item #1 de "Como retomar"/"Próximos passos". Sessão longa? ao final, crie um novo handoff (encadeia o anterior).

Guardrails

• Nunca grave secrets (a validação é heurística — você é o gate final). Liste nomes de env var, não valores.
• Aponta-não-duplica: handoff = estado transitório. Fato durável vai pra ADR/memória, não aqui.
• Não invente git state nem afirme testes que não rodou. Unknowns são explícitos.
• A curadoria com o usuário (passo 3 do CRIAR) não é opcional — é o que distingue esta skill.

Para usar num projeto: /install-skill session-handoff lá dentro.