Handoff - 交接區塊產生器

Handoff

全新的會話比原先實作的會話更適合做 QA 與審查——因為前者的背景資訊較少，對程式碼也沒有情感依附。這是一種刻意的做法，而手順交接的品質決定其成敗。此技能能讓每一次交接都達到這個水準。

運作原則

• 事實必須驗證，而非記憶。 區塊中的每個計數、路徑與 ID 都來自當下執行的命令：git rev-list --count origin/<branch>..HEAD、git worktree list、ls QA-<slug>.md、從 QA 檔案中 grep 出的 fixture ID。若交接中寫「可能有 3 個提交未推送」，但實際計數是 5，就會誤導下一會話。
• 閱讀者只能看到這個區塊。 沒有「如同我們所見」，沒有提及本會話。直接寫明要呼叫的技能、要讀取的檔案、要執行的命令。
• 預設顯示於聊天室。 區塊會以圍欄式程式碼區塊呈現在聊天室中，方便複製貼上。僅在使用者要求檔案，或區塊超過約 60 行時，才會寫入 HANDOFF-<slug>.md 檔案（暫存根目錄檔案，profile.ephemeral_patterns：已加入 gitignore，永不提交）。
• 會影響生產環境的步驟須標明原因。 不是「小心步驟 8」，而是說明它在哪裡寫入了什麼，以及為什麼無法復原。
• 與其他地方相同的 PII 紀律： 使用 ID 與名字；電子郵件是工作識別碼，可以出現；絕對不能包含身分證字號、電話或地址。

使用時機

• cdv-finalize 的結尾（它會使用此模板輸出 QA 交接）。
• 使用者要求以另一會話繼續調查、執行審查或執行 QA 的提示。
• 因為會話上下文增長（即將壓縮、「這個會話越來越長」）而即將被放棄時。

工作流程

步驟 0 — 載入設定檔與擴充

1. 讀取 .claude/harness/profile.yaml，若存在 .claude/harness/profile.local.yaml 則以其鍵值為優先。若缺少 profile.yaml，則停止並告知：此技能需要此儲存庫的 cdv-harness 設定檔，且絕不猜測值。
2. 若 <profile.extension_dir>/cdv-handoff.md 存在，則讀取它。擴充只會增加或限制；當此技能與擴充衝突時，以此儲存庫的擴充為準。 以下，profile.<key> 是來自設定檔的值。若某鍵值缺失或為 none，代表該儲存庫沒有該項目：跳過需要它的步驟。

步驟 1 — 決定類型並收集事實（全部為唯讀）

類型 ∈ qa | review | investigation | continue-implementation。然後執行並保留原始輸出：

git branch --show-current
git worktree list --porcelain
git rev-list --count origin/<branch>..HEAD 2>/dev/null   # 未推送的提交（若無遠端則為 '?'）
git rev-list --count HEAD..origin/<profile.default_branch> # 落後於預設分支的數量
git status --porcelain | grep -v '^??'                   # 未提交的已追蹤檔案
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

對於 qa：fixture 來自 QA 檔案本身的步驟（ID 加上顯示標籤，如同 cdv-interactive-qa 所需）。對於 review：透過 cdv-code-review/scripts/resolve-ticket-id.sh 取得的 ticket ID，以及 <profile.pr_review_dir_prefix><TICKET>/ 是否已存在。對於 investigation：來自 cdv-debug 報告的假設區塊與證據表格，原文照錄。對於 continue-implementation：STATE-<slug>.md 的階段狀態、其 ## Finalize seed 以及 ## Verificação 是否存在。

步驟 2 — 渲染區塊

圍欄式程式碼區塊，使用 profile.language_ui（下方的 PT-BR 區段標題保持不變），按以下順序；只有當某區段完全為空時才刪除它，並明確說明（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  (僅當程式碼位於 worktree 且 `profile.worktree_runner` 不是 `none` 時)
- 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> 是 Rode o QA interativo、Faça o code review、Continue a investigação 或 Continue a implementação。

步驟 3 — 輸出前自我檢查

• 每個數字都來自步驟 1 中的命令（若樹狀結構已更改，請重新執行）。
• 每個路徑都存在（ls）。
• 沒有任何句子需要理解此會話才能看懂。
• PRODUCTION-AFFECTING 區段存在（有內容或寫著「Nenhum」）。

組合

• cdv-finalize — 在結尾使用此模板輸出 qa 類型的交接；當此技能在 finalize 之後單獨被呼叫時，重複使用狀態報告中的數字，而非重新推導。
• cdv-interactive-qa、cdv-code-review、cdv-debug、cdv-plan-feature — 接收端。區塊會指明要呼叫哪一個。
• cdv-code-review 第三方模式 — 針對同事 PR 的審查交接會明確說明（branch de terceiro: sem apply-review）。

範例（qa 類型，簡化版）

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.