Back to Details

resume-work

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/resume - Session State Restoration

/resume - 会话状态恢复

Operator Context

技能背景

This skill reconstructs session state from handoff artifacts so work can continue without wasting time re-reading files and re-discovering decisions. It is the consumer half of the pause/resume pair — 
/pause
creates the artifacts, 
/resume
consumes them.
The priority cascade exists because handoff quality varies:
  1. HANDOFF.json — Best case. Machine-readable, structured, created by explicit 
    /pause
    . Contains reasoning context.
  2. .continue-here.md — Good case. Human-readable prose. May exist without JSON if user wrote it manually.
  3. task_plan.md — Fallback. Records task structure but not session reasoning. Better than nothing.
  4. git log + git status — Last resort. Can infer recent activity but cannot reconstruct reasoning or rejected approaches.
Each level down the cascade loses more context, so the skill always starts from the top.
本技能从交接工件中重建会话状态，让工作可以继续，无需浪费时间重新读取文件和重新梳理决策。它是暂停/恢复配对中的消费端——
/pause
生成工件，
/resume
消费这些工件。
优先级顺序的存在是因为交接的质量参差不齐：
  1. HANDOFF.json —— 最优情况。机器可读的结构化文件，由显式的
    /pause
    命令生成，包含推理上下文。
  2. .continue-here.md —— 良好情况。人类可读的文本。如果用户手动编写，可能会在没有JSON文件的情况下存在。
  3. task_plan.md —— 备选方案。记录任务结构但不包含会话推理，聊胜于无。
  4. git日志 + git状态 —— 最后手段。可以推断近期活动，但无法重建推理过程或被否决的方案。
每往下一个优先级，丢失的上下文就越多，因此本技能始终从最高优先级开始检查。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

  • CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
  • Priority Cascade: Always check sources in order: HANDOFF.json > .continue-here.md > task_plan.md > git log. Never skip to a lower source if a higher one exists, because higher sources contain richer context that would be lost.
  • Stale Handoff Warning: If HANDOFF.json exists and 
    created_at
    is older than 24 hours, warn the user before proceeding. Stale handoffs may describe work that has been superseded by manual changes.
  • One-Shot Consumption: Delete HANDOFF.json and .continue-here.md after successful state reconstruction and user confirmation. These are ephemeral session artifacts, not persistent state. Keeping them risks future 
    /resume
    calls loading outdated context.
  • Status Dashboard: Always present a status summary before taking action. The user needs to confirm the reconstructed state matches reality before the session proceeds — self-assessment of "what I was doing" is inherently fallible.
  • No Destructive Operations: This skill reads and deletes handoff files. It never modifies code, resets git state, or discards uncommitted changes.
  • CLAUDE.md 合规性：执行前读取并遵循仓库中的CLAUDE.md
  • 优先级顺序：始终按以下顺序检查来源：HANDOFF.json > .continue-here.md > task_plan.md > git日志。如果高优先级来源存在，绝不要跳转到低优先级来源，因为高优先级来源包含更丰富的上下文，跳过会导致这些上下文丢失。
  • 过期交接警告：如果HANDOFF.json存在且
    created_at
    早于24小时，在继续操作前向用户发出警告。过期的交接可能描述的工作已被手动更改取代。
  • 一次性消费：成功重建状态并获得用户确认后，删除HANDOFF.json和.continue-here.md。这些是临时的会话工件，不是持久化状态。保留它们可能导致未来的
    /resume
    调用加载过时的上下文。
  • 状态仪表板：执行操作前始终展示状态摘要。在会话继续前，用户需要确认重建的状态与实际情况相符——自我评估“我之前在做什么”本质上容易出错。
  • 无破坏性操作：本技能仅读取和删除交接文件，绝不修改代码、重置Git状态或丢弃未提交的更改。

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

  • Quick Resume Mode: If the user says just "continue" or "resume" with no qualifiers, skip the options menu and immediately execute the 
    next_action
    from the handoff. This optimizes for the common case where the user trusts the handoff and wants to get back to work fast.
  • Uncommitted Work Alert: If handoff reports uncommitted files, verify they still exist and alert if any have been lost (worktree cleanup, manual revert).
  • Route via /do: When executing 
    next_action
    , route through the 
    /do
    system if the action matches a known skill trigger. This ensures proper agent/skill selection for the resumed work.
  • 快速恢复模式：如果用户仅说“continue”或“resume”且无其他限定词，跳过选项菜单，立即执行交接中的
    next_action
    。这针对用户信任交接并希望快速回到工作的常见情况进行了优化。
  • 未提交工作提醒：如果交接报告存在未提交文件，验证这些文件是否仍然存在，若有丢失（工作区清理、手动回滚）则发出警告。
  • 通过/do路由：执行
    next_action
    时，如果操作匹配已知的技能触发词，通过
    /do
    系统路由。这确保为恢复的工作选择合适的Agent/技能。

