pause-work

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/pause - Session Handoff

/pause - 会话交接

Operator Context

操作上下文

This skill captures ephemeral session reasoning into durable artifacts so the next session can resume without wasting time on context reconstruction. It solves a specific gap:

task_plan.md

records WHAT tasks exist, but not WHY the current session chose a particular approach, what it rejected, or what it planned to do next.

The two output files serve different audiences:

```
HANDOFF.json
```
— machine-readable, consumed by
```
/resume
```
for automated state reconstruction
```
.continue-here.md
```
— human-readable, for users who want to understand session state without starting a new session

本技能会将临时的会话推理内容保存为持久化工件，让下一个会话无需浪费时间重建上下文即可恢复。它解决了一个特定的缺口：

task_plan.md

记录了存在哪些任务，但不会记录当前会话为何选择特定方案、否决了哪些方案，或是计划下一步做什么。

生成的两个输出文件面向不同受众：

```
HANDOFF.json
```
—— 机器可读格式，供
```
/resume
```
技能用于自动化状态重建
```
.continue-here.md
```
—— 人类可读格式，供无需启动新会话即可了解当前会话状态的用户查看

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Dual-Format Output: Always produce BOTH
```
HANDOFF.json
```
and
```
.continue-here.md
```
. The machine format enables automated resume; the human format enables manual inspection. Skipping either breaks half the use case.
Uncommitted Work Detection: Always run
```
git status
```
and
```
git diff --stat
```
to identify uncommitted changes. Uncommitted work is the highest-risk information to lose across sessions.
False Completion Detection: Grep for placeholder markers (TODO, FIXME, PLACEHOLDER, TBD, XXX, HACK, stub, not yet implemented) in uncommitted files. These indicate work that looks done but is not — the most dangerous handoff failure mode.
Project Root Placement: Write both files to the project root (where
```
.git/
```
lives), not the current working directory if different. This ensures
```
/resume
```
can find them reliably.
No Destructive Operations: This skill only creates files. It never deletes, modifies existing code, or runs destructive git commands.

CLAUDE.md 合规性：执行前需阅读并遵循仓库中的CLAUDE.md
双格式输出：始终同时生成
```
HANDOFF.json
```
和
```
.continue-here.md
```
。机器格式支持自动化恢复，人类格式支持人工检查。缺少任意一个都会导致一半的用例失效。
未提交工作检测：始终运行
```
git status
```
和
```
git diff --stat
```
来识别未提交的变更。未提交工作是跨会话最容易丢失的高风险信息。
虚假完成检测：在未提交文件中搜索占位标记（TODO、FIXME、PLACEHOLDER、TBD、XXX、HACK、stub、not yet implemented）。这些标记表示看起来已完成但实际未完成的工作，是交接失败最危险的模式。
项目根目录存放：将两个文件写入项目根目录（即
```
.git/
```
所在目录），而非当前工作目录（若两者不同）。确保
```
/resume
```
技能能可靠找到它们。
无破坏性操作：本技能仅创建文件，从不删除、修改现有代码，或执行破坏性git命令。

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

WIP Commit Suggestion: If uncommitted changes exist, suggest a WIP commit before pausing. Uncommitted work can be lost if the worktree is cleaned up. Do not auto-commit — suggest and let the user decide.
task_plan.md Integration: If
```
task_plan.md
```
exists, read it and incorporate its phase status into the handoff. The handoff supplements the plan, it does not replace it.
Timestamp in ISO 8601: All timestamps use UTC ISO 8601 format for unambiguous parsing.

WIP提交建议：若存在未提交变更，建议在暂停前创建WIP提交。若工作树被清理，未提交工作可能丢失。请勿自动提交——仅给出建议，由用户决定。
task_plan.md 集成：若
```
task_plan.md
```
存在，读取该文件并将其阶段状态整合到交接内容中。交接内容是对计划的补充，而非替代。
ISO 8601时间戳：所有时间戳均采用UTC ISO 8601格式，确保解析无歧义。

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

Auto-Commit Handoff (
```
--commit
```
): Commit the handoff files on the current branch. Default is to leave them uncommitted so the user can review first.
Quiet Mode (
```
--quiet
```
): Skip the confirmation summary. For automated/scripted usage.

