Clube-do-Valor/cdv-handoff

Handoff (Traspaso)

Una sesión fresca hace mejor QA y mejor revisión que la sesión que implementó: menos contexto, sin apego al código. Esa es una práctica deliberada, y depende del handoff. Este skill hace que cada uno sea tan bueno como debería.

Principios de operación

• Los hechos se verifican, no se recuerdan. Cada conteo, ruta e id en el bloque proviene de un comando ejecutado ahora: git rev-list --count origin/<branch>..HEAD, git worktree list, ls QA-<slug>.md, los ids de fixtures extraídos del archivo QA. Un handoff que diga "3 commits pueden no estar pushados" cuando el conteo es 5 lleva a la siguiente sesión por el camino equivocado.
• El lector solo tiene el bloque. Sin "como vimos", sin referencia a este chat. Nombra el skill a invocar, el archivo a leer, el comando a ejecutar.
• Por defecto en el chat. El bloque se renderiza en el chat dentro de un bloque de código delimitado para copiar y pegar. Un archivo HANDOFF-<slug>.md (un archivo raíz efímero, profile.ephemeral_patterns: en gitignore, nunca commiteado) solo cuando el usuario pide un archivo o el bloque supera ~60 líneas.
• Los pasos que afectan producción se nombran, con la razón. No "cuidado con el paso 8" sino qué escribe dónde y por qué no se puede deshacer.
• Disciplina de PII como siempre: ids y nombres; los correos electrónicos son identificadores de trabajo y pueden aparecer; nunca números de identificación nacional, teléfono o dirección.

Cuándo usarlo

• El cierre de cdv-finalize (imprime el handoff de QA él mismo, usando esta plantilla).
• El usuario pide un prompt para continuar una investigación, ejecutar una revisión o ejecutar QA en otra sesión.
• Una sesión está a punto de abandonarse porque su contexto creció (compactación inminente, "esto se está alargando").

Flujo de trabajo

Paso 0 — Cargar el perfil y la extensión

1. Lee .claude/harness/profile.yaml y, cuando exista, .claude/harness/profile.local.yaml (sus claves ganan). Si profile.yaml falta, detente y dilo: este skill necesita el perfil cdv-harness del repositorio, y nunca adivina los valores.
2. Lee <profile.extension_dir>/cdv-handoff.md cuando existe. La extensión solo añade o restringe; donde esta y este skill difieren, la extensión gana para este repositorio. Abajo, profile.<key> es un valor del perfil. Una clave que falta o es none significa que el repositorio no tiene esa cosa: salta el paso que la necesita.

Paso 1 — Determinar el tipo y recopilar hechos (todo solo lectura)

Tipo ∈ qa | review | investigation | continue-implementation. Luego ejecuta y guarda la salida cruda:

git branch --show-current
git worktree list --porcelain
git rev-list --count origin/<branch>..HEAD 2>/dev/null   # commits no pushados ('?' si no hay remoto)
git rev-list --count HEAD..origin/<profile.default_branch> # detrás de la rama por defecto
git status --porcelain | grep -v '^??'                   # archivos trackeados sin commit
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

Para qa: los fixtures provienen de los propios pasos del archivo QA (ids + etiquetas de visualización, como los necesita cdv-interactive-qa). Para review: el id del ticket mediante cdv-code-review/scripts/resolve-ticket-id.sh y si ya existe un <profile.pr_review_dir_prefix><TICKET>/. Para investigation: el bloque de hipótesis y la tabla de evidencia del reporte cdv-debug, textualmente. Para continue-implementation: los estados de fase de STATE-<slug>.md, su ## Finalize seed y si existe ## Verificación.

Paso 2 — Renderizar el bloque

Bloque de código delimitado, en profile.language_ui (los encabezados de sección en PT-BR a continuación se mantienen como están escritos), en este orden; omite una sección solo cuando está realmente vacía, y dilo (Sem fixtures pré-consultadas.):

<VERBO> da branch <branch> (<un frase de lo que entrega>).

ONDE ESTÁ O CÓDIGO
- <ruta del worktree | checkout principal `profile.main_checkout`>
- <N> commits por delante de origin/<profile.default_branch>; <M> commits NO pushados (confira: git rev-list --count origin/<branch>..HEAD)
- <archivos trackeados sin commit, o "árvore limpa">

ARMADILHA DO AMBIENTE  (solo cuando el código está en un worktree y `profile.worktree_runner` no es `none`)
- El worktree no tiene el entorno del checkout principal (dependencias, `.env`); `profile.cmd_container_exec` prueba el checkout principal, no este.
- Todo gate por: <profile.worktree_runner> <worktree> <comando de prueba> <filtro>
- Para QA en pantalla: traer la rama con <profile.bring_branch_script> --check <branch> y luego sin --check. Si se niega, PARE y pregunta — es WIP de otra sesión. Nunca git stash.
- Baseline actual: <N pasados (M aserciones)>, formateador <PASS>, análisis estático <OK>.

O QUE FAZER
- Invoca el skill <cdv-interactive-qa | cdv-code-review | cdv-debug | cdv-plan-feature>.
- <guión/archivo a leer, con ruta> | <id del ticket> | <reporte desde el que empezar>

FIXTURES REAIS (validadas en <fecha>)
- <entidad> <id> (<etiqueta como se muestra en pantalla>) — <estado que interesa>
- ...

PASSOS QUE ESCREVEM FORA DO LOCAL  [PRODUCTION-AFFECTING]
- Paso <n>: escribe <qué> en <sistema externo, de `profile.production_writing_integrations`>; irreversible porque <motivo>. Solo el usuario lo ejecuta, después de confirmar <qué>.
- (o) Nenhum — todo es lectura o escritura solo en la base local.

CONTEXTO QUE MUDA A EXPECTATIVA
- <el uno o dos hechos que de otro modo parecerían errores: "el comando de exportación sale con exit 0 por decisión", "la exportación solo se ejecuta de madrugada — probar con el comando manual es lo esperado">

NÃO FAÇA
- No cambies la rama del checkout principal por encima de WIP ajeno; no uses git stash.
- <cualquier cosa que el usuario haya excluido: "no investigar los dos registros duplicados">

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

Paso 3 — Autocomprobación antes de imprimir

• Cada número provino de un comando del Paso 1 (vuelve a ejecutarlo si el árbol cambió).
• Cada ruta existe (ls).
• Ninguna oración necesita este chat para ser entendida.
• La sección PRODUCTION-AFFECTING está presente (con contenido o con "Nenhum").

Composición

• cdv-finalize — imprime el tipo qa en su cierre usando esta plantilla; cuando este skill se invoca por sí solo después de un finalize, reutiliza los números del reporte de estado en lugar de volver a derivarlos.
• cdv-interactive-qa, cdv-code-review, cdv-debug, cdv-plan-feature — los receptores. El bloque nombra cuál invocar.
• Modo de terceros de cdv-code-review — un handoff de revisión para un PR de un colega lo dice explícitamente (branch de terceiro: sem apply-review).

Ejemplo (tipo qa, condensado)

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.