---
name: sdlc-handoff
description: 'Session handoff and takeover that works with any coding agent. 会话交接与会话接手：旧会话上下文将满、或任务要换会话/换机器/换 agent 继续时，把当前任务压缩成一张自足的交接卡（write）；新会话读取交接卡并直接继续（resume），覆盖开发、排查、梳理、调研、文档等任意任务。Use when 交接、接手、继续上次的工作、上下文满了、换个会话做、上次做到哪了、pick up where I left off, handoff, resume previous work, context is full. 用法：/sdlc-handoff write|resume|list'
license: MIT
---

# 交接（sdlc-handoff）

> **定位**：上下文将满、或要换会话／换机器／换 agent 时，把「任务做到哪」压成一张**自足的交接卡**；新会话凭卡直接继续，不必重述背景。覆盖开发、排查、梳理、调研、文档任意任务——不限于 SDLC 某一阶段。

**路径基准**：文中 `scripts/...`、`references/...` 一律相对本文件所在目录（技能根目录）解析。

**平台无关**：本 skill 不依赖任何具体 agent 的目录、环境变量、工具名或斜杠行为。脚本无法执行时，按 [manual-collect.md](references/manual-collect.md) 用现有工具采集同样字段；会话记录读不到时，靠交接卡本身继续。

## 三种动作

| 用户意图 | 动作 |
|---|---|
| 「交接一下」「上下文满了」「换个会话做」「换 agent 继续」 | write |
| 「接手」「继续上次」「上次做到哪了」「按这张卡继续」 | resume |
| 「有哪些交接卡」「列一下交接」 | list |
| 同一会话内只是历史太长、任务仍在推进 | 不做交接，用 agent 自带的上下文压缩 |

无参数时给出三选一，不要猜；同时说明「同一会话内只是历史太长」可以不走交接。**list** 即执行 resume 第 1 步的扫描与展示（时间 / 任务 / `status` / `next`）后结束，不进入接手。

长任务不必等上下文将满：每完成一个里程碑都可主动 write 一张存档卡（`status` 按实际填，`prev` 指向上一张）——越接近上下文上限，压缩质量越差。

## write：产出交接卡

1. **空会话不产卡**：本会话无实质工作（无文件改动、无工具调用记录）时直接说明，建议开新会话即可。
2. **采集硬事实**：执行 `bash <技能根>/scripts/collect.sh`。脚本不可执行或环境不支持时，按 [manual-collect.md](references/manual-collect.md) 逐项采集。
3. **补会话外状态**：若工具集提供后台进程/长任务列表，记录仍在运行的项；否则在卡里写明「未检查」。
4. **写卡**：按 [handoff-template.md](references/handoff-template.md) 的 8 段结构落盘到「落盘与命名」约定的位置。collect 输出的 handoffs 段有同任务存续卡时，填 `prev` 并继承其「背景与目标」与未结待办，按现状改写、不凭记忆重写。
5. **自检**（逐条过，不通过就改）：
   - 8 段齐全，`next` 是单条可直接执行的下一步
   - 正文 ≤120 行；单个代码块 ≤10 行
   - 每项「已完成」都带 `已跑通` / `未验证` / `仅编译`，未验证不得写成已完成
   - 未提交改动、后台任务、临时产物都有落点
   - 无 diff、无大段代码、无原文照抄
   - **接手者五问**：只读这张卡，能答上「为什么做 / 第一步干什么 / 有什么环境坑 / 哪条路已否决别重走 / 找谁拍板」吗？答不上就补卡
6. **交付启动语**：输出新会话的第一句话 `接手 <交接卡绝对路径>`，并建议会话名（`<任务关键词>-<日期>`）。不写死任何平台的斜杠命令。

## resume：接手