自动提交交接文件（
```
--commit
```
）：将交接文件提交到当前分支。默认不提交，以便用户先审核。
静默模式（
```
--quiet
```
）：跳过确认摘要。适用于自动化/脚本化场景。

What This Skill CAN Do

本技能可实现的功能

Capture completed tasks, remaining work, blockers, and decisions into structured handoff files
Detect uncommitted work and suggest WIP commits
Detect false completions (placeholder markers in modified files)
Synthesize the session's reasoning context (approach chosen, alternatives rejected, mental model)
Optionally commit handoff artifacts to the current branch

将已完成任务、剩余工作、阻塞问题和决策捕获到结构化交接文件中
检测未提交工作并建议创建WIP提交
检测虚假完成（修改文件中的占位标记）
整合会话推理上下文（所选方案、否决的替代方案、思维模型）
可选将交接工件提交到当前分支

What This Skill CANNOT Do

本技能不可实现的功能

Replace
```
task_plan.md
```
— handoffs capture session reasoning, plans capture task structure
Auto-commit code changes — it only suggests WIP commits, never executes them without user consent
Guarantee reasoning accuracy — handoff quality depends on the session's self-awareness (same limitation as any self-assessment)
Resume from handoff files — that is the
```
resume-work
```
skill

替代
```
task_plan.md
```
—— 交接内容捕获会话推理，计划内容捕获任务结构
自动提交代码变更 —— 仅建议创建WIP提交，未经用户同意绝不执行提交
保证推理准确性 —— 交接质量取决于会话的自我认知（与任何自我评估有相同局限性）
从交接文件恢复会话 —— 这是
```
resume-work
```
技能的功能

Instructions

操作步骤

Phase 1: GATHER

阶段1：收集

Goal: Collect all state needed for the handoff.

Step 1: Identify project root

Find the git root directory:

bash

git rev-parse --show-toplevel

All subsequent paths and file writes are relative to this root.

Step 2: Collect git state

Run these commands to capture the current state:

bash

undefined

目标：收集交接所需的所有状态信息。

步骤1：确定项目根目录

找到git根目录：

bash

git rev-parse --show-toplevel

后续所有路径和文件写入操作均相对于此根目录。

步骤2：收集Git状态

运行以下命令捕获当前状态：

bash

undefined

Current branch

当前分支

git branch --show-current

Uncommitted files (staged and unstaged)

未提交文件（已暂存和未暂存）

git status --short

Summary of uncommitted changes

未提交变更摘要

git diff --stat git diff --cached --stat

Recent commits on this branch (for context)

当前分支的最近提交（用于上下文）

git log --oneline -10


**Step 3: Check for false completions**

Search uncommitted/modified files for placeholder markers:

```bash

git log --oneline -10


**步骤3：检测虚假完成**

在未提交/修改的文件中搜索占位标记：

```bash

Get list of modified files

获取修改文件列表

git diff --name-only git diff --cached --name-only


Use the Grep tool to search those files for these patterns: `TODO`, `FIXME`, `PLACEHOLDER`, `TBD`, `XXX`, `HACK`, `stub`, `not yet implemented`.

Record any findings — these are items that look complete but are not.

**Step 4: Read task_plan.md if present**

If `task_plan.md` exists in the project root, read it to extract:
- Which phases are complete (marked `[x]`)
- Which phases remain (marked `[ ]`)
- Current status line
- Decisions and errors logged

**Step 5: Read .adr-session.json if present**

If `.adr-session.json` exists, note the active ADR for context in the handoff.

**GATE**: Git state collected. Modified file list available. Placeholder scan complete. Ready to synthesize.

git diff --name-only git diff --cached --name-only


使用Grep工具在这些文件中搜索以下模式：`TODO`、`FIXME`、`PLACEHOLDER`、`TBD`、`XXX`、`HACK`、`stub`、`not yet implemented`。

记录所有发现——这些是看起来已完成但实际未完成的项。

**步骤4：读取task_plan.md（若存在）**

