recovery

Recovery Skill

Recovery Skill - 用于在上下文丢失、会话中断或发生错误后恢复工作流的工作流恢复协议。负责重建状态、恢复制品并无缝继续工作流。 - 上下文窗口耗尽后恢复工作流 - 从会话中断中恢复 - 根据制品和门控文件重建工作流状态 - 找出最后完成的步骤并从此处继续 - 防止恢复过程中重复工作

使用时机

• 工作流进行到一半时上下文窗口耗尽
• 会话中断或丢失
• 需要从最后完成的步骤继续
• 需要重建工作流状态

步骤 1：找出最后完成的步骤

1. 检查门控文件，找出最近一次成功验证：

   • 位置：.claude/context/history/gates/{workflow_id}/
   • 找出 validation_status: "pass" 的最高步骤编号
   • 这是最后成功完成的步骤

2. 查看推理文件，了解进度：

   • 位置：.claude/context/history/reasoning/{workflow_id}/
   • 读取截至最后完成步骤的推理文件
   • 提取上下文和已作出的决策

3. 找出已创建的制品：

   • 检查制品注册表：.claude/context/artifacts/registry-{workflow_id}.json
   • 列出截至最后一步创建的所有制品
   • 确认制品文件存在

步骤 2：加载计划文档

1. 读取计划文档（无状态）：

   • 从制品注册表加载 plan-{workflow_id}.json
   • 提取当前工作流状态
   • 找出已完成和待处理的任务

2. 加载相关阶段计划（如为多阶段）：

   • 检查项目是否为多阶段（是否超过 phase_size_max_lines 阈值）
   • 加载活动阶段计划：plan-{workflow_id}-phase-{n}.json
   • 了解阶段边界和依赖关系

3. 了解当前状态：

   • 将已完成的任务映射到计划
   • 找出后续步骤
   • 检查依赖关系

步骤 3：恢复上下文

1. 加载最后完成步骤的制品：

   • 读取制品注册表
   • 加载所有 validation_status: "pass" 的制品
   • 验证制品完整性

2. 读取推理文件以恢复上下文：

   • 加载已完成步骤的推理文件
   • 提取关键决策和上下文
   • 了解工作流进展

3. 重建工作流状态：

   • 综合计划、制品和推理
   • 创建恢复状态文档
   • 验证状态一致性

步骤 4：恢复执行

1. 从下一步继续：

   • 找出最后完成步骤之后的下一步
   • 从计划中加载步骤要求
   • 为下一步准备输入

2. 规划器更新计划状态（无状态）：

   • 使用当前状态更新 plan-{workflow_id}.json
   • 标记已完成的步骤
   • 更新进度跟踪

3. 编排器协调后续 Agent：

   • 将恢复的制品传递给下一步
   • 恢复工作流执行
   • 监控是否发生其他中断

</execution_process>

失败分类

任务失败时，请对失败类型进行分类：

失败类型	表现	恢复操作
BROKEN_BUILD	构建错误、语法错误、找不到模块	回滚 + 修复
VERIFICATION_FAILED	测试失败、验证错误、断言错误	修复后重试（最多 3 次）
CIRCULAR_FIX	同一错误出现 3 次以上、反复采用类似方法	跳过或升级处理
CONTEXT_EXHAUSTED	达到令牌上限、超过最大长度	压缩上下文并继续
UNKNOWN	不符合任何模式	重试一次，然后升级处理

循环修复检测

铁律：如果同一种方法已尝试 3 次以上且未成功，请立即停止。

检测到循环修复时：

1. 停止当前方法
2. 记录已尝试的内容（方法、错误、文件）
3. 尝试根本不同的方法（使用不同的库、不同的模式、更简单的实现）
4. 如果仍然失败，请升级处理，寻求人类介入

检测算法：

• 从当前方法中提取关键词（排除停用词）
• 与最近 3 次尝试中的关键词进行比较
• 如果 2 次以上尝试的 Jaccard 相似度 > 30%，则标记为循环

示例：

Attempt 1: "Using async await for fetch"
Attempt 2: "Using async/await with try-catch"
Attempt 3: "Trying async await pattern again"
=> CIRCULAR FIX DETECTED - Stop and try callback pattern instead

尝试次数阈值

失败类型	最大尝试次数	后续操作
VERIFICATION_FAILED	3	跳过 + 升级处理
UNKNOWN	2	升级处理
BROKEN_BUILD	1	回滚（如果存在良好的提交）
CIRCULAR_FIX	0	立即跳过

参考资料

详细模式见 references/：

• failure-types.md - 失败分类详情和指标
• recovery-actions.md - 恢复操作决策树和执行步骤
• merge-strategies.md - 多 Agent 场景下的文件合并策略

<best_practices>

恢复验证清单

• 正确识别最后完成的步骤
• 已加载并验证计划文档
• 已完成步骤的所有产物均可用
• 已查看推理文件以获取上下文
• 已准确重建工作流状态
• 不会重复执行工作
• 已准备好下一步所需的输入
• 已将恢复情况记录在推理文件中

</best_practices>

<error_handling>

错误处理

• 缺少计划文档：请求规划器根据需求重新制定计划
• 缺少产物：请求源 Agent 重新创建产物
• 产物损坏：请求重新创建并验证产物
• 推理不完整：使用产物注册表和关卡文件重建状态

</error_handling>

**上下文丢失后的恢复**：

# 1. Check gate files for last completed step
ls .claude/context/history/gates/{workflow_id}/

# 2. Load plan document
cat .claude/context/artifacts/plan-{workflow_id}.json

# 3. Review reasoning files
cat .claude/context/history/reasoning/{workflow_id}/*.json

# 4. Resume from next step

</usage_example>

<usage_example> 自然语言调用：

"Resume the workflow from where we left off"
"Recover the workflow state and continue"
"What was the last completed step?"

</usage_example>

相关内容

• Planner Agent：.claude/agents/core/planner.md
• 记忆文件：.claude/context/memory/

记忆协议（强制）

开始之前：

cat .claude/context/memory/learnings.md

完成之后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假设工作会中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。