maintain-workflow-context-restore

Context Restore — Restore work context

Entry/Exit

• Entry: .claude/checkpoints/ checkpoint files under
• Exit: context summary presented to the user
• Points to: after confirmation → continue the original workflow (build / verify / ship, etc.)
• Preload: CANON.md、maintain-workflow-context-save(upstream producer, understands the checkpoint format contract)
• Output path: read .claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md → after restore, continue the corresponding phase skill

Boundary with automatic feature state

A new session will, through docs/features/<feature>/state.json , obtain a phase-level restore hint: current feature, current phase, last phase document, next-step command. This hint is not equal to /restore, and will not automatically start writing code.

/restore is used to restore a decision-rich checkpoint: current goal, git snapshot, progress status, decisions made, verification status, blockers, remaining work, next command, and handoff risks. When you only need to know "how far it got", prefer the feature state hint from SessionStart.

When not to use

• The current session context is complete, and there is no need to restore from a checkpoint
• The user is only asking about historical information and is not preparing to continue previous work
• SessionStart has already provided sufficient feature state, and there is no need to restore decision context
• The source of the checkpoint content is unknown or it clearly does not match the current repo

Hard gate

只读操作。不修改代码。

Starting to write code directly after restoring context = skipping confirmation. You must first present, then confirm, then act.

Process

Step 1: Find checkpoint files

Scan all .claude/checkpoints/ files under .md .

File names start with the YYYYMMDD prefix, which naturally guarantees chronological ordering. Sorting by filename alphabetically is the chronological order.