若项目根目录中存在`task_plan.md`，读取并提取以下内容：
- 已完成的阶段（标记为`[x]`）
- 剩余阶段（标记为`[ ]`）
- 当前状态行
- 已记录的决策和错误

**步骤5：读取.adr-session.json（若存在）**

若`.adr-session.json`存在，记录当前活跃的ADR，作为交接上下文的一部分。

**检查点**：Git状态已收集，修改文件列表已获取，占位标记扫描已完成，准备整合。

Phase 2: SYNTHESIZE

阶段2：整合

Goal: Combine gathered state with session reasoning into handoff content.

Step 1: Construct completed_tasks

List what was accomplished this session. Draw from:

Git commits made during the session
Phases marked complete in task_plan.md
Work the session performed (files created, edited, reviewed)

Be specific: "Implemented scoring module in scripts/quality-score.py" not "Did some work on scoring."

Step 2: Construct remaining_tasks

List what still needs to be done. Draw from:

Unchecked phases in task_plan.md
Placeholder markers found in Phase 1 Step 3
Known incomplete work from session context

Step 3: Construct decisions

Record key decisions made during the session and WHY. This is the highest-value handoff content because it prevents the next session from re-exploring dead ends.

Format:

{"decision description": "reasoning for the decision"}

Step 4: Construct next_action

Write a specific, actionable description of what the next session should do first. Include:

The exact action (not vague "continue working")
Relevant file paths and function names
Integration points or dependencies
Why this is the right next step

Step 5: Construct context_notes

Capture the session's mental model — the reasoning context that is NOT captured in code or commits:

Approaches tried and rejected (and why)
Assumptions being made
Gotchas discovered
Performance or design trade-offs considered

GATE: All handoff fields populated with specific, actionable content. No vague entries like "continue work" or "finish implementation."

目标：将收集到的状态与会话推理整合为交接内容。

步骤1：构建completed_tasks

列出本次会话完成的工作，可从以下来源获取信息：

会话期间创建的Git提交
task_plan.md中标记为完成的阶段
会话执行的工作（创建、编辑、审核的文件）

描述需具体：例如“在scripts/quality-score.py中实现评分模块”，而非“做了一些评分相关的工作”。

步骤2：构建remaining_tasks

列出仍需完成的工作，可从以下来源获取信息：

task_plan.md中未勾选的阶段
阶段1步骤3中发现的占位标记
会话上下文中已知的未完成工作

步骤3：构建decisions

记录会话期间做出的关键决策及原因。这是交接内容中价值最高的部分，可避免下一个会话重复探索已被否决的方案。

格式：

{"决策描述": "决策的推理过程"}

步骤4：构建next_action

写下下一个会话应首先执行的具体、可操作的描述，包括：

具体操作（而非模糊的“继续工作”）
相关文件路径和函数名
集成点或依赖关系
为何这是正确的下一步

步骤5：构建context_notes

捕获会话的思维模型——未在代码或提交中体现的推理上下文：

尝试过并否决的方案及原因
做出的假设
发现的陷阱
考虑过的性能或设计权衡

检查点：所有交接字段已填充具体、可操作的内容，无“继续工作”或“完成实现”等模糊表述。

Phase 3: WRITE

阶段3：写入

Goal: Write both handoff files to the project root.

Step 1: Write HANDOFF.json

Write to

{project_root}/HANDOFF.json

json

{
  "created_at": "<ISO 8601 UTC timestamp>",
  "task_summary": "<Brief description of the overall task>",
  "completed_tasks": [
    "<Specific completed item 1>",
    "<Specific completed item 2>"
  ],
  "remaining_tasks": [
    "<Specific remaining item 1>",
    "<Specific remaining item 2>"
  ],
  "blockers": [
    "<Blocker if any, or empty array>"
  ],
  "decisions": {
    "<Decision 1>": "<Reasoning>",
    "<Decision 2>": "<Reasoning>"
  },
  "uncommitted_files": [
    "<file1>",
    "<file2>"
  ],
  "next_action": "<Specific next action with file paths and integration points>",
  "context_notes": "<Mental model, rejected approaches, gotchas, assumptions>",
  "branch": "<current branch name>",
  "base_branch": "main",
  "false_completions": [
    "<file:line — placeholder marker found, if any>"
  ]
}

