checkpoint

name	checkpoint
description	Summarize completed work, update progress tracking in DEV_SPEC.md, and prepare for next iteration. Final stage of dev-workflow pipeline. Use when task implementation and testing is completed, or when user says "完成检查点", "checkpoint", "保存进度", "save progress", "任务完成".
metadata	{"category":"progress-tracking","triggers":"checkpoint, save progress, 完成检查点, 保存进度, 任务完成"}
allowed-tools	Bash(python:*) Bash(git:*) Read Write

Checkpoint & Progress Persistence

This skill handles task completion summarization and progress tracking synchronization. It ensures that completed work is properly documented and the project schedule in DEV_SPEC.md stays up-to-date.

Single Responsibility: Summarize → Persist → Prepare Next

---

When to Use This Skill

• When a task implementation and testing is completed
• When you need to manually update progress in DEV_SPEC.md
• When you want to generate a commit message for completed work
• As the final stage of the dev-workflow pipeline

---

Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│  Step 1           Step 1.5                 Step 2              Step 3      │
│  ────────         ────────                 ────────            ────────     │
│  Summarize   →   User Confirm (WHAT)  →   Persist Progress →  Commit Prep │
│  (Summarize)      (Verify work done)       (Update DEV_SPEC)   (WHETHER)   │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌──────────────────┐
                    │   Tests Passed   │
                    └────────┬─────────┘
                             ▼
                  ┌──────────────────────┐
                  │  Step 1: Summarize   │
                  │  Generate summary    │
                  └────────┬─────────────┘
                           ▼
                  ┌──────────────────────┐
                  │ Step 1.5: User       │
                  │ Confirmation         │
                  │ Wait for user OK     │
                  └────────┬─────────────┘
                           │
                     User OK? ──No──→ Revise summary → Back to Step1
                           │
                       Yes ▼
                  ┌──────────────────────┐
                  │ Step 2: Persist      │
                  │ Progress             │
                  │ Update DEV_SPEC.md   │
                  └────────┬─────────────┘
                           ▼
                  ┌──────────────────────┐
                  │ Step 3: Commit Prep  │
                  │ Generate commit msg  │
                  │ Wait for user OK     │
                  └────────┬─────────────┘
                           │
                     User OK? ──No──→ Skip commit → Flow end
                           │
                       Yes ▼
                  ┌──────────────────────┐
                  │  Execute git commit  │
                  └────────┬─────────────┘
                           ▼
                  ┌──────────────────────┐
                  │   Checkpoint Done  │
                  └──────────────────────┘

---

Step 1: Work Summary

Goal: Generate a clear, structured summary of completed work.

1.1 Collect Information

Gather the following from the current session:

• Task ID: e.g., A3, B1, C5
• Task Name: e.g., "配置加载与校验"
• Files Created/Modified: List all file changes
• Test Results: Pass/fail status and coverage (if available)
• Implementation Iterations: How many test-fix cycles occurred

1.2 Generate Summary Report

Output Format:

────────────────────────────────────────────────────
 TASK COMPLETED: [Task ID] [Task Name]
────────────────────────────────────────────────────

 Files Changed:
  Created:
    - src/xxx/yyy.py
    - tests/unit/test_yyy.py
  Modified:
    - src/xxx/zzz.py

 Test Results:
    - tests/unit/test_yyy.py: 5/5 passed 
    - tests/unit/test_zzz.py: 3/3 passed 
    - Coverage: 85% (if available)

 Iterations: [N] (1 = first try success)

 Spec Reference: DEV_SPEC.md Section [X.Y]
────────────────────────────────────────────────────

---

Step 1.5: User Confirmation (Verify WHAT Was Done)

Goal: Present summary to user for verification before persisting progress.

This confirms WHAT work was completed - validating the summary accuracy, not whether to save it.

1.5.1 Confirmation Prompt

Output Format:

════════════════════════════════════════════════════
 Please Verify Completion Summary / 请验证工作总结
════════════════════════════════════════════════════

 Task: [Task ID] [Task Name]
 Spec Reference: DEV_SPEC.md Section [X.Y]

 Files Changed:
  Created:
    - src/xxx/yyy.py
    - tests/unit/test_yyy.py
  Modified:
    - src/xxx/zzz.py

 Test Results:
    - tests/unit/test_yyy.py: 5/5 passed 
    - tests/unit/test_zzz.py: 3/3 passed 

 Iterations: [N]

════════════════════════════════════════════════════
 Is this summary accurate?
 以上总结是否准确？

   Please reply: "confirm" / "确认" to save progress to DEV_SPEC.md
                "revise" / "修改" to regenerate summary
                
 Note: This only verifies the summary. DEV_SPEC.md will be updated
 after confirmation. Git commit decision comes later.
════════════════════════════════════════════════════

1.5.2 Handle User Response

User Response	Action
"confirm" / "yes" / "确认" / "是"	Proceed to Step 2
"revise" / "no" / "修改" / "否"	Ask user what needs to be corrected, then regenerate summary

Important: Do NOT proceed to Step 2 until user explicitly confirms.

---

