handoff · diff
git:20261015.0b213d9 to git:20261015.227cf3d
34 added, 26 removed. Audit A to A.
---
name: handoff
- description: Nota de fim de sessão para a próxima sessão retomar o trabalho, com os fatos do git coletados pela ferramenta (branch, commits a frente da base, arquivos modificados, stashes) e as citações conferidas antes de gravar - o que não existe fica marcado "[nao verificado]". Use quando o usuário pedir para encerrar a sessão deixando um handoff, escrever uma nota de passagem, ou retomar uma - "faz o handoff", "deixa uma nota pra próxima sessão", "retome o handoff". Also use when the user says "handoff", "write a handoff note", "resume the handoff" or "end of session notes". Gatilhos - /handoff ou /housekeeping:handoff.
+ description: Writes an end-of-session note so the next session can resume the work, with the git facts collected by the tool (branch, commits ahead of the base, modified files, stashes) and the citations checked before saving - whatever does not exist is marked "[nao verificado]" ("not verified"). Use when the user asks to end the session leaving a handoff, to write a handover note, or to resume one, for example "faz o handoff", "deixa uma nota pra próxima sessão", "retome o handoff", "handoff", "write a handoff note", "resume the handoff", "end of session notes". Triggers - /handoff or /housekeeping:handoff.
---
- # handoff (nota de fim de sessão com fatos conferidos)
+ # handoff (end-of-session note with checked facts)
- Escreve uma nota para uma sessão nova, sem a sua memória, continuar o trabalho. Dois cuidados a distinguem de uma nota escrita de cabeça: os **fatos do git** (branch, ponta, commits a frente da base, arquivos modificados, stashes, worktrees) vêm do git, não de você; e toda **citação** que você escreve (commit, branch, arquivo) é conferida antes de a nota ser gravada, e a que não existe fica marcada `[nao verificado]`, sem apagar nada. Requer `python3` (stdlib) e `git`; não usa a rede.
+ Writes a note that lets a new session, without your memory, continue the work. Two things set it apart from a note written from memory. First, the **git facts** (branch, tip, commits ahead of the base, modified files, stashes, worktrees) come from git, not from you. Second, every **citation** you write (commit, branch, file) is checked before the note is saved, and a citation that does not exist is marked `[nao verificado]` ("not verified"), without deleting anything. It needs `python3` (stdlib) and `git`; it does not use the network.
- ## Quando usar
+ Reply to the user in the user's language. Write the content of the note in the user's language too. The headings, the citation prefixes and the `[nao verificado]` mark are fixed Portuguese text that the tool matches: keep them exactly as given below.
- Quando o usuário pedir uma nota de passagem ou para retomar uma. Não se ofereça sozinho. Retomar só acontece sob pedido: nenhum hook, nenhuma oferta automática.
+ ## When to use
- ## Fluxo
+ Use it when the user asks for a handover note or to resume one. Never offer it on your own. Resuming happens only on request: no hook, no automatic offer.
- ### 0. Localizar o script
+ ## Flow
- O script acompanha esta skill: `${CLAUDE_SKILL_DIR}/scripts/handoff.py`. Use-o direto, sempre com `python3 -I`.
+ ### 0. Locate the script
+ The script ships with this skill: `${CLAUDE_SKILL_DIR}/scripts/handoff.py`. Use it directly, always with `python3 -I`.
+
```bash
test -f "${CLAUDE_SKILL_DIR}/scripts/handoff.py" && echo OK || echo FALTA
```
- Se `${CLAUDE_SKILL_DIR}` aparecer sem ser substituído, use no lugar dele o caminho mostrado como "Base directory for this skill" quando a skill foi carregada, escrito por extenso em cada comando.
+ `OK` means the script exists. `FALTA` means "missing".
- ### 1. Escrever o rascunho
+ If `${CLAUDE_SKILL_DIR}` shows up unexpanded, use the path shown as "Base directory for this skill" when the skill was loaded, written out in full in every command.
- Escreva o rascunho com **estes quatro títulos**, nesta ordem, sem acentos (a ferramenta avisa se faltar algum, e nunca inventa o conteúdo):
+ In the commands below, `<repositório>` is the repository path ("repository").
+ ### 1. Write the draft
+
+ Write the draft with **these four headings**, in this order, without accents (the tool warns if one is missing, and never invents the content):
+
```markdown
## O que foi feito
## Decisoes e por que
## Proximos passos
## O que falhou ou travou
```
- O estado do git não entra no rascunho: a ferramenta o acrescenta no topo da nota. Em cada seção seja concreto: o que mudou, o que foi decidido e descartado (com o motivo, para ninguém refazer a discussão), a primeira coisa a fazer ao retomar, e as tentativas que não deram certo.
+ The meaning of the headings is "What was done", "Decisions and why", "Next steps" and "What failed or got stuck". Keep the Portuguese heading text exactly as shown. Write the content under each heading in the user's language.
- **Cite com tipo.** Só estas formas, entre crases, são conferidas; uma crase sem tipo é texto:
+ Do not put the git state in the draft: the tool adds it at the top of the note (a section titled `## Estado do git`, "Git state"). In each section be concrete: what changed, what was decided and what was discarded (with the reason, so nobody repeats the discussion), the first thing to do when resuming, and the attempts that did not work.
- - `` `commit:abc1234` ``: um commit (7 a 40 caracteres hexadecimais);
- - `` `branch:nome` ``: uma branch local ou remota (`origin/main`);
- - `` `file:caminho/do/arquivo.py:42` ``: um arquivo relativo à raiz do repositório, com a linha opcional.
+ **Cite with a type.** Only these forms, between backticks, are checked; a backtick span with no type is plain text:
- Cite só o que você viu existir nesta sessão. Se a nota não tiver nenhuma citação tipada, nada é conferido: diga isso ao usuário.
+ - `` `commit:abc1234` ``: a commit (7 to 40 hexadecimal characters);
+ - `` `branch:nome` ``: a local or remote branch (`origin/main`); `nome` is the branch name ("name");
+ - `` `file:caminho/do/arquivo.py:42` ``: a file relative to the repository root, with an optional line number; `caminho/do/arquivo.py` is "path/to/file.py".
- ### 2. Gravar
+ Cite only what you saw exist in this session. If the note has no typed citation, nothing is checked: tell the user so.
+ ### 2. Save
+
```bash
python3 -I "${CLAUDE_SKILL_DIR}/scripts/handoff.py" write <repositório> --draft - <<'EOF'
## O que foi feito
...
EOF
```
- A nota vai para `.handoff/AAAA-MM-DD-hhmmss.md` (privada, uma por execução, nunca sobrescreve outra). Código de saída: `0` tudo conferido, `1` alguma citação não verificada (a nota foi gravada com a marca), `2` erro. Leia o relatório: se houver citações não verificadas, diga quais e **proponha corrigir** (um novo `write` cria outra nota); se houver "aviso: falta a secao", diga qual.
+ The note goes to `.handoff/AAAA-MM-DD-hhmmss.md` (`AAAA-MM-DD` is YYYY-MM-DD; the file is private, one per run, and never overwrites another). Exit codes: `0` everything checked, `1` some citation not verified (the note was saved with the mark), `2` error. The tool prints `nota gravada em <path>` ("note saved to <path>"), then `<N> citacoes, <M> nao verificadas` ("N citations, M not verified"). Read that output. If there are unverified citations, say which ones and **propose a fix** (a new `write` creates another note). If it prints `aviso: falta a secao '<name>'` ("warning: section '<name>' is missing"), say which section.
- `collect` mostra só os fatos do git; `verify <arquivo>` confere as citações de qualquer nota ou rascunho sem alterar o arquivo.
+ `collect` shows only the git facts. `verify <arquivo>` checks the citations of any note or draft without changing the file (`<arquivo>` is "file").
- ### 3. Retomar (só sob pedido)
+ ### 3. Resume (only on request)
```bash
python3 -I "${CLAUDE_SKILL_DIR}/scripts/handoff.py" resume <repositório>
```
- Mostra a nota mais recente (`--file` escolhe outra), confere de novo cada citação e lista o que mudou desde que ela foi escrita: a ponta de uma branch que andou, a contagem a frente/atrás da base, arquivos modificados que sumiram ou apareceram, stashes. Saída `0` sem nada novo, `1` com mudança ou citação com problema. **Apresente as diferenças antes de agir** e não retome o plano da nota às cegas: o repositório pode ter andado.
+ It shows the most recent note (`--file` picks another one), checks every citation again, and lists what changed since the note was written: the tip of a branch that moved, the ahead/behind count against the base, modified files that disappeared or appeared, stashes. Exit code `0` with nothing new, `1` with a change or a citation with a problem. **Present the differences before acting**, and do not resume the note's plan blindly: the repository may have moved.
- ## Regras
+ ## Rules
- - `.handoff/` não deve ir para o git: as notas podem citar caminhos internos ou texto colado. A ferramenta não edita `.gitignore`; sugira a linha `.handoff/` e só a acrescente com o OK do usuário. Não publique nem commite uma nota.
- - Não escreva na nota algo que você não verificou como se fosse fato: o que não for certo, diga que é suposição.
- - Somente leitura no repositório: a ferramenta só escreve a nota, e recusa uma pasta `.handoff` que seja link simbólico. Não rode em um repositório em que você não confia: o git lê a configuração local dele. Se `git` não existir no PATH, diga isso ao usuário.
+ - `.handoff/` must not go into git: notes may cite internal paths or pasted text. The tool does not edit `.gitignore`. Suggest the line `.handoff/` and add it only with the user's OK. Never publish or commit a note.
+ - Never write something you did not verify as if it were a fact. If you are not sure, say in the note that it is an assumption.
+ - Read-only on the repository: the tool only writes the note, and it refuses a `.handoff` folder that is a symbolic link. Never run it on a repository you do not trust: git reads that repository's local configuration. If `git` is not on the PATH, tell the user so.