Optional Behaviors (OFF unless enabled)

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

  • Dry Run (
    --dry-run
    ): Show reconstructed state and planned next action without executing. For reviewing what 
    /resume
    would do.
  • Keep Handoff (
    --keep
    ): Do not delete handoff files after consumption. For debugging or when the user wants to re-resume.
  • 试运行（
    --dry-run
    ）：展示重建的状态和计划的下一个操作，但不执行。用于查看
    /resume
    会执行哪些操作。
  • 保留交接文件（
    --keep
    ）：消费后不删除交接文件。用于调试或用户希望再次恢复的场景。

What This Skill CAN Do

本技能能做什么

  • Read and parse HANDOFF.json for structured state reconstruction
  • Read .continue-here.md for prose-based state reconstruction
  • Fall back to task_plan.md and git log when no handoff files exist
  • Present a status dashboard with completed work, remaining tasks, and next action
  • Route to the next action via /do or direct execution
  • Delete consumed handoff files to prevent stale state
  • 读取和解析HANDOFF.json以进行结构化状态重建
  • 读取.continue-here.md以进行基于文本的状态重建
  • 当无交接文件时，回退到task_plan.md和git日志
  • 展示包含已完成工作、剩余任务和下一个操作的状态仪表板
  • 通过/do或直接执行路由到下一个操作
  • 删除已消费的交接文件以防止状态过期

What This Skill CANNOT Do

本技能不能做什么

  • Create handoff artifacts — that is the 
    pause-work
    skill
  • Recover uncommitted changes that were lost — it can detect the loss but cannot undo it
  • Guarantee state accuracy — reconstructed state is only as good as the handoff that created it
  • Replace task_plan.md — the plan is the persistent record; handoff is the ephemeral session context
  • 创建交接工件——这是
    pause-work
    技能的功能
  • 恢复已丢失的未提交更改——它可以检测到丢失，但无法撤销
  • 保证状态准确性——重建的状态仅与其基于的交接一样准确
  • 替代task_plan.md——计划是持久化记录，交接是临时的会话上下文

Instructions

操作步骤

Phase 1: DISCOVER

阶段1：发现

Goal: Find the best available state source using the priority cascade.
Step 1: Identify project root
bash
git rev-parse --show-toplevel
Step 2: Check for HANDOFF.json (Priority 1)
Look for 
{project_root}/HANDOFF.json
. If found:
  • Read and parse the JSON
  • Check 
    created_at
    timestamp — if older than 24 hours, set 
    stale_warning = true
  • This is the richest source: proceed to Phase 2 with full structured data
  • Also read 
    .continue-here.md
    if it exists (for supplementary prose context)
Step 3: Check for .continue-here.md (Priority 2)
If no HANDOFF.json but 
.continue-here.md
exists:
  • Read the prose content
  • Extract what you can: task description, completed items, next action, decisions
  • Note that reasoning context may be limited compared to JSON handoff
Step 4: Check for task_plan.md (Priority 3)
If neither handoff file exists but 
task_plan.md
exists:
  • Read the plan
  • Extract: completed phases 
    [x]
    , remaining phases 
    [ ]
    , decisions, errors, current status
  • Note: this source captures task structure but not session reasoning