Step 2: Write .continue-here.md

Write to

{project_root}/.continue-here.md

markdown

undefined

目标：将两个交接文件写入项目根目录。

步骤1：写入HANDOFF.json

写入到

{project_root}/HANDOFF.json

：

json

{
  "created_at": "<ISO 8601 UTC timestamp>",
  "task_summary": "<任务整体的简要描述>",
  "completed_tasks": [
    "<具体已完成项1>",
    "<具体已完成项2>"
  ],
  "remaining_tasks": [
    "<具体剩余项1>",
    "<具体剩余项2>"
  ],
  "blockers": [
    "<阻塞问题（若有），否则为空数组>"
  ],
  "decisions": {
    "<决策1>": "<推理过程>",
    "<决策2>": "<推理过程>"
  },
  "uncommitted_files": [
    "<file1>",
    "<file2>"
  ],
  "next_action": "<包含文件路径和集成点的具体下一步操作>",
  "context_notes": "<思维模型、否决的方案、陷阱、假设>",
  "branch": "<当前分支名称>",
  "base_branch": "main",
  "false_completions": [
    "<file:line — 发现的占位标记（若有）>"
  ]
}

步骤2：写入.continue-here.md

写入到

{project_root}/.continue-here.md

：

markdown

undefined

Continue Here

What I was doing

我正在做什么

[Prose description of the task, current state, and approach being taken]

[任务、当前状态和采用方案的散文式描述]

What's done

已完成

[Completed item 1]
[Completed item 2]

[已完成项1]
[已完成项2]

What's next

下一步

[Specific next action — what to do, which files, why this step]

[具体的下一步操作——做什么、涉及哪些文件、为何选择此步骤]

Key decisions

关键决策

[决策1]：[原因]
[决策2]：[原因]

Watch out for

需要注意

[Blockers, gotchas, dead ends already explored]
[False completions found: file:line — marker]

[阻塞问题、陷阱、已探索过的死胡同]
[发现的虚假完成：file:line — 标记]

Uncommitted work

未提交工作

[file1 — brief description of changes]
[file2 — brief description of changes]


**Step 3: Suggest WIP commit if needed**

If there are uncommitted changes (from Phase 1 Step 2), display:

WARNING: Uncommitted changes detected in N file(s):

file1
file2

Consider a WIP commit before ending the session: git add <files> && git commit -m "wip: <description>"

Uncommitted work can be lost if the worktree is cleaned up.


Do NOT auto-commit. The user decides.

**Step 4: Optional commit of handoff files**

If `--commit` flag was provided:
```bash
git add HANDOFF.json .continue-here.md
git commit -m "chore: session handoff artifacts"

GATE: Both files written to project root. User notified of uncommitted work if any.

[file1 — 变更的简要描述]
[file2 — 变更的简要描述]


**步骤3：必要时建议WIP提交**

若存在未提交变更（来自阶段1步骤2），显示以下内容：

警告：检测到N个文件存在未提交变更：

file1
file2

建议在结束会话前创建WIP提交： git add <files> && git commit -m "wip: <描述>"

若工作树被清理，未提交工作可能丢失。


请勿自动提交，由用户决定。

**步骤4：可选提交交接文件**

若提供了`--commit`参数：
```bash
git add HANDOFF.json .continue-here.md
git commit -m "chore: session handoff artifacts"

检查点：两个文件已写入项目根目录，若存在未提交工作已通知用户。

Phase 4: CONFIRM

阶段4：确认

Goal: Display summary and confirm handoff was captured.

Display the handoff summary:

===================================================================
 SESSION PAUSED
===================================================================

 Handoff files created:
   - HANDOFF.json (machine-readable)
   - .continue-here.md (human-readable)

 Completed: N task(s)
 Remaining: N task(s)
 Blockers: N
 Uncommitted files: N
 False completions: N placeholder(s) found

 Next action: <brief next_action summary>

 Resume with: /resume
===================================================================

目标：显示摘要并确认交接已完成。

显示交接摘要：

===================================================================
 会话已暂停
