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

code

┌─────────────────────────────────────────────────────────────────────────────┐
│  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:

code

────────────────────────────────────────────────────
 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:

code

════════════════════════════════════════════════════
 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

•Read DEV_SPEC.md (the GLOBAL file, NOT chapter files)
•
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:

python

# 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.2.1 Update Overall Progress Table (总体进度)

CRITICAL: After updating the individual task status, you MUST also update the 📈 总体进度表.

Location in DEV_SPEC.md: Look for section ### 📈 总体进度 or ### Overall Progress

What to Update:

•已完成 (Completed Count): Increment by 1 for the task's phase
•进度 (Progress %): Recalculate as (已完成 / 总任务数) × 100%

Example:

markdown

Before:
| 阶段 A | 3 | 2 | 67% |

After (when A3 completed):
| 阶段 A | 3 | 3 | 100% |

2.3 Step 2 Output Format

Output after updating DEV_SPEC.md:

code

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

Step 3: Commit Preparation

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

3.1 Commit Message Template

Subject Format:

code

<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:

code

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

【Subject】
feat(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:

code

────────────────────────────────────
 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:

bash

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

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

Success Output:

code

────────────────────────────────────
 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:

code

────────────────────────────────────
 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

•
Always Update GLOBAL DEV_SPEC.md: This is the single source of truth for progress tracking.
•
Preserve Existing Format: Match the marker style already used in the document (checkbox vs emoji vs text).
•
Atomic Updates: Update ONE task at a time. Don't batch-update multiple tasks.
•
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!
•
Update Both Progress Markers: When marking a task complete, update both the individual task status and the 📈 总体进度表 (aggregate counts).
•
Traceability: Every checkpoint must reference the specific spec section that defined the task.