Step 5: Fall back to git reconstruction (Priority 4)
If no handoff files and no task_plan.md:
bash
undefined
目标：使用优先级顺序找到最佳可用状态来源。
步骤1：确定项目根目录
bash
git rev-parse --show-toplevel
步骤2：检查HANDOFF.json（优先级1）
查找
{project_root}/HANDOFF.json
。如果找到：
  • 读取并解析JSON
  • 检查
    created_at
    时间戳——如果早于24小时，设置
    stale_warning = true
  • 这是最丰富的来源：携带完整的结构化数据进入阶段2
  • 如果.continue-here.md存在，同时读取该文件（用于补充文本上下文）
步骤3：检查.continue-here.md（优先级2）
如果没有HANDOFF.json但存在.continue-here.md：
  • 读取文本内容
  • 提取可用信息：任务描述、已完成项、下一个操作、决策
  • 注意：与JSON交接相比，这里可能缺少推理细节
步骤4：检查task_plan.md（优先级3）
如果既没有交接文件也没有task_plan.md：
  • 读取计划
  • 提取：已完成阶段
    [x]
    、剩余阶段
    [ ]
    、决策、错误、当前状态
  • 注意：该来源仅捕获任务结构，不包含会话推理
步骤5：回退到Git重建（优先级4）
如果没有交接文件和task_plan.md：
bash
undefined

Recent activity

近期活动

git log --oneline -20
git log --oneline -20

Current branch context

当前分支上下文

git branch --show-current
git branch --show-current

Uncommitted work

未提交工作

git status --short
git status --short

What's changed

更改内容

git diff --stat

Synthesize a best-effort summary from git state. This is the least precise reconstruction — it shows WHAT happened but not WHY.

**Step 6: Set reconstruction quality indicator**

| Source | Quality | Missing |
|--------|---------|---------|
| HANDOFF.json | Full | Nothing — richest source |
| .continue-here.md | Good | Structured data, may lack reasoning detail |
| task_plan.md | Partial | Session reasoning, rejected approaches, mental model |
| git log | Minimal | All reasoning context, decisions rationale, next action specifics |

**GATE**: At least one state source found and read. If ALL sources are empty (no handoff, no plan, no git history), inform user: "No session state found. Use /do to start a new task."
git diff --stat

从Git状态中合成最佳的总结。这是最不精确的重建方式——它显示了发生了什么，但无法说明原因。

**步骤6：设置重建质量指标**

| 来源 | 质量 | 缺失内容 |
|--------|---------|---------|
| HANDOFF.json | 完整 | 无——最丰富的来源 |
| .continue-here.md | 良好 | 结构化数据，可能缺少推理细节 |
| task_plan.md | 部分 | 会话推理、被否决的方案、思维模型 |
| git日志 | 极少 | 所有推理上下文、决策理由、下一个操作的细节 |

**关卡**：至少找到并读取一个状态来源。如果所有来源都为空（无交接、无计划、无Git历史），告知用户：“未找到会话状态。使用/do启动新任务。”

Phase 2: RECONSTRUCT

阶段2：重建

Goal: Build a coherent state picture from available sources.
Step 1: Verify uncommitted files
If the handoff reports 
uncommitted_files
, check whether they still exist:
bash
undefined
目标：从可用来源构建连贯的状态视图。
步骤1：验证未提交文件
如果交接报告存在
uncommitted_files
，检查这些文件是否仍然存在：
bash
undefined

For each file in uncommitted_files list

针对未提交文件列表中的每个文件

git status --short -- <file>

Flag any files that were listed as uncommitted but are now missing — these represent potential work loss.

**Step 2: Check for false completions**

If the handoff reports `false_completions`, verify those placeholder markers still exist in the codebase. They may have been fixed by manual intervention between sessions.

**Step 3: Synthesize status dashboard**

Build the dashboard from available data:

=================================================================== SESSION RESUMED

Source: HANDOFF.json (created: <timestamp>) [STALE WARNING if applicable] Branch: <branch> (base: <base_branch>)
Task: <task_summary>
Completed:
  • <completed item 1>
  • <completed item 2>
Remaining:
  • <remaining item 1>
  • <remaining item 2>
Blockers: <blockers or "None">
Key Decisions:
  • <decision>: <reasoning>
