---
name: handoff
description: 会话交接文档生成 - 总结当前会话的任务、已完成项、卡点、下一步、踩坑警示，写入 HANDOFF.md 供新会话接手
---

会话结束前生成交接文档，把本次会话的上下文打包成一份完全没有背景的人也能看懂的 HANDOFF.md。

## Usage

```
/handoff            # 生成本次会话的交接文档到 HANDOFF.md
/handoff 仅审查      # 仅输出交接摘要到对话，不写文件
```

## 为什么要这个 skill

会话结束后，新会话（或新人）接手时完全没有上下文。如果不主动总结，关键信息会随会话消失：
- 我们在做什么任务、为什么做
- 已经完成了哪些、验证到什么程度
- 当前卡在哪一步、下一步该干什么
- 踩过哪些坑、绝对不要再踩

一份好的交接文档能让接手者 5 分钟内进入状态，而不是花 30 分钟翻对话历史猜上下文。

## 输出位置

- **文件**：项目根目录 `HANDOFF.md`（与 CLAUDE.md 同级，最显眼处）
- **覆盖策略**：如已存在 HANDOFF.md，询问是覆盖、追加还是另存为 `HANDOFF_<日期>.md`

## 交接文档结构（固定六节）

```markdown
# HANDOFF — <任务一句话标题>

> 最后更新：YYYY-MM-DD HH:MM ｜ 分支：<branch> ｜ 负责人：<who>

## 1. 我们在做什么
（任务背景：为什么做、目标是什么、来源是哪个 PRD/需求/issue。2-3 段，让接手者知道"为什么"。）

## 2. 已经完成了什么
（按时间或子任务顺序列出已完成项，每项一行，标注✅。关键文件路径、关键决策、验证结果都要写明。
不要只写"做完了"，要写"做到了什么程度、怎么验证的"。）

## 3. 当前卡在哪
（现在停在哪一步、为什么停。是等用户确认？等外部依赖？遇到报错？还是自然完成等下一步指令？
如果是报错，贴关键错误信息。如果是等确认，写清楚在等什么、给谁。如果已全部完成没卡点，明确写"无卡点，等待下一步指令"。）

## 4. 下一步计划
（接手者打开新会话后第一件事该做什么。按优先级编号列出 2-5 条具体动作，每条可执行。
不要写"继续优化"这种模糊的，要写"执行 P1-2：在 skill/code/tests/ 下用 pytest 覆盖 search_engine.py"。）

## 5. 踩过的坑（绝对不要再踩）
（本次会话踩过的坑、犯过的错、浪费过时间的点。每条写：坑是什么 + 为什么会踩 + 怎么避免。
这是交接文档最有价值的一节——让接手者不重蹈覆辙。）

## 6. 关键文件与命令速查
（本次任务涉及的核心文件路径、常用命令、环境配置。让接手者不用翻目录就能上手。）
```

## 执行步骤

1. **回溯会话上下文**：扫描当前会话已完成的工具调用和结论，提取：任务目标、已完成子任务、当前状态、遇到的问题
2. **补充外部状态**：
   - `git branch --show-current` 获取当前分支
   - `git status --short` 获取工作区状态（哪些文件改了、哪些未提交）
   - `git log --oneline -5` 获取最近提交（判断已提交 vs 待提交）
3. **检查 HANDOFF.md 是否已存在**：存在则用 AskUserQuestion 询问覆盖/追加/另存
4. **按六节结构生成文档**：
   - 第 1 节：背景要写"为什么做"，不只是"做什么"
   - 第 2 节：每项标✅，写明验证方式（如"HTTP 验证通过：/api/health 返回 ok"）
   - 第 3 节：诚实写卡点，没有就写"无卡点"
   - 第 4 节：下一步要具体到可执行动作，按优先级编号
   - 第 5 节：**这是重点**——所有踩过的坑、走过的弯路、犯过的错，每条写清"坑 + 原因 + 避免方法"
   - 第 6 节：列出本次涉及的关键文件路径和命令
5. **写入 HANDOFF.md** 并向用户展示摘要
6. **提醒**：是否要把 HANDOFF.md 加入 git（提交 or 忽略，由用户决定）

## 写作原则

- **写给完全没上下文的人看**：不假设读者知道任何前置信息，所有专有名词第一次出现要解释
- **诚实**：完成就写完成，没完成就写没完成，验证失败就贴失败原因。不要美化状态
- **具体优于抽象**："修改了 server.py 的异常处理"是坏的，"把 server.py 第 695-1245 行的 12 处 `except Exception` 改为 `logger.exception`"是好的
- **踩坑要写透**：不只是"踩了坑"，要写"为什么会踩、下次怎么第一时间避开"
- **可执行**：下一步计划要让接手者能直接照做，不用再决策
- **不堆代码**：交接文档是地图不是代码本，引用文件路径而非贴大段代码

## 注意事项

- **必须包含第 5 节踩坑**：这是交接文档的核心价值，没踩坑就写"本次会话较顺利，无重大踩坑"
- **不要把整个会话复述一遍**：交接文档是摘要，不是流水账。只保留对下一步有用的信息
- **关键决策要留痕**：为什么选 A 不选 B、为什么放弃某个方案——这些对话历史里查不到的决策理由要写明
- **敏感信息脱敏**：密码、密钥不要写进 HANDOFF.md，写"使用环境变量 SSH_PASSWORD（见 .env）"即可
- **文件路径用 repo 相对路径**：如 `skill/code/web/server.py`，不要用绝对路径
- **日期用绝对日期**：写 `2026-07-13` 不写"今天"，交接文档可能跨天看