ls .claude/checkpoints/*.md | sort

Step 2: Select a checkpoint

Default behavior: load the latest one (the last after sorting).

Search by fragment: supports filtering by title keyword.

/restore              → 加载最新 checkpoint
/restore auth         → 搜索文件名包含 "auth" 的最新 checkpoint
/restore list         → 列出最近 20 个 checkpoint（标题 + 时间 + 状态）

Select by number: list output with numbers, specify by number.

Step 3: Present the summary

Read the checkpoint file, extract and present the key information:

📋 Checkpoint: refactor-auth-module
  分支: feature/auth-refactor
  时间: 2026-04-24 14:30
  状态: active
  目标: migrate auth from session to JWT
  下一命令: /build

  Summary: 将登录模块从 session-based 重构为 JWT-based。
           已完成 token 签发，停在 refresh token 轮换逻辑。

  Validation: unit tests pass; integration tests not_run
  Remaining Work:
    - Refresh token 轮换逻辑
    - 旧 session 清理迁移
    - 集成测试补全

  Handoff Risks:
    - 不要删除 src/auth/legacy.ts

Do not expand all content. Present only the minimum information needed to restore decisions. Show the full content only when the user requests it.

Step 4: Branch match check

Get the current git branch and compare it with the checkpoint's branch field:

Case	Handling
Exact match	Continue normally
Mismatch	Issue a warning:⚠️ 当前分支 {current} 与 checkpoint 分支 {saved} 不匹配。确认是否切换分支？
checkpoint has no branch field	Hint:checkpoint 缺少 branch 信息，请手动确认分支是否正确

A branch mismatch does not prevent restore—but it must warn. The user may intentionally continue on another branch.

Also check current_objective、next_command、Validation State、Blockers and Handoff Risks. If missing, it must be marked as a legacy checkpoint, and you must not pretend the restore information is complete.

Step 5: Suggest the next step

After presenting the summary, wait for the user to choose:

1. Continue work — Continue according to the checkpoint's Next Command and Remaining Work
2. View full file — Output the full checkpoint text
3. Ignore — Do not restore; continue from the current state

Make no assumptions. Do not automatically start writing code.

Checkpoint file example

A complete, well-formed checkpoint looks like this:

# .claude/checkpoints/20260425-143000-task-auth.md

---
status: paused
branch: feature/auth-jwt
timestamp: 2026-04-25T14:30:00+08:00
current_objective: implement JWT auth
next_command: /build
files_modified:
  - src/auth/token.ts
last_commits:
  - a1b2c3d feat: add auth middleware
---

## Summary
实现用户认证功能：JWT token 签发 + 验证中间件

## Current Objective
- Goal: 完成 JWT auth
- Stop point: refresh token endpoint 未完成
- Feature doc: `docs/features/20260425-auth/03-plan.md`

## Git Snapshot
- Branch: feature/auth-jwt
- Status summary: 1 modified file
- Diff stat: +80/-10 in auth
- Last commits: `a1b2c3d feat: add auth middleware`

## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| Middleware | done | unit tests pass |
| Refresh token | pending | plan task 3 |

## Decisions Made
- 选择 JWT 而非 session（理由：无状态、横向扩展友好）
- access token 15min + refresh token 7d
- 密码用 bcrypt cost=12

## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| Unit tests | `npm test -- auth` | pass | middleware covered |

## Remaining Work
- [ ] 刷新 token 端点
- [ ] 密码重置流程
- [ ] 集成测试

## Blockers
| Blocker | Owner | Needed Decision / Action |
|---------|-------|--------------------------|
| none | | |

## Next Command
- Recommended command: `/build`
- Why: 继续 refresh token 端点
- Preconditions: branch matches checkpoint

## Handoff Risks
- 不要把 refresh token 存明文

## Notes
- spec 在 docs/features/20260425-auth/01-spec.md
- plan 在 docs/features/20260425-auth/03-plan.md

Checkpoint selection flowchart

查找 checkpoints/
  │
  ├── 找到多个？
  │   ├── YES → 按时间戳排序 → 选最新的
  │   └── NO → 只有一个 → 使用它
  │
  ├── 分支匹配？
  │   ├── YES → 继续
  │   └── NO → 警告用户 → 确认是否继续
  │
  ├── 状态检查
  │   ├── blocked → 先调查阻塞原因
  │   └── active / paused → 呈现恢复摘要
  │
  ├── 恢复合同检查
  │   ├── next_command 存在？ → 用它建议下一步
  │   ├── validation state 存在？ → 告知已验证/未验证
  │   └── handoff risks 存在？ → 高亮风险
  │
  └── 呈现摘要 → 用户确认 → 开始工作

Anti-pattern fix table

Anti-pattern	Fix
Not checking the branch after restoring	You must compare the checkpoint branch with the current branch, and warn if they do not match
Skipping user confirmation and continuing directly	After presenting the summary, you must wait for the human partner to confirm
Restoring a checkpoint with a corrupted format	First check the markdown structure for completeness; if fields are missing, skip it and report
Ignoring Remaining Work after restoring	Remaining Work is the starting point for the work, and it must be confirmed item by item
Ignoring Next Command	Next Command is the stage entry point and must be presented as the recommended recovery path
Ignoring Validation State	You must state which checks have been run and which have not, to avoid false completion
Ignoring Handoff Risks	You must highlight the points most likely to be misjudged in the next session
Restoring multiple checkpoints at the same time	Restore only one. If there are multiple, let the user choose the most relevant one
Forgetting the original work goal after restoring	The Summary is your North Star; review it before every operation
Looking only at code changes and not at decisions	Decisions Made prevents re-discussing already excluded options
Not checking whether relevant files still exist after restoring	Verify referenced paths such as spec/plan, and mark them as stale if missing

Common excuses

Excuse	Reality	Consequence
"Starting from scratch is faster"	Reunderstanding the codebase is 10 times slower than restoring context. Saved decisions and notes are experience bought with money.	Rebuilding context from scratch > 30 minutes vs restoring from a checkpoint < 5 minutes, and you may repeat already excluded options.
"There are too many files"	Only show the most recent 20, and load earlier ones on demand. There is no need to go through the entire history.	Not restoring → discarding decision context → re-discussing the same option next time, wasting 15-30 minutes.
"The previous context is already outdated"	It is not the entire context that is outdated—decision records and notes are usually still valid. Look first, then judge.	Assuming everything is outdated and discarding it directly → valid decisions are also discarded → may reselect already excluded options.
"I remember what I was doing before"	Memory disappears at session boundaries. Are you 100% confident that you remember every decision and note?	Relying on memory → losing 70%+ of details after a session switch → missing key notes causing 4-8 hours of rework.
"Just looking at the code is enough"	The code tells you what was done, not why it was done, what is still missing, or what to watch out for.	Looking only at the code → don't know why A was chosen → might re-choose B which was already ruled out → directional rework cost 10x.
"I'll just start over instead of resuming"	Context restoration saves duplicate work. At least take a look at previous decisions.	Starting over = repeating the previous exploration, discussion, and decision-making process, with total time > 5-10x that of checkpoint restoration.

Red flag — STOP

• Starting to write code directly after restoration — violates the Hard Gate. The context must first be confirmed to still be accurate.
• Ignoring a branch mismatch warning — the code state on different branches can be completely different; forcing continuation = overwriting the wrong foundation.
• Loading a stale blocked checkpoint without asking why — blocked has a reason. Continuing without figuring out why it was blocked will repeat the same mistakes.
• Omitting Remaining Work / Next Command / Validation State when presenting the summary — the user can't judge "what to do next, whether it can continue," and restoration loses its meaning.
• Not checking the checkpoint file format integrity — a checkpoint with a corrupted format may mislead restoration.

Watch for signals from human partners:

• "Where did we get to before?" — you started working without reading the checkpoint
• "Is this new or a continuation of before?" — you didn't confirm the restoration state
• "Why didn't we use option A last time?" — you didn't read Decisions Made
• "How much longer?" — you didn't read Remaining Work to understand the remaining tasks
• "Wasn't this discussed before?" — you didn't restore the previous decision context

All of it means: STOP. Go back and read the checkpoint.

Validation failure handling

Failure scenario	Handling method
Checkpoint file is corrupted or has a format error	Skip that checkpoint, report the error, and try the next most recent checkpoint
Checkpoint branch has been force-pushed	Warn the user that the branch history has been rewritten, and confirm whether to continue
A file referenced by the checkpoint no longer exists	Mark as stale, and prompt the user that they may need to start over
Checkpoint status is blocked	First investigate the blocking cause, then resume work after the blocker is resolved
There are multiple checkpoints for the same task	Choose the newest one. If the newest is in blocked status, choose the newest non-blocked one
All of the checkpoint's Remaining Work has been completed	Report that the task may already be finished, and confirm whether the checkpoint needs to be cleaned up

Validation checklist

• checkpoint file exists in .claude/checkpoints/
• YAML frontmatter is complete (status, branch, timestamp, files_modified)
• All core Markdown sections exist (Summary, Current Objective, Git Snapshot, Progress State, Decisions Made, Validation State, Remaining Work, Blockers, Next Command, Handoff Risks, Notes)
• branch matches or a warning has been issued
• next_command has been presented or marked as legacy missing
• Validation State has been presented, and unrun checks are clearly marked
• Blockers and Handoff Risks have been highlighted
• The user confirms to continue (does not automatically start operations)
• A summary was presented instead of the full text (when the user did not request it)

Good and bad examples

Good — structured recovery

/restore

Step 1: 扫描 checkpoints/ → 找到 3 个文件
Step 2: 选择最新的: 20260424-143052-refactor-auth-module.md
Step 3: 呈现摘要:
  📋 Checkpoint: refactor-auth-module
    分支: feature/auth-refactor
    时间: 2026-04-24 14:30
    状态: paused
    目标: migrate auth from session to JWT
    下一命令: /build
    Validation: unit tests pass; integration tests not_run
    Remaining: refresh token 轮换 + session 清理 + 集成测试
    Risks: 不要删除 src/auth/legacy.ts
Step 4: branch 匹配 ✅ (当前也在 feature/auth-refactor)
Step 5: 等待用户确认

→ 用户确认后按 Remaining Work 继续执行

Bad — writing code directly without confirmation

/restore

（读了 checkpoint，发现停在 refresh token 逻辑）

（直接开始写 refresh token 代码）

→ 问题: 没有呈现摘要 → 用户不知道恢复了什么
→ 问题: 没有检查 branch → 可能在新分支上写旧分支的代码
→ 问题: 没有等用户确认 → 违反 Hard Gate（必须先确认再行动）

Output template

### Context Restore 恢复记录

**Checkpoint**: [文件名]
**分支**: [checkpoint 分支 / 当前分支 / 不匹配警告]
**时间**: [保存时间]
**状态**: [active / paused / blocked]
**目标**: [current_objective]
**下一命令**: [next_command / legacy missing]

**摘要**: [一句话描述当前进度]
**Validation State**: [已跑/未跑/失败检查摘要]
**Blockers**: [阻塞项摘要]
**Remaining Work**: [未完成任务列表]
**关键决策**: [已做决策摘要]
**Handoff Risks**: [下个 session 风险摘要]

**Branch 匹配**: ✓ 匹配 / ⚠ 不匹配 — [当前分支] vs [checkpoint 分支]
**用户确认**: [已确认继续 / 已查看完整文件 / 已忽略]
**下一步**: [按 Remaining Work 继续 / 用户指定方向]