Uncommitted Work: <N file(s)> [WARNING: N file(s) missing if applicable]
False Completions: <N placeholder(s)> [or "None detected"]
Next Action: <next_action description>
===================================================================

**GATE**: Status dashboard constructed. Ready to present to user.
git status --short -- <file>

标记任何被列为未提交但已丢失的文件——这些代表潜在的工作损失。

**步骤2：检查虚假完成项**

如果交接报告存在`false_completions`，验证这些占位符标记是否仍存在于代码库中。在会话间隔期间，它们可能已被手动修复。

**步骤3：合成状态仪表板**

从可用数据构建仪表板：

=================================================================== 会话已恢复

来源：HANDOFF.json（创建时间：<timestamp>）[如适用则显示过期警告] 分支：<branch>（基准：<base_branch>）
任务：<task_summary>
已完成：
  • <已完成项1>
  • <已完成项2>
剩余：
  • <剩余项1>
  • <剩余项2>
阻塞项：<阻塞项或“无”>
关键决策：
  • <决策>：<推理>
未提交工作：<N>个文件[如适用则显示警告：N个文件丢失]
虚假完成项：<N>个占位符[或“未检测到”]
下一个操作： <next_action描述>
===================================================================

**关卡**：状态仪表板已构建完成，准备展示给用户。

Phase 3: PRESENT

阶段3：展示

Goal: Show the user what was reconstructed and confirm before proceeding.
Step 1: Display status dashboard
Show the dashboard from Phase 2.
Step 2: Handle stale handoff warning
If 
stale_warning
is true:
WARNING: Handoff is from <timestamp> (>24 hours ago).
State may not reflect manual changes made since then.
Proceed with this handoff or discard it? [proceed/discard]
If user discards, fall to next priority level in cascade.
Step 3: Determine action mode
  • Quick resume (user said "continue", "resume", or similar with no qualifiers): Skip options, proceed directly to Phase 4 to execute 
    next_action
  • Review mode (user said "what was I doing", "where did I leave off", or asked a question): Display dashboard only, wait for user to choose what to do next
GATE: User has seen the dashboard. In quick resume mode, proceed to Phase 4. In review mode, wait for user direction.
目标：向用户展示重建的内容并在继续前获得确认。
步骤1：显示状态仪表板
展示阶段2中构建的仪表板。
步骤2：处理过期交接警告
如果
stale_warning
为true：
警告：交接创建于<timestamp>（超过24小时）。
状态可能无法反映此后的手动更改。
是否继续使用此交接或丢弃它？[继续/丢弃]
如果用户选择丢弃，回退到优先级顺序中的下一个来源。
步骤3：确定操作模式
  • 快速恢复（用户说“continue”“resume”或类似无限定词的表述）：跳过选项，直接进入阶段4执行
    next_action
  • 查看模式（用户说“我之前在做什么”“我上次做到哪了”或提出问题）：仅显示仪表板，等待用户选择下一步操作
关卡：用户已查看仪表板。快速恢复模式下进入阶段4，查看模式下等待用户指令。

Phase 4: EXECUTE

阶段4：执行

Goal: Route to the next action and clean up handoff files.
Step 1: Execute next action
Take the 
next_action
from the handoff and execute it:
  • If it matches a skill trigger (e.g., "run tests" -> /vitest-runner), invoke that skill
  • If it describes a code change, proceed with the implementation directly
  • If it requires user input (e.g., "need clarification on threshold"), present the question
Carry forward all context from the handoff: decisions made, approaches rejected, gotchas to avoid. This context should inform the execution, not just the dashboard.
Step 2: Clean up handoff files
After the next action has been initiated (not necessarily completed — just successfully started):
bash
undefined
目标：路由到下一个操作并清理交接文件。
步骤1：执行下一个操作
执行交接中的
next_action
：
  • 如果匹配技能触发词（例如“run tests” -> /vitest-runner），调用该技能
  • 如果描述的是代码更改，直接进行实现
  • 如果需要用户输入（例如“需要明确阈值”），向用户提出问题
从交接中传递所有上下文：已做出的决策、被否决的方案、需要避免的问题。这些上下文应指导执行过程，而不仅仅是用于仪表板。
步骤2：清理交接文件
在下一个操作启动后（不一定完成，只要成功启动即可）：
bash
undefined

