Clube-do-Valor/cdv-handoff

ハンドオフ

新しいセッションは、実装したセッションよりも優れたQAとレビューを実行します。コンテキストが少なく、コードへの執着もありません。これは意図的なプラクティスであり、ハンドオフの成否がその成否を左右します。このスキルは、すべてのハンドオフをその水準に引き上げます。

運用原則

• 事実は検証され、記憶されない。 ブロック内のすべてのカウント、パス、IDは、今実行されたコマンドから取得されます：git rev-list --count origin/<branch>..HEAD、git worktree list、ls QA-<slug>.md、QAファイルからgrepされたfixture ID。カウントが5にもかかわらず「3つのコミットがプッシュされていない可能性があります」と記載されたハンドオフは、次のセッションを誤った方向に導きます。
• 読み手はブロックだけを手がかりにする。 「como vimos」のような表現はなく、このチャットへの参照もありません。呼び出すスキル、読み込むファイル、実行するコマンドを明示します。
• デフォルトはチャット。 ブロックはチャット内にコードブロック（コピー＆ペースト可能）として表示されます。ユーザーがファイルを明示的に要求した場合、またはブロックが約60行を超える場合にのみ、HANDOFF-<slug>.mdファイル（エフェメラルルートファイル、profile.ephemeral_patterns：gitignore対象、コミットされない）が生成されます。
• 本番環境に影響を与える手順は、理由とともに明記する。 「手順8に注意」ではなく、それが何をどこに書き込むのか、なぜ元に戻せないのかを記載します。
• PII（個人識別情報）の規律は他のすべてと同様に： IDとファーストネームは使用可能；メールアドレスは勤務先識別子として表示される可能性あり；国民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の場合：チケットIDはcdv-code-review/scripts/resolve-ticket-id.shを介して取得され、<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  (コードがワークツリーにあり、`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.