---
name: 交班
description: Session 收尾時產出結構化 handoff doc，固定寫到 docs/superpowers/handoff/ 供下次 session 接手。預設用 light 模式（極簡、給馬上接的下一個自己），加 --full 才產報告書版（給陌生人或幾天後接）。觸發情境：(1) 用戶說「交班」、「handoff」、「收工」(2) 工作告一段落要給下次 session 接手 (3) 用戶要結束對話前產出接續說明。不適用於：純粹 commit/PR（用 /go）、完成後無後續工作（直接做完即可）。
---

# 交班 — 產出 handoff doc

## 概述

當次 session 收尾時，把「已完成」「進行中」「下次要做的」「mental notes」寫成 markdown，存到 `docs/superpowers/handoff/` 目錄。下次新 session 用 `/接班` 直接讀最新一份接續工作。

**設計原則：** handoff 是寫給「下一個你（Claude）」的便條，不是寫給主管的報告。寫剛剛 5 分鐘前的自己會看不懂的東西，不要囉嗦記錄已經很明顯的事。

---

## 模式選擇（步驟 0）

**預設 `--light`**（馬上接、同 repo / 同 branch / 短時間內）：
- 10–20 行內、口語化、保留 in-flight 細節 + mental notes
- 不寫表格、不列環境變數路徑（除非剛剛真的動到）
- 適合 90% 情境

**加 `--full`**（陌生人接、跨 session 數天、跨 repo）：
- 完整 sections（已完成 / 部署狀態 / Critical path / Gotchas / Secrets map / 環境位置）
- 寫成「給沒看過這次對話的新人」能直接動手的密度

判斷：用戶沒講就用 `--light`。明顯是大型多日工作 / 要交給別人 / user 講「完整交班」「正式 handoff」才上 `--full`。

---

## 固定路徑

```
{repo-root}/docs/superpowers/handoff/YYYYMMDD-NN-<topic-slug>.md
```

- `YYYYMMDD`：交班當天日期（Asia/Taipei），如 `20260420`
- `NN`：當天的序號，從 `01` 開始，同一天多次交班遞增
- `<topic-slug>`：短英文或中文 slug（如 `phase3b-aibus-hub-handoff` 或 `shopify-app-migrate`）

**命名範例：**
- `20260420-01-phase3b-aibus-hub-handoff.md`
- `20260420-02-kb-deep-sync-review.md`
- `20260421-01-cashback-customer-flow.md`

---

## 執行流程

### 步驟 1：確認 repo-root

找當前工作目錄下有 `docs/superpowers/` 的 repo root。若不存在，先 `mkdir -p docs/superpowers/handoff/`。

### 步驟 2：決定檔名

1. 取今天日期 `YYYYMMDD`（用 Bash：`date +%Y%m%d`）
2. 列當天已有的交班檔：`ls docs/superpowers/handoff/YYYYMMDD-*.md 2>/dev/null`
3. 下一個序號 = 當天檔數 + 1（左補零到 2 位）
4. 跟用戶確認 topic slug（英文連字號或中文短詞皆可）

### 步驟 3：蒐集交班素材

依工作性質從 session context + tools 抓以下項目：

- **已完成事項**：這次 session 做了什麼（PR、commit、部署動作、決定、修好的 bug）
- **當前狀態**：哪些服務在哪，哪些已 live，哪些待部署
- **下次要做的 scope**：下一個 session 要接手的任務清單
- **架構決策**：這次定案的決策 + 理由（下次不用重問）
- **Critical path**：接手後第一步到最後一步的順序
- **Gotchas**：踩過的坑 + 解法
- **環境位置**：相關容器、網路、檔案路徑、DB、port
- **Secrets map**：敏感資訊不寫進 doc，只寫「在哪裡」（Mac Mini 路徑、env 變數、或請用戶重新提供）
- **相關 PR/commit**：列出這次 session 產出的 PR 號碼

### 步驟 4：用範本產生 handoff doc

#### 4a. Light 範本（預設）

口語化、不要把每段都做成 table。10–20 行就夠。

```markdown
# {Topic} — {一行描述下次要做什麼}

> {一句話脈絡：為什麼在做這個、上次卡哪}

## ✅ 剛做完
{一段話寫剛做了什麼，可附 commit hash / PR# 不用列表格}

## 🔄 In-flight（接班最重要看這段）
- **正在做**：{具體到 step / 檔名 / 行號}
- **卡在**：{錯誤訊息、等什麼、缺什麼資訊}
- **不要重做**：{已經做過的副作用，避免接班的下一個 Claude 重跑}
- **繼續從**：{下一個動作的具體指令 / 檔案路徑}

## ⏭ Next（in-flight 解掉之後）
1. {下一步}
2. {再下一步}

## 🧠 Mental notes（給下一個 Claude 的口袋話）
- {user 偏好 / 已否決方案 / 隱含 constraint / 對話建立的脈絡}
- 例：「user 偏好直接動手不要再 plan」「case 是 SQL 保留字所以用 case_discussion」「W1/W2 已過所以不加欄位」
```