Remove one-shot handoff artifacts

删除一次性交接工件

rm -f HANDOFF.json .continue-here.md

If `--keep` flag was provided, skip deletion.

**Step 3: Update task_plan.md if present**

If `task_plan.md` exists, update its status line to reflect that the session has resumed:
Status: Resumed from handoff — executing: <next_action summary>

**GATE**: Next action initiated. Handoff files cleaned up. Session is now in active work mode.

---
rm -f HANDOFF.json .continue-here.md

如果提供了`--keep`参数，跳过删除步骤。

**步骤3：如果存在task_plan.md则更新**

如果task_plan.md存在，更新其状态行以反映会话已恢复：
状态：从交接恢复——正在执行：<next_action摘要>

**关卡**：下一个操作已启动，交接文件已清理。会话现在处于活跃工作模式。

---

Error Handling

错误处理

Error: No State Sources Found

错误：未找到状态来源

Cause: No HANDOFF.json, no .continue-here.md, no task_plan.md, and git log is empty or on a fresh branch Solution: Inform user: "No session state found to resume from. Use /do to start a new task, or describe what you were working on and I'll reconstruct manually."
原因：无HANDOFF.json、无.continue-here.md、无task_plan.md，且Git日志为空或处于新分支 解决方案：告知用户：“未找到可恢复的会话状态。使用/do启动新任务，或描述你之前在做什么，我会手动重建。”

Error: HANDOFF.json Parse Failure

错误：HANDOFF.json解析失败

Cause: HANDOFF.json exists but contains invalid JSON (corrupted, partially written, manually edited badly) Solution: Warn user about the parse error. Fall through to .continue-here.md if it exists, otherwise fall to task_plan.md. Do not silently ignore the error — the user should know their handoff was corrupted.
原因：HANDOFF.json存在但包含无效JSON（损坏、部分写入、手动编辑错误） 解决方案：向用户发出解析错误警告。如果存在.continue-here.md则回退到该文件，否则回退到task_plan.md。不要静默忽略错误——用户应该知道他们的交接已损坏。

Error: Uncommitted Files Missing

错误：未提交文件丢失

Cause: Handoff reports uncommitted files that no longer exist (worktree cleanup, manual deletion, git checkout) Solution: Alert the user with specific file names. These changes are likely lost. The user may need to recreate them — the handoff's 
context_notes
and 
decisions
can help guide reconstruction.
原因：交接报告的未提交文件已不存在（工作区清理、手动删除、Git切换分支） 解决方案：向用户发出包含具体文件名的警告。这些更改可能已丢失。用户可能需要重新创建它们——交接中的
context_notes
和
decisions
可以帮助指导重建。

Error: Stale Handoff Rejected

错误：过期交接被拒绝

Cause: User chose to discard a stale (>24h) handoff Solution: Delete the stale handoff files and fall through to the next priority level in the cascade (task_plan.md or git log). Proceed with the lower-quality reconstruction.
原因：用户选择丢弃过期（超过24小时）的交接 解决方案：删除过期的交接文件，回退到优先级顺序中的下一个来源（task_plan.md或Git日志）。继续使用质量较低的重建结果。

Anti-Patterns

反模式

Anti-Pattern 1: Skipping the Dashboard

反模式1：跳过仪表板

What it looks like: Reading HANDOFF.json and immediately executing next_action without showing the user what was reconstructed Why wrong: Self-assessment of session state is inherently fallible. The user needs to confirm the reconstruction matches reality before the session acts on potentially stale or incorrect assumptions. Do instead: Always show the dashboard. In quick resume mode, show it briefly then proceed — but never skip it entirely.
表现：读取HANDOFF.json后立即执行下一个操作，不向用户展示重建的内容 错误原因：会话状态的自我评估本质上容易出错。在会话基于可能过时或错误的假设采取行动前，用户需要确认重建的状态是否正确。 正确做法：始终展示仪表板。在快速恢复模式下，可以短暂展示后继续，但绝不能完全跳过。

Anti-Pattern 2: Keeping Handoff Files Forever

反模式2：永久保留交接文件

