Clube-do-Valor/cdv-handoff

Handoff

Eine frische Sitzung macht besseres QA und bessere Reviews als die Sitzung, die implementiert hat – weniger Kontext, keine Bindung an den Code. Das ist eine bewusste Praxis, und sie steht und fällt mit dem Handoff. Diese Skill macht jeden einzelnen davon so gut.

Arbeitsprinzipien

• Fakten werden verifiziert, nicht erinnert. Jede Anzahl, jeder Pfad und jede ID im Block stammt aus einem jetzt ausgeführten Befehl: git rev-list --count origin/<branch>..HEAD, git worktree list, ls QA-<slug>.md, die Fixture-IDs aus der QA-Datei. Ein Handoff, der „3 Commits möglicherweise nicht gepusht“ sagt, wenn es 5 sind, führt die nächste Sitzung in die Irre.
• Der Leser hat nichts als den Block. Kein „como vimos“, kein Verweis auf diesen Chat. Benennen Sie die aufzurufende Skill, die zu lesende Datei, den auszuführenden Befehl.
• Standardmäßig im Chat. Der Block wird im Chat in einem Code-Block dargestellt (zum Kopieren und Einfügen). Eine HANDOFF-<slug>.md-Datei (eine flüchtige Root-Datei, profile.ephemeral_patterns: ignoriert, niemals committed) wird nur erstellt, wenn der Benutzer nach einer Datei fragt oder der Block etwa 60 Zeilen überschreitet.
• Produktionsrelevante Schritte werden mit Grund genannt. Nicht „Vorsicht bei Schritt 8“, sondern was wo geschrieben wird und warum es nicht rückgängig gemacht werden kann.
• PII-Disziplin wie überall: IDs und Vornamen; E-Mails sind Arbeitskennungen und dürfen erscheinen; niemals Personalausweisnummern, Telefonnummern oder Adressen.

Wann verwenden

• Der Abschluss von cdv-finalize (gibt den QA-Handoff selbst aus, unter Verwendung dieser Vorlage).
• Der Benutzer fordert eine Aufforderung an, um eine Untersuchung fortzusetzen, ein Review durchzuführen oder QA in einer anderen Sitzung auszuführen.
• Eine Sitzung steht kurz vor dem Abbruch, weil ihr Kontext zu groß geworden ist (Compaction droht, „es wird zu lang“).

Arbeitsablauf

Schritt 0 – Profil und Erweiterung laden

1. Lesen Sie .claude/harness/profile.yaml und, falls vorhanden, .claude/harness/profile.local.yaml (seine Schlüssel gewinnen). Wenn profile.yaml fehlt, brechen Sie ab und sagen Sie es: Diese Skill benötigt das cdv-harness-Profil des Repositorys und errät niemals die Werte.
2. Lesen Sie <profile.extension_dir>/cdv-handoff.md, falls vorhanden. Die Erweiterung fügt nur hinzu oder schränkt ein; wo sie und diese Skill abweichen, gewinnt die Erweiterung für dieses Repository. Im Folgenden ist profile.<key> ein Wert aus dem Profil. Ein fehlender Schlüssel oder none bedeutet, dass das Repository dieses Merkmal nicht hat: Überspringen Sie den Schritt, der es benötigt.

Schritt 1 – Art bestimmen und Fakten sammeln (alle schreibgeschützt)

Art ∈ qa | review | investigation | continue-implementation. Führen Sie dann aus und behalten Sie die Rohausgabe:

git branch --show-current
git worktree list --porcelain
git rev-list --count origin/<branch>..HEAD 2>/dev/null   # nicht gepushte Commits ('?' wenn kein Remote)
git rev-list --count HEAD..origin/<profile.default_branch> # hinter dem Standard-Branch
git status --porcelain | grep -v '^??'                   # nicht committete, getrackte Dateien
ls QA-<slug>.md STATE-<slug>.md <slug>-pr.md decisions-<slug>.md 2>/dev/null
grep -n 'PRODUCTION-AFFECTING' QA-<slug>.md 2>/dev/null

Bei qa: Die Fixtures stammen aus den eigenen Schritten der QA-Datei (IDs + Anzeigelabels, wie cdv-interactive-qa sie benötigt). Bei review: Die Ticket-ID über cdv-code-review/scripts/resolve-ticket-id.sh und ob ein <profile.pr_review_dir_prefix><TICKET>/ bereits existiert. Bei investigation: Der Hypothesenblock und die Beweistabelle aus dem cdv-debug-Bericht, wortwörtlich. Bei continue-implementation: Die Phasenstatus von STATE-<slug>.md, der Abschnitt ## Finalize seed und ob ## Verificação existiert.

Schritt 2 – Block rendern

Code-Block in profile.language_ui (die unten stehenden Abschnittsüberschriften auf PT-BR bleiben wie geschrieben), in dieser Reihenfolge; lassen Sie einen Abschnitt nur weg, wenn er wirklich leer ist, und sagen Sie es (Sem fixtures pré-consultadas.):