===================================================================

 已创建交接文件：
   - HANDOFF.json（机器可读）
   - .continue-here.md（人类可读）

 已完成：N项任务
 剩余：N项任务
 阻塞问题：N个
 未提交文件：N个
 虚假完成：发现N个占位标记

 下一步操作：<next_action的简要摘要>

 使用/resume技能恢复会话
===================================================================

Error Handling

错误处理

Error: Not in a Git Repository

错误：不在Git仓库中

Cause:

git rev-parse --show-toplevel

fails — no

.git/

directory found Solution: Handoff files require git context for branch and uncommitted file detection. Navigate to a git repository root and retry.

原因：

git rev-parse --show-toplevel

执行失败——未找到

.git/

目录 解决方案：交接文件需要Git上下文来检测分支和未提交文件。请导航到Git仓库根目录后重试。

Error: Cannot Determine Session Work

错误：无法确定会话工作内容

Cause: No commits on current branch, no task_plan.md, no uncommitted changes — nothing to hand off Solution: If the session genuinely did no work, there is nothing to hand off. Inform the user: "No work detected to hand off. If you made changes that aren't committed or tracked, describe what you were working on and I'll create the handoff manually."

原因：当前分支无提交、无task_plan.md、无未提交变更——无内容可交接 解决方案：若会话确实未完成任何工作，则无需交接。告知用户：“未检测到可交接的工作。若你进行了未提交或未跟踪的变更，请描述你正在做的工作，我将手动创建交接文件。”

Error: HANDOFF.json Already Exists

错误：HANDOFF.json已存在

Cause: A previous

/pause

created handoff files that were never consumed by

/resume

Solution: Warn the user that stale handoff files exist. Offer to overwrite (default) or append. Overwriting is almost always correct — stale handoffs from abandoned sessions should not block new ones.

原因：之前的

/pause

操作创建了交接文件，但尚未被

/resume

技能使用 解决方案：警告用户存在过期的交接文件，提供覆盖（默认）或追加选项。覆盖几乎总是正确的选择——来自已终止会话的过期交接不应阻碍新的交接。

Anti-Patterns

反模式

Anti-Pattern 1: Vague Next Actions

反模式1：模糊的下一步操作

What it looks like:

"next_action": "Continue working on the feature"

Why wrong: The entire point of handoff is to avoid reconstruction. Vague next actions force the next session to re-discover what "continue working" means. Do instead: Be specific:

"next_action": "Wire quality-score.py into pr-pipeline Phase 3. The function signature is score_package(path) -> ScoreResult. Integration point is the gate check between STAGE and REVIEW phases."

表现：

"next_action": "继续开发功能"

为何错误：交接的核心目的是避免上下文重建。模糊的下一步操作会迫使下一个会话重新探索“继续工作”的具体含义。 正确做法：描述需具体，例如：

"next_action": "将quality-score.py集成到pr-pipeline的第3阶段。函数签名为score_package(path) -> ScoreResult。集成点位于STAGE和REVIEW阶段之间的网关检查处。"

Anti-Pattern 2: Skipping context_notes

反模式2：跳过context_notes

What it looks like:

"context_notes": ""

or omitting the field Why wrong: Context notes capture WHY the session chose its approach — the information most likely to be lost and most expensive to reconstruct. Do instead: Always include at least: what approach was chosen, what was rejected, and any gotchas discovered.

表现：

"context_notes": ""

或省略此字段 为何错误：context_notes捕获了会话选择方案的原因——这是最容易丢失且重建成本最高的信息。 正确做法：至少始终包含：选择的方案、否决的方案，以及发现的陷阱。

Anti-Pattern 3: Using Handoff as Task Plan

反模式3：将交接用作任务计划

What it looks like: Creating detailed phase breakdowns in HANDOFF.json instead of task_plan.md Why wrong: Handoff files are one-shot artifacts deleted after resume. Task plans persist as the task record of truth. Putting plan content in handoff means it vanishes after the next

/resume

. Do instead: Keep task_plan.md for task structure. Use handoff for session-specific reasoning that supplements the plan.