Step 2: Persist Progress

Goal: Update DEV_SPEC.md to mark the task as completed.

Auto-Execute: This step runs automatically after Step 1.5 user confirmation. No additional user input required.

2.1 Locate Task in DEV_SPEC.md

1. Read DEV_SPEC.md (the GLOBAL file, NOT chapter files)
2. Find the task by its identifier pattern:
   • Look for ### [Task ID]：[Task Name] (e.g., ### A3：配置加载与校验)
   • Or look for checkbox pattern: - [ ] [Task ID] [Task Name]

2.2 Update Progress Marker

Supported Marker Styles:

Before	After	Style
[ ]	[x]	Checkbox
``	``	Emoji
### A3：任务名	### A3：任务名	Title suffix
(进行中)	(已完成)	Chinese status
(In Progress)	(Completed)	English status

Update Logic:

# Pseudo-code for update logic
if task_line contains "[ ]":
    replace "[ ]" with "[x]"
elif task_line contains "":
    replace "" with ""
elif task_line contains "(进行中)" or "(In Progress)":
    replace with "(已完成)" or "(Completed)"
else:
    append " " to task title

2.3 Step 2 Output Format

Output after updating DEV_SPEC.md:

────────────────────────────────────
DEV_SPEC.md Progress Updated
────────────────────────────────────
Task: [Task ID] [Task Name]
Status: [ ] -> [x]
────────────────────────────────────

---

Step 3: Commit Preparation

Goal: Generate structured commit message and ask user whether to commit.

3.1 Commit Message Template

Subject Format:

<type>(<scope>): [Phase X.Y] <brief description>

Template Definition:

Field	Description	Example
<type>	Commit type (see table below)	feat, fix, test
<scope>	Module/component name	config, retriever, pipeline
[Phase X.Y]	DEV_SPEC phase number	[Phase 2.3], [Phase A3]
<brief description>	What was done (< 50 chars)	implement config loader

Commit Type Guidelines:

Change Type	Commit Prefix
New feature	feat:
Bug fix	fix:
Refactoring	refactor:
Tests only	test:
Documentation	docs:
Configuration	chore:

3.2 Generate Commit Message

Output Format:

════════════════════════════════════════════════════
 COMMIT MESSAGE / 提交信息
════════════════════════════════════════════════════

【Subject】
feat(<module>): [Phase X.Y] implement <feature name>

【Description】
Completed DEV_SPEC.md Phase X.Y: <Task Name>

Changes:
- Added <component 1> implementation
- Added <component 2> implementation
- Added unit tests test_xxx.py

Testing:
- Command: pytest tests/unit/test_xxx.py -v
- Results: X/X passed 
- Coverage: XX% (if available)

Refs: DEV_SPEC.md Section X.Y
Task: [Task ID] <Task Name>

════════════════════════════════════════════════════

3.3 User Commit Confirmation (Decide WHETHER to Commit)

This confirms WHETHER to commit - deciding if changes should be committed to git now or manually later.

Prompt User:

────────────────────────────────────
 Do you want me to commit these changes?
 是否需要帮您执行 git commit？
────────────────────────────────────

Please reply / 请回复:
  "yes" / "commit" / "是" → Execute git add + git commit
  "no" / "skip" / "否"   → End flow, you can commit manually later
────────────────────────────────────

3.4 Execute Commit (If Confirmed)

If user confirms:

# Stage all changed files
git add <list of changed files>

# Commit with generated message
git commit -m "<subject>" -m "<description>"

Success Output:

────────────────────────────────────
 COMMIT SUCCESSFUL
────────────────────────────────────
Commit: <short hash>
Branch: <current branch>

Progress saved, task [Task ID] completed!
进度已保存，任务 [Task ID] 已完成！
────────────────────────────────────

3.5 Skip Commit (If Declined)

If user declines:

────────────────────────────────────
 WORKFLOW COMPLETED (No Commit)
────────────────────────────────────
 DEV_SPEC.md updated
 Git commit skipped

You can manually commit later with:
  git add .
  git commit -m "<subject>" -m "<description>"

Task [Task ID] checkpoint completed!
任务 [Task ID] 检查点完成！
────────────────────────────────────

---

Quick Commands

User Says	Behavior
"checkpoint" / "完成检查点"	Full workflow (Step 1-3) with confirmations
"save progress" / "保存进度"	Step 1.5-2 only (confirm + persist)
"commit message" / "生成提交信息"	Step 3 only (generate commit message)
"commit for me" / "帮我提交"	Step 3 + execute git commit

---

Important Rules

1. Always Update GLOBAL DEV_SPEC.md: This is the single source of truth for progress tracking.

2. Preserve Existing Format: Match the marker style already used in the document (checkbox vs emoji vs text).

3. Atomic Updates: Update ONE task at a time. Don't batch-update multiple tasks.

4. Two User Confirmations Required:

   • Step 1.5: User must confirm work summary before persisting
   • Step 3.3: User must confirm before git commit
   • NEVER skip these confirmations!

5. Traceability: Every checkpoint must reference the specific spec section that defined the task.

---