<VERBO> da branch <branch> (<uma frase do que ela entrega>).

ONDE ESTÁ O CÓDIGO
- <worktree path | checkout principal `profile.main_checkout`>
- <N> commits à frente de origin/<profile.default_branch>; <M> commits NÃO pushados (confira: git rev-list --count origin/<branch>..HEAD)
- <uncommitted tracked files, or "árvore limpa">

ARMADILHA DO AMBIENTE  (nur wenn der Code in einem Worktree liegt und `profile.worktree_runner` nicht `none` ist)
- O worktree não tem o ambiente do checkout principal (dependências, `.env`); `profile.cmd_container_exec` testa o checkout principal, não este.
- Todo gate por: <profile.worktree_runner> <worktree> <comando de teste> <filtro>
- Para QA na tela: trazer a branch com <profile.bring_branch_script> --check <branch> e depois sem --check. Se recusar, PARE e pergunte — é WIP de outra sessão. Nunca git stash.
- Baseline atual: <N passed (M assertions)>, formatador <PASS>, análise estática <OK>.

O QUE FAZER
- Invoque a skill <cdv-interactive-qa | cdv-code-review | cdv-debug | cdv-plan-feature>.
- <roteiro/arquivo a ler, with path> | <ticket id> | <report to start from>

FIXTURES REAIS (validadas em <data>)
- <entidade> <id> (<label como a tela mostra>) — <estado que interessa>
- ...

PASSOS QUE ESCREVEM FORA DO LOCAL  [PRODUCTION-AFFECTING]
- Passo <n>: escreve <o quê> em <sistema externo, de `profile.production_writing_integrations`>; irreversível porque <motivo>. Só o usuário roda, depois de confirmar <o quê>.
- (or) Nenhum — tudo é leitura ou escrita só no banco local.

CONTEXTO QUE MUDA A EXPECTATIVA
- <the one or two facts that would otherwise look like bugs: "o comando de exportação sai com exit 0 por decisão", "o export roda só de madrugada — testar com o comando manual é o esperado">

NÃO FAÇA
- Não troque a branch do checkout principal por cima de WIP alheio; não use git stash.
- <anything the user excluded: "não investigar os dois registros duplicados">

<VERBO> ist Rode o QA interativo, Faça o code review, Continue a investigação oder Continue a implementação.

Schritt 3 – Selbstprüfung vor der Ausgabe

• Jede Zahl stammt aus einem Befehl in Schritt 1 (erneut ausführen, wenn sich der Baum geändert hat).
• Jeder Pfad existiert (ls).
• Kein Satz benötigt diesen Chat, um verstanden zu werden.
• Der Abschnitt PRODUCTION-AFFECTING ist vorhanden (mit Inhalt oder mit „Nenhum“).

Zusammensetzung

• cdv-finalize – gibt die Art qa bei seinem Abschluss mithilfe dieser Vorlage aus; wenn diese Skill nach einem Finalize eigenständig aufgerufen wird, die Zahlen des Statusberichts wiederverwenden, anstatt sie neu abzuleiten.
• cdv-interactive-qa, cdv-code-review, cdv-debug, cdv-plan-feature – die Empfänger. Der Block benennt, welche aufzurufen ist.
• cdv-code-review Third-Party-Modus – ein Review-Handoff für einen PR eines Kollegen sagt dies explizit (branch de terceiro: sem apply-review).

Beispiel (Art qa, komprimiert)

Rode o QA interativo da branch fix/export-stale-file (o export escrevia o arquivo de ontem
depois de uma nova execução manual; agora grava o arquivo do dia e remove o anterior).

ONDE ESTÁ O CÓDIGO
- worktree .claude-worktrees/export-stale-file
- 5 commits à frente de origin/<branch padrão>; 2 NÃO pushados (git rev-list --count origin/fix/export-stale-file..HEAD)
- árvore limpa

ARMADILHA DO AMBIENTE
- Worktree sem o ambiente do checkout principal: gates pelo executor de worktree; para a tela, o script de trazer a branch com --check primeiro.
- Baseline: suíte de testes verde, formatador PASS, análise estática OK.

O QUE FAZER
- Invoque cdv-interactive-qa; roteiro em QA-export-stale-file.md (6 passos).

FIXTURES REAIS (validadas na data do handoff)
- relatório 7 (Vendas — semana) — exportado ontem, o arquivo antigo ainda existe (o caso a reparar)
- relatório 8 (Estoque — semana) — nunca exportado (o caso limpo)

PASSOS QUE ESCREVEM FORA DO LOCAL
- Passo 4: o one-off LÊ a API externa real (uma chamada por item) para conferir os totais; nunca escreve nela. Se algo sugerir escrita, pare.
- Nenhum outro — o export grava só no disco local.

CONTEXTO QUE MUDA A EXPECTATIVA
- O export roda só de madrugada — testar com o comando manual é o esperado.

NÃO FAÇA
- Não troque a branch do checkout principal por cima de WIP alheio; não use git stash.