SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmaintain-workflow-context-save

maintain-workflow-context-save

Office & productivity

View repository

Updated 10-16 10:19

About this skill

Context Save — Save work context

Entry/Exit

  • Entry: Work state in the current session
  • Exit: .claude/checkpoints/ checkpoint file under
  • Points to: On restore → maintain-workflow-context-restore; Continue workflow → build-workflow-execute、verify-workflow-review、ship-workflow-ship etc.
  • Preload: CANON.md、maintain-workflow-context-restore(downstream consumers)
  • Output path: .claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md → On restore, consumed by maintain-workflow-context-restore Consumption

Boundary with automatic feature state

docs/features/<feature>/state.json is automatically maintained by hooks for stage-level recovery: current feature, current stage, last stage document, next command.

/save is not responsible for basic stage continuity. It is responsible for saving what state.json cannot express: why A was chosen over B, important trade-offs, caveats, blocking reasons, non-obvious remaining work.

When not to use

  • The current task has not yet formed a recoverable state or clear checkpoint value
  • The user is only asking to commit, publish, or verify, and does not need to save context
  • The user only needs to know the current feature stage and next command; in this case, first check the feature state prompt from SessionStart
  • When code needs to be modified to "tidy up the state", first return to the corresponding build/verify skill

Hard gate

只读操作。不修改代码，只读 git 状态和写 checkpoint 文件。

Violating this gate = this skill is being misused as an excuse to modify code.

Process

Step 1: Collect git status

Collect the current repository snapshot:

git branch --show-current
git status --short
git diff --stat
git log --oneline -5

No more is needed. The full diff is not needed — statistics are enough to understand the scope of changes.

Step 2: Summarize context

Extract the nine categories of information needed for restoration from the current session:

  1. What is being done — Current progress, which step it stopped at
  2. Current goal — The goal, stopping point, and feature doc to be restored by this checkpoint
  3. git snapshot — branch, status summary, diff stat, recent commits
  4. Progress status — Evidence of done / pending / blocked for each work area
  5. Decisions made — Why A was chosen over B, trade-off points
  6. Verification status — Commands run, results, items not run, and failed items
  7. Remaining work — Which steps are still incomplete
  8. Blockers and next command — Blocked by whom, which stage command should be run next
  9. Handover risks — What the next session is most likely to misjudge

The summary should be concise. A checkpoint is not a work log — it is the minimal information set for restoring context.

Step 3: Write the checkpoint file

Path:.claude/checkpoints/YYYYMMDD-HHMMSS-{title-slug}.md

If the .claude/checkpoints/ directory does not exist, create it first:mkdir -p .claude/checkpoints

Example file name:20260424-143052-refactor-auth-module.md

File format:

Template starting point:templates/maintain/checkpoint.md

---
status: active|paused|blocked
branch: feature/auth-refactor
timestamp: 2026-04-24T14:30:52+08:00
current_objective: migrate auth from session to JWT
next_command: /build
files_modified:
  - src/auth/login.ts
  - src/auth/session.ts
last_commits:
  - a1b2c3d feat: add token signing
---

## Summary

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

## Current Objective

- Goal: 完成 JWT auth migration
- Stop point: refresh token rotation 未完成
- Feature doc: `docs/features/20260424-auth/03-plan.md`

## Git Snapshot

- Branch: feature/auth-refactor
- Status summary: 2 modified files
- Diff stat: +120/-35 across auth files
- Last commits: `a1b2c3d feat: add token signing`

## Progress State

| Area | Status | Evidence |
|------|--------|----------|
| Token signing | done | unit tests passing |
| Refresh token rotation | in_progress | plan task 2 |
| Session cleanup | pending | plan task 3 |

## Decisions Made

- 选 RS256 不选 HS256 — 多服务场景下公钥分发更安全
- access token 有效期 15min，refresh token 7 天

## Validation State

| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| Unit tests | `npm test -- auth` | pass | token signing covered |
| Integration tests | `npm test -- auth.integration` | not_run | blocked until rotation exists |

## Remaining Work

- [ ] Refresh token 轮换逻辑
- [ ] 旧 session 清理迁移
- [ ] 集成测试补全

## Blockers

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

## Next Command

- Recommended command: `/build`
- Why: 继续实现 plan 中的 refresh token rotation
- Preconditions: 当前分支保持 feature/auth-refactor

## Handoff Risks

- 不要删除 `src/auth/legacy.ts`；下个迭代才废弃
- production migration 尚未执行

## Notes

- `src/auth/legacy.ts` 不要删，下个迭代才废弃
- DB migration 已在 staging 跑过，production 还没

YAML frontmatter field descriptions:

Field Type Description
status Enum active(in progress),paused(paused),blocked(Blocking)
branch String Current git branch
timestamp ISO-8601 Save time
current_objective String Target that the current checkpoint is to restore to
next_command String Recommended next-stage command after restoration
files_modified List Files modified but not committed
last_commits List Recent related commits, at least 1 or write none