**Light 模式重點：**
- 沒有 in-flight 就寫「無」一個字，不要硬湊
- Mental notes 至少寫 1–2 條，這是 light 模式最有價值的部分
- 不寫已經明顯能從 git log / git status 看到的東西

#### 4b. Full 範本（`--full` 才用）

**必備 sections**（根據任務性質可加可減）：

```markdown
# {Topic} Handoff — {一行描述下次要做什麼}

> **目標**：{一句話}
>
> {相依的 prerequisite Phase / PR，已做完的列出來}

---

## 已完成（不重做）

| 項目 | 狀態 | PR / Commit |
|------|------|-----|
| ... | ✅ | #xxx |

## 🔄 In-flight（半完成、不要重做）

- **正在做**：{step / 檔名 / 行號}
- **卡在**：{錯誤訊息、缺什麼、等什麼}
- **不要重做**：{已產生但無法 rollback 的副作用，如外部 API 呼叫過、資料已寫入}
- **繼續從**：{下一個動作的具體指令}

## 目前部署狀態

```
{service.domain}  ✅/❌  {環境 / DATA_STORE / 備註}
```

## Scope（這次 session 要做的）

1. **{step 1}**：{做什麼、動到哪些檔}
2. ...

---

## 架構決策（已定，沿用）

| # | 決策 | 理由 |
|---|------|------|
| 1 | ... | ... |

## Critical path（下次 session 第一步到最後）

1. **Read X**：看哪些檔、grep 什麼 symbol
2. **寫 plan**：format 同 `docs/superpowers/plans/xxx.md`
3. **Spawn agent** 做實作
4. **部署 + smoke test**

## Gotchas（踩過的坑，避免重犯）

| # | 問題 | 解法 |
|---|------|------|
| 1 | ... | ... |

## 🧠 Mental notes（給下一個 Claude 的口袋話）

寫對話建立的脈絡，不寫架構決策（架構決策上面有專欄）。
- {user 偏好 / 已否決方案 / 隱含 constraint}
- 例：「user 偏好直接動手不要再 plan」「case 是 SQL 保留字所以用 case_discussion」「W1/W2 已過所以不加欄位」

---

## 環境/位置（會用到的路徑）

```
~/docker/xxx/    ← 部署目錄
aibus-network    ← docker network
container-name   ← port mapping
```

## Secrets（不在這份 doc）

| 項目 | 位置 |
|------|------|
| xxx | {Mac Mini path / env var / 請用戶重新提供} |

---

## 相關 PR / 變更

- #xxx — {描述}

---

## 變更紀錄

| 日期 | 變更 | 作者 |
|------|------|------|
| YYYY-MM-DD | 初版 | Claude + {user name} |
```

### 步驟 5：寫 doc + commit + PR（建議）

1. `Write` 檔案到 `docs/superpowers/handoff/{filename}.md`
2. 跟用戶確認內容大綱（一句話摘要 + critical path）
3. 若是獨立分支：`git commit` 後開 PR（用 `gh pr create`），PR body 放 handoff summary
4. 回報 PR URL 給用戶，提醒下次可說「繼續做 X」或「看 handoff 然後做」

### 步驟 6：告知 session 結束方式

最後一段回應用戶：

```
下次 session 開場只要說：
- 「繼續做 {topic}」
- 「看 handoff 然後做」
- 「/接班」（若有 skill 對應）

新 session 會自動讀 docs/superpowers/handoff/{filename}.md 接手。

這次 session 工作成果：
- {完成項目 1}
- {完成項目 2}
...
```

---

## 注意事項

1. **不寫 secret 到 doc**：密碼、token、key 只寫「在哪裡找」，不寫值。doc 會進 git 歷史
2. **寫絕對路徑**：下次 session 沒有上下文，`./xxx` 或「上面提到的檔」都看不懂
3. **Critical path 要有順序**：step 1 → step 2 → step 3，不要平行列清單，因為接手的人要照順序做
4. **列 PR 號碼**：所有這次 session 產出的 PR 都要列，方便下次查 git 歷史
5. **Gotchas 要具體**：寫「symptom」「root cause」「解法」，不要只寫「XXX 有問題」
6. **不要 commit session summary**：這是操作性交班，不是歷史文件。寫完就進 handoff 目錄，不要發到其他地方
7. **當天多份交班用序號區分**：不要 overwrite 同天的檔
8. **commit 時若該 branch 有 uncommitted 變更**：先跟用戶確認，不要把進行中的 code 變更跟 handoff doc 綁在一起

---

## 變數

- **repo-root**：執行 skill 時的 repo 根目錄（含 `docs/superpowers/`）
- **date_utc8**：Asia/Taipei 當天日期 `YYYYMMDD`
- **topic_slug**：用戶確認的 topic 短詞