表现：在HANDOFF.json中创建详细的阶段分解，而非写入task_plan.md 为何错误：交接文件是一次性工件，恢复会话后会被删除。任务计划是任务的真实记录，会持久保存。将计划内容放入交接文件意味着恢复会话后这些内容会消失。 正确做法：使用task_plan.md记录任务结构，使用交接文件记录补充计划的会话特定推理内容。

Anti-Pattern 4: Auto-Committing Code Changes

反模式4：自动提交代码变更

What it looks like: Committing uncommitted work as part of the pause flow without user consent Why wrong: Uncommitted changes may be experimental, broken, or intentionally staged for review. Auto-committing removes the user's ability to decide. Do instead: Suggest a WIP commit. Show the files. Let the user decide.

表现：在暂停流程中未经用户同意自动提交未提交工作 为何错误：未提交变更可能是实验性的、有问题的，或是为审核特意暂存的。自动提交会剥夺用户的决定权。 正确做法：建议创建WIP提交，显示涉及的文件，由用户决定。

Anti-Rationalization

反合理化

Rationalization	Why It's Wrong	Required Action
"The task plan captures everything"	task_plan.md captures task state, not session reasoning (approach, rejections, mental model)	Create handoff files with context_notes
"Next session can figure it out from git log"	Git log shows WHAT changed, not WHY or what was rejected	Include decisions and context_notes
"No need for .continue-here.md, JSON is enough"	Humans read prose faster than JSON; .continue-here.md is for manual inspection	Always write both files
"The changes are obvious, no need for detailed next_action"	What's obvious now is opaque after context loss	Write specific next_action with file paths
"I'll just quickly commit the code too"	Auto-committing code without user consent risks committing broken/experimental work	Suggest WIP commit, never auto-commit code

合理化借口	为何错误	要求操作
“任务计划已捕获所有内容”	task_plan.md捕获任务状态，但不捕获会话推理（方案、否决项、思维模型）	创建包含context_notes的交接文件
“下一个会话可以从git log中找到答案”	Git log显示变更了什么，但不显示原因或否决了哪些方案	包含决策和context_notes
“不需要.continue-here.md，JSON就足够了”	人类阅读散文比JSON更快；.continue-here.md用于人工检查	始终同时写入两个文件
“变更很明显，不需要详细的next_action”	现在看来明显的内容，丢失上下文后会变得难以理解	写入包含文件路径的具体next_action
“我顺便把代码也提交了吧”	未经用户同意自动提交代码可能会提交有问题/实验性的工作	建议创建WIP提交，绝不自动提交代码

References

参考

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations

本技能使用以下共享模式：

反合理化 - 防止寻找捷径的合理化借口

pause-work

Original

Translation

/pause - Session Handoff

/pause - 会话交接

Operator Context

操作上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

What This Skill CAN Do

本技能可实现的功能

What This Skill CANNOT Do

本技能不可实现的功能

Instructions

操作步骤

Phase 1: GATHER

阶段1：收集

Current branch

当前分支

Uncommitted files (staged and unstaged)

未提交文件（已暂存和未暂存）

Summary of uncommitted changes

未提交变更摘要

Recent commits on this branch (for context)

当前分支的最近提交（用于上下文）

Get list of modified files

获取修改文件列表

Phase 2: SYNTHESIZE

阶段2：整合

Phase 3: WRITE

阶段3：写入

Continue Here

Continue Here

What I was doing

我正在做什么

What's done

已完成

What's next

下一步

Key decisions

关键决策

Watch out for

需要注意

Uncommitted work

未提交工作

Phase 4: CONFIRM

阶段4：确认

Error Handling

错误处理

Error: Not in a Git Repository

错误：不在Git仓库中

Error: Cannot Determine Session Work

错误：无法确定会话工作内容

Error: HANDOFF.json Already Exists

错误：HANDOFF.json已存在

Anti-Patterns

反模式

Anti-Pattern 1: Vague Next Actions

反模式1：模糊的下一步操作

Anti-Pattern 2: Skipping context_notes

反模式2：跳过context_notes

Anti-Pattern 3: Using Handoff as Task Plan

反模式3：将交接用作任务计划

Anti-Pattern 4: Auto-Committing Code Changes

反模式4：自动提交代码变更

Anti-Rationalization

反合理化

References

参考

Related Skills

相关技能