What it looks like: Never deleting HANDOFF.json after consumption, or using 
--keep
by default Why wrong: Stale handoff files cause future 
/resume
calls to load outdated context, potentially overriding the user's actual current state with a previous session's snapshot. Do instead: Delete after successful reconstruction. Use 
--keep
only for debugging.
表现：消费后从不删除HANDOFF.json，或默认使用
--keep
参数 错误原因：过期文件会导致比丢失文件更严重的问题——未来的
/resume
调用可能加载过时的上下文，覆盖用户当前的实际状态。 正确做法：成功重建后删除文件。仅在调试时使用
--keep
。

Anti-Pattern 3: Ignoring Lower-Priority Sources

反模式3：忽略低优先级来源

What it looks like: Finding HANDOFF.json and not checking task_plan.md at all Why wrong: task_plan.md may have been updated manually between sessions. It provides the task structure that supplements the handoff's session reasoning. Do instead: Use HANDOFF.json as primary source but also read task_plan.md if it exists for supplementary context.
表现：找到HANDOFF.json后完全不检查task_plan.md 错误原因：task_plan.md可能在会话间隔期间被手动更新，它提供了补充交接会话推理的任务结构。 正确做法：将HANDOFF.json作为主要来源，但如果task_plan.md存在，也读取它以获取补充上下文。

Anti-Pattern 4: Re-Exploring Rejected Approaches

反模式4：重新尝试被否决的方案

What it looks like: The handoff says "tried X, rejected because Y" but the new session tries X again Why wrong: This is the exact waste handoff was designed to prevent. Re-exploring dead ends burns context on work already done. Do instead: Read 
decisions
and 
context_notes
carefully. Honor previous session's findings unless circumstances have changed.
表现：交接中提到“尝试了X，因Y被否决”，但新会话再次尝试X 错误原因：这正是交接设计要避免的浪费。重新探索死胡同会浪费在已完成工作上的上下文。 正确做法：仔细阅读
decisions
和
context_notes
。除非情况发生变化，否则尊重之前会话的结论。

Anti-Rationalization

反合理化

RationalizationWhy It's WrongRequired Action
"I'll just start fresh, it's faster"Reconstruction from handoff takes seconds; re-discovery takes minutes to hoursCheck handoff files first
"The handoff is stale, I'll ignore it"Stale handoff still contains decisions and rejected approaches worth knowingRead it, warn about staleness, let user decide
"I know what to do, don't need the dashboard"You're a new session — you know nothing yet. The dashboard IS your knowledge.Always display the dashboard
"I'll keep the handoff files just in case"Stale files cause worse problems than missing filesDelete after successful consumption
"The git log tells me everything"Git log shows WHAT changed but not WHY, what was rejected, or what's nextUse handoff files when available; git log is last resort
合理化理由错误原因要求操作
“我直接重新开始更快”从交接重建只需几秒，重新梳理需要几分钟到几小时先检查交接文件
“交接已过期，我忽略它”过期的交接仍然包含值得参考的决策和被否决的方案读取它，发出过期警告，让用户决定
“我知道要做什么，不需要仪表板”你是一个新会话——你一无所知。仪表板就是你的知识。始终显示仪表板
“我保留交接文件以防万一”过期文件导致的问题比丢失文件更严重成功消费后删除
“Git日志告诉我一切”Git日志显示了发生了什么，但无法说明原因、被否决的内容或下一步要做什么有交接文件时使用；Git日志是最后手段

References

参考

This skill uses these shared patterns:
  • Anti-Rationalization - Prevents shortcut rationalizations
本技能使用以下共享模式：
  • 反合理化 - 防止走捷径的合理化理由

Related Skills

相关技能

  • pause-work
    — Creates the handoff artifacts this skill consumes
  • do
    — Routes next_action to appropriate agent/skill for execution
  • workflow-orchestrator
    — For complex multi-phase tasks that benefit from handoff between phases
  • pause-work
    —— 生成本技能消费的交接工件
  • do
    —— 将下一个操作路由到合适的Agent/技能执行
  • workflow-orchestrator
    —— 适用于需要在阶段间交接的复杂多阶段任务",