1. **定位卡片**：给了路径就用路径；否则按修改时间扫描 `<项目根>/.handoff/` → `~/.handoff/`。命中多张时列 top3（时间 / 任务 / `next`），让用户挑，不猜。
2. **漂移校验**（只用 git，不依赖平台）：
   - `repo` 与当前项目根不一致 → 说明「卡来自另一个目录」
   - `branch` 不一致 → 直接指出
   - `head` 不在当前 HEAD 的祖先链上 → 疑似 rebase / force-push
   - `dirty_files` 与当前 `git status --porcelain | wc -l` 不一致 → 列出新增/消失的改动
   - **只报告，不阻断**；用户没要求就不要回滚任何文件。
3. **读卡并给接手确认**（固定四要素，各一行，共 ≤10 行）：① 任务与背景（是什么、为什么）② 断点位置 ③ 我要执行的第一步 ④ 需要用户拍板的风险或未决问题。固定结构让人扫一眼即可校验理解是否偏差。
4. **按需补细节**：卡不足以判断、且 `session_ref` 可达时，执行
   `python3 <技能根>/scripts/digest_transcript.py --session <session_ref> --tail 40`。
   不可达或解析失败就跳过，靠卡继续——**绝不要求用户重述背景**。
5. **断点复核**：卡中断点或 `next` 带可复现命令（如「此时跑 X 应 2 条失败」）时，先复现一次再动手；结果与卡不符按漂移报告，不急着开工。
6. **直接执行 `next`**：不重述全部背景、不重做「已完成」里的步骤、不推翻已记录决策。只有 `next` 存在真正歧义时，问一个具体问题。
7. **收尾留痕**（append-only）：推进后在卡末尾追加 `- [时间] 已推进：<结果>`；过程中新增的决策、否决方案、环境坑分别追加进对应段并标时间，不改写历史行。再交接时写新卡、以本卡为 `prev`，避免过期卡被当成现行状态。

## 交接卡里的 8 段

1. **背景与目标**——项目与栈、为什么做、验收口径（接手者 30 秒建立心智模型）
2. **已完成**——每项带验证状态
3. **断点位置**——精确到 `文件:行` 或正在跑的命令
4. **关键决策与已否决方案**——代码里读不到的，防新会话重走死路
5. **改动清单**——来自 git 事实，不贴 diff
6. **有序待办**——每步可独立执行，标注依赖
7. **未决问题**——需要人拍板的
8. **指针与操作须知**——怎么跑/怎么验、环境坑、会话记录 / 计划文档 / 后台任务 / 临时产物

正文预算 120 行。写不下说明这张卡该拆。

## 落盘与命名

```
<项目根>/.handoff/YYYYMMDD-HHmm-<slug>.md      # 项目内优先
~/.handoff/YYYYMMDD-HHmm-<slug>.md             # 非 git 目录 / 跨项目兜底
```

- `<slug>`：任务描述小写化、非字母数字转 `-`、截断到 40 字符
- `HANDOFF_DIR` 可覆盖全局兜底目录
- 项目内目录建议加进 `.gitignore`；需要跨机器时可自行决定是否提交

## 红线

- **不贴 diff、不贴代码、不抄原文**：只给 `文件:行` 指针
- **不把未验证写成已完成**：验证状态必须显式标注
- **resume 不重做、不翻案**：已记录决策只有在用户明确推翻时才改
- **不写凭据**：token、密钥、真实公司名与内网地址一律用 `<占位>`
- **不覆盖旧卡**：永远按时间戳新建
- **不诱导平台依赖**：不要在卡里写「用某个命令恢复」，启动语只写自然语言

## 脚本

| 脚本 | 作用 | 缺失时 |
|---|---|---|
| `scripts/collect.sh` | 采集 git 状态、改动清单、最近提交、已有交接卡、可选会话/临时产物 | 按 [manual-collect.md](references/manual-collect.md) 手工采集 |
| `scripts/digest_transcript.py` | 把 JSONL 会话记录压成「用户原话 + 动作时间线 + 触碰文件」，供 resume 补细节 | 跳过该增强，靠交接卡继续 |