The eleven Markdown body sections cannot be omitted. Content may be empty (e.g., under ## Notes write 无), but section headings must exist—restoration locates information by heading.

Common Excuses

Excuse Reality Consequence
"I'm not done yet, no need to save" The right time to save is during progress, not at the end. Saving after completion = only results, no decision process. Storing only results, not the process → next session doesn't know why A was chosen → re-discussing decisions already made, wasting 15-30 minutes.
"I'll remember next time" Context windows are limited. Written records span sessions. Memory is unreliable, files are reliable. Relying on memory → after session switch, 70%+ of context details are lost → rebuilding context from scratch > 30 minutes vs restoring from checkpoint < 5 minutes.
"Saving takes too much time" Capturing git state + writing summary < 2 minutes. Re-understanding context > 30 minutes. The 2 minutes saved comes back doubled next session: 30 minutes re-understanding + possibly re-discussing decisions already made.
"Too little content to be worth saving" One line of decision is better than starting from zero. There is no context "too small to be worth saving". Small decisions not saved → next session re-discusses the same decision → 5-10 minutes per re-discussion, accumulating > 30 minutes wasted.

Red Flags — STOP

  • Checkpoint file exceeds 100 lines — too detailed = doesn't belong here. A checkpoint is a restoration index, not a work diary.
  • Modifying code — violates Hard Gate. This skill only reads, does not write (except the checkpoint file).
  • Omitting YAML frontmatter — frontmatter is machine-readable metadata, and restoration depends on it.
  • Omitting core Markdown sections — restoration locates information by heading, missing sections = incomplete restoration.
  • Writing a summary without capturing git state — a checkpoint missing git state cannot verify branch consistency.
  • Not recording validation state or next command — the next session doesn't know whether it can continue or from which stage to continue.

Verification Checklist

  • git state complete (branch, status, diff --stat, log --oneline -5)
  • All eleven Markdown sections present (Summary, Current Objective, Git Snapshot, Progress State, Decisions Made, Validation State, Remaining Work, Blockers, Next Command, Handoff Risks, Notes)
  • Decisions recorded (why A was chosen over B)
  • Validation State records checks run/not run/failed
  • Remaining work listed (actionable to-dos, not vague descriptions)
  • Next Command clearly states the recommended command, reason, and prerequisites
  • Handoff Risks clearly documents the points most likely to be misjudged in the next session
  • YAML frontmatter complete (status, branch, timestamp, current_objective, next_command, files_modified, last_commits)
  • Filename format correct (YYYYMMDD-HHMMSS-{title-slug}.md)
  • Total file lines ≤ 100

Validation failure handling

Failure scenario Handling method
checkpoint exceeds 100 lines Refine the content: remove duplicate descriptions, merge similar entries, and keep only the minimal information set needed for recovery. Do not split into multiple checkpoints.
Core sections have omissions Force completion. For empty sections, write "none", but do not omit section headings — information is located by heading during recovery.
Git status collection fails (non-git repository) Record in frontmatter branch: none, and note in the Markdown body: "non-git repository environment, unable to collect git status".
frontmatter fields incomplete Complete status、branch、timestamp、current_objective、next_command、files_modified、last_commits. Do not omit any item.
Decisions not recorded Force listing at least 1 decision + reason. "No decisions" does not hold — if a choice was made, there is a decision.
Validation State missing Add checks that were run, not run, and failed; if there was no validation, write not_run and the reason.
Next Command missing Choose based on Remaining Work /build、/review、/ship or another clear next step.

Good and bad examples

Good — refined checkpoint

---
status: paused
branch: feature/auth-refactor
timestamp: 2026-04-24T14:30:52+08:00
current_objective: migrate auth from session to JWT
next_command: /build
files_modified:
  - src/auth/login.ts
  - src/auth/session.ts
last_commits:
  - a1b2c3d feat: add token signing
---

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

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

## Git Snapshot
- Branch: feature/auth-refactor
- Status summary: 2 modified files
- Diff stat: +120/-35 across auth files
- Last commits: `a1b2c3d feat: add token signing`

## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| Token signing | done | unit tests passing |
| Refresh token rotation | in_progress | plan task 2 |

## Decisions Made
- 选 RS256 不选 HS256 — 多服务场景下公钥分发更安全
- access token 15min，refresh token 7 天

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

## Remaining Work
- [ ] Refresh token 轮换逻辑
- [ ] 旧 session 清理迁移
- [ ] 集成测试补全

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

## Next Command
- Recommended command: `/build`
- Why: 继续 plan task 2
- Preconditions: 当前分支保持 feature/auth-refactor

## Handoff Risks
- src/auth/legacy.ts 不要删，下个迭代才废弃

## Notes
- src/auth/legacy.ts 不要删，下个迭代才废弃

→ frontmatter complete, all four sections present, decisions have reasons, line count < 50

Bad — overly detailed work diary

## Summary
今天早上 9 点开始，先读了 spec，然后讨论了方案 A 和 B，
花了一个小时比较，然后写了第一个文件的 100 行代码...

→ 问题: 超 100 行 → 不该是日记
→ 问题: 无 YAML frontmatter → 恢复时无法机器定位 branch 和 status
→ 问题: 决策理由缺失 → 下次 session 不知道为什么选 A
→ 问题: 工作时间线无恢复价值 → 只需要当前状态和剩余工作

Output template

---
status: active|paused|blocked
branch: [当前 git 分支]
timestamp: [ISO-8601 保存时刻]
current_objective: [当前目标]
next_command: [/build|/review|/ship|other]
files_modified:
  - [已修改未提交文件1]
  - [已修改未提交文件2]
last_commits:
  - [short-sha message]
---

## Summary
[一句话描述当前进度和停点]

## Current Objective
- Goal:
- Stop point:
- Feature doc:

## Git Snapshot
- Branch:
- Status summary:
- Diff stat:
- Last commits:

## Progress State
| Area | Status | Evidence |
|------|--------|----------|
| | pending / in_progress / done / blocked | |

## Decisions Made
- [决策1] — [理由]
- [决策2] — [理由]

## Validation State
| Check | Command / Evidence | Result | Notes |
|-------|--------------------|--------|-------|
| | | not_run / pass / fail / blocked | |

## Remaining Work
- [ ] [未完成任务1]
- [ ] [未完成任务2]

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

## Next Command
- Recommended command:
- Why:
- Preconditions:

## Handoff Risks
- [下个 session 最容易误判的点]

## Notes
- [注意事项/已知的坑]