track-session

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session Progress

会话进度

🔄 Session tracking activated - I'll use SESSION_PROGRESS.md to track our work so we can pause and resume anytime.

🔄 会话跟踪已激活 - 我将使用SESSION_PROGRESS.md来跟踪我们的工作，以便随时暂停和恢复。

Overview

概述

Use SESSION_PROGRESS.md in the project root to track plans and progress. All planned work should be saved to SESSION_PROGRESS.md and updated over time. If the plan changes, update SESSION_PROGRESS.

Core principle: Maintain recoverable state so work can pause and resume without losing context.

使用项目根目录下的SESSION_PROGRESS.md来跟踪计划和进度。所有规划的工作都应保存到SESSION_PROGRESS.md中，并随时间更新。如果计划变更，需同步更新SESSION_PROGRESS.md。

核心原则： 可恢复状态维护，确保工作暂停和恢复时不会丢失上下文。

Usage Modes

使用模式

This skill supports four modes via optional arguments:

Mode	Command	What it does	Use when
Default	`/track-session`	Save progress, then continue working	Checkpoint during active work
Save	`/track-session save`	Save progress and stop	Pausing work or taking a break
Resume	`/track-session resume`	Load SESSION_PROGRESS.md and continue	Starting new session after break
Verify	`/track-session verify`	Validate completed work against requirements	Before declaring done or delivery

该技能通过可选参数支持四种模式：

模式	命令	功能	使用场景
默认模式	`/track-session`	保存进度后继续工作	活跃工作期间创建检查点
保存模式	`/track-session save`	保存进度并停止工作	暂停工作或休息时
恢复模式	`/track-session resume`	加载SESSION_PROGRESS.md并继续工作	休息后开启新会话时
验证模式	`/track-session verify`	根据需求验证已完成的工作	宣布任务完成或交付前

When to Use

适用场景

Always use when:

Working on multi-phase implementations
Planning complex refactoring across multiple files
Pairing with user on design decisions
Tasks that might span multiple sessions or context resets
Long-running debugging sessions with multiple approaches

Useful for:

Feature development with dependencies between tasks
Large refactoring projects
Learning new codebases with exploration notes
Collaborative work sessions with progress tracking

Avoid when:

Quick 1-2 file changes
Simple bug fixes with obvious solutions
Read-only exploration without planned changes
Tasks that complete in under 5 minutes

必须使用的场景：

处理多阶段实现任务
规划跨多个文件的复杂重构
与用户协作进行设计决策
可能跨多个会话或上下文重置的任务
包含多种方案的长时间调试会话

适用场景：

存在任务依赖的功能开发
大型重构项目
记录新代码库的探索笔记
带进度跟踪的协作工作会话

避免使用的场景：

快速的1-2个文件修改
解决方案明确的简单bug修复
无计划变更的只读探索
5分钟内可完成的任务

When to Update

更新时机

Update after:

Completing any checklist item
Any change in plan
Any error or failed attempt
Every 2-3 file modifications
Before asking user questions

在以下情况后更新：

完成任一清单项
计划发生任何变更
出现任何错误或尝试失败
每修改2-3个文件后
向用户提问前

When to Verify

验证时机

Run verification:

Before declaring work complete
After all planned tasks are checked off
Before final delivery or handoff
When returning to work after a long break (verify nothing regressed)
After major refactoring (verify functionality preserved)
When user asks "are we done?" or "did we finish everything?"

在以下情况执行验证：

宣布工作完成前
所有规划任务勾选完成后
最终交付或交接前
长时间休息后恢复工作时（验证无回退问题）
大型重构后（验证功能保留）
用户询问「我们完成了吗？」或「我们做完所有事了吗？」时

Format

格式

markdown

undefined

markdown

undefined

Session Progress

Plan

Task 1: Description [dependency: none]
Task 2: Description [dependency: Task 1]
Task 3: Description [dependency: Task 2]

Task 1: Description [dependency: none]
Task 2: Description [dependency: Task 1]
Task 3: Description [dependency: Task 2]

Current Status

Last updated: [timestamp] Working on: [current task] Next: [immediate next step]

Failed Attempts

Tried [approach]: Failed because [reason], trying [alternative] instead

Tried [approach]: Failed because [reason], trying [alternative] instead

Completed Work

[timestamp] Task 2: [brief summary of what was done]

[timestamp] Task 2: [brief summary of what was done]

Verification Results

(Added by /track-session verify command)

✅ Successfully Verified

Task/Phase: Evidence of completion and correctness

Task/Phase: Evidence of completion and correctness

⚠️ Minor Issues Found

Issue: Description and impact

Issue: Description and impact

❌ Blocking Issues

Critical problem: What's broken and why it blocks delivery

Critical problem: What's broken and why it blocks delivery

📋 Recommended Next Steps

Specific action to address issues
Next action after that

undefined

Specific action to address issues
Next action after that

undefined

Verification

验证说明

Command:

/track-session verify

Validates completed tasks against original requirements. Checks that work is actually done, requirements met, dependencies satisfied, no scope gaps. Generates report with verified items, minor issues, blockers, and next steps.

See: Detailed Verification Guide for full methodology.

命令：

/track-session verify

根据原始需求验证已完成的任务。检查工作是否实际完成、需求是否满足、依赖是否解决、是否存在范围缺口。生成包含已验证项、次要问题、阻塞点和后续步骤的报告。

参考： 详细验证指南获取完整方法。

Rules

规则

Never repeat failures - Log every failed approach with reason
Resume from checkpoint - Check for existing SESSION_PROGRESS.md at session start
Keep current - File should always reflect actual state
Be specific - Include enough detail to resume work after context loss
Verify before declaring done - Always run
```
/track-session verify
```
before claiming work is complete
Verification is not optional - Checked boxes don't mean work meets requirements; verification does

切勿重复失败 - 记录每一次失败的尝试及原因
从检查点恢复 - 会话开始时检查是否存在SESSION_PROGRESS.md
保持实时更新 - 文件应始终反映实际状态
内容具体 - 包含足够细节，以便上下文丢失后仍可恢复工作
宣布完成前必须验证 - 声明工作完成前务必运行
```
/track-session verify
```
验证不可省略 - 勾选任务不代表工作符合要求，验证才能确认

Examples

示例

Example: Mode Selection

示例：模式选择

<Good> ```bash

Scenario 1: Starting a big feature

场景1：启动大型功能开发

user: "Let's implement user authentication" assistant: "/track-session"

Creates SESSION_PROGRESS.md with plan, then starts working immediately

创建SESSION_PROGRESS.md并记录计划，随即开始工作

Scenario 2: Taking a lunch break

场景2：准备午休

user: "Save my progress, I'll be back in an hour" assistant: "/track-session save"

Saves current state and stops

保存当前状态并停止工作

Scenario 3: Coming back from break

场景3：休息后返回

user: "I'm back, let's continue" assistant: "/track-session resume"

Reads SESSION_PROGRESS.md and continues from checkpoint

读取SESSION_PROGRESS.md并从检查点继续

Scenario 4: Creating checkpoint mid-work

场景4：工作中途创建检查点

assistant: "Completed Phase 2, creating checkpoint before Phase 3" assistant: "/track-session"

Updates SESSION_PROGRESS.md with Phase 2 completion, continues to Phase 3

更新SESSION_PROGRESS.md记录Phase 2完成，继续Phase 3

Scenario 5: Verifying work is complete

场景5：验证工作是否完成

user: "Are we done? Did we complete everything?" assistant: "/track-session verify"

Reads SESSION_PROGRESS.md, checks all completed tasks against requirements

读取SESSION_PROGRESS.md，检查所有已完成任务是否符合要求

Reports: "✅ Phases 1-3 verified. ⚠️ Phase 4 tests not run. Recommend: Run test suite"

报告："✅ Phases 1-3 verified. ⚠️ Phase 4 tests not run. Recommend: Run test suite"

Scenario 6: End of work session verification

场景6：工作会话结束前验证

assistant: "All tasks appear complete. Let me verify before we finish." assistant: "/track-session verify"

Validates all work, generates verification report

验证所有工作，生成验证报告


**Why this is good:** Clear separation of concerns - save for pausing, resume for continuing, no-arg for checkpointing during active work, verify for validation before delivery.
</Good>

<Bad>
```bash


**为何合理：** 职责清晰分离 - 保存用于暂停，恢复用于继续，无参数模式用于活跃工作时创建检查点，验证用于交付前确认。
</Good>

<Bad>
```bash

Always using save even when you want to continue

即使想继续工作也一直使用save

user: "Let's build authentication" assistant: "/track-session save"

Saves and STOPS, now user has to manually ask to resume

保存并停止工作，用户需手动请求恢复

Using resume without a saved session

无已保存会话时使用resume

user: "Start working on the feature" assistant: "/track-session resume"

ERROR: No SESSION_PROGRESS.md exists yet

错误：不存在SESSION_PROGRESS.md

Marking tasks complete without verification

未验证就标记任务完成

assistant: "All tasks are checked off, we're done!"

Never ran verify to confirm work actually meets requirements

从未运行verify确认工作是否符合要求


**Why this is bad:** Using save when you want to continue wastes time. Using resume without prior save fails. Skipping verify means potentially incomplete or incorrect work. Use no-arg mode to save+continue, and always verify before declaring completion.
</Bad>


**为何不合理：** 想继续工作却使用save会浪费时间；无保存会话时使用resume会失败；跳过验证可能导致工作不完整或错误。使用无参数模式保存并继续工作，宣布完成前务必验证。
</Bad>

Example 1: Complex Feature Implementation

示例1：复杂功能实现

<Good> ```markdown

Session Progress

Plan

Phase 1: Research authentication libraries [dependency: none]
- Evaluated OAuth.js, Passport.js, Auth0
- Chose Passport.js for flexibility
Phase 2: Set up OAuth flow [dependency: Phase 1]
- Configured Google OAuth provider
- Added callback routes
Phase 3: Add user session management [dependency: Phase 2]
- Implement Redis session store
- Add session cleanup job
Phase 4: Test authentication flows [dependency: Phase 3]
- Test login/logout
- Test session persistence

Phase 1: Research authentication libraries [dependency: none]
- Evaluated OAuth.js, Passport.js, Auth0
- Chose Passport.js for flexibility
Phase 2: Set up OAuth flow [dependency: Phase 1]
- Configured Google OAuth provider
- Added callback routes
Phase 3: Add user session management [dependency: Phase 2]
- Implement Redis session store
- Add session cleanup job
Phase 4: Test authentication flows [dependency: Phase 3]
- Test login/logout
- Test session persistence

Current Status

Working on: Phase 3 - Implementing Redis session storage Next: Add Redis client configuration, then implement session middleware

Failed Attempts

Tried in-memory sessions: Failed because sessions not persistent across server restarts, switching to Redis instead
Attempted express-session default store: Performance issues with concurrent users, Redis solves this

Tried in-memory sessions: Failed because sessions not persistent across server restarts, switching to Redis instead
Attempted express-session default store: Performance issues with concurrent users, Redis solves this

Completed Work

Phase 2 completed - OAuth flow working with Google provider
Phase 1 completed - Selected Passport.js after comparing 3 libraries


**Why this is good:** Specific tasks with clear dependencies, documented decisions, failed attempts recorded with reasons, concrete next steps.
</Good>

<Bad>
```markdown

Phase 2 completed - OAuth flow working with Google provider
Phase 1 completed - Selected Passport.js after comparing 3 libraries


**为何合理：** 任务具体且依赖关系清晰，记录决策过程，失败尝试及原因明确，后续步骤具体。
</Good>

<Bad>
```markdown

Session Progress

Plan

Do auth stuff
Fix sessions
Test it

Working on auth. Tried some things that didn't work.


**Why this is bad:** Too vague, no dependencies tracked, no details on what failed or why, impossible to resume without starting over.
</Bad>

Do auth stuff
Fix sessions
Test it

Working on auth. Tried some things that didn't work.


**为何不合理：** 过于模糊，未跟踪依赖关系，无失败细节，无法恢复工作只能从头开始。
</Bad>

Example 2: Debugging Session

示例2：调试会话

<Good> ```markdown

Session Progress

Plan

Phase 1: Reproduce bug [dependency: none]
Phase 2: Identify root cause [dependency: Phase 1]
Phase 3: Implement fix [dependency: Phase 2]
Phase 4: Verify fix with tests [dependency: Phase 3]

Phase 1: Reproduce bug [dependency: none]
Phase 2: Identify root cause [dependency: Phase 1]
Phase 3: Implement fix [dependency: Phase 2]
Phase 4: Verify fix with tests [dependency: Phase 3]

Current Status

Working on: Phase 3 - Implementing race condition fix Next: Add mutex lock around shared resource access in payment processor

Failed Attempts

Checked payment API logs: No errors found, bug is client-side
Added try-catch around payment call: Still crashes, race condition suspected
Increased timeout values: Made it worse, confirms race condition hypothesis

Checked payment API logs: No errors found, bug is client-side
Added try-catch around payment call: Still crashes, race condition suspected
Increased timeout values: Made it worse, confirms race condition hypothesis

Completed Work

Phase 2 - Root cause identified: race condition in payment state management
Phase 1 - Bug reproduced consistently with concurrent payment attempts


**Why this is good:** Clear progression through debugging phases, failed attempts inform next steps, root cause documented.
</Good>

<Bad>
```markdown

Phase 2 - Root cause identified: race condition in payment state management
Phase 1 - Bug reproduced consistently with concurrent payment attempts


**为何合理：** 调试阶段进展清晰，失败尝试为后续步骤提供参考，根本原因已记录。
</Good>

<Bad>
```markdown

Session Progress

Debugging payment bug. Tried a few things. Need to fix it.


**Why this is bad:** No systematic approach, no record of what was tried, no hypothesis tracking.
</Bad>

Debugging payment bug. Tried a few things. Need to fix it.


**为何不合理：** 无系统化方法，未记录尝试内容，未跟踪假设。
</Bad>

Example 3: Verification Workflow

示例3：验证工作流

<Good> ```markdown

Session Progress

Plan

Phase 1: Set up authentication system
Phase 2: Implement user registration
Phase 3: Add email verification
Phase 4: Write tests

Phase 1: Set up authentication system
Phase 2: Implement user registration
Phase 3: Add email verification
Phase 4: Write tests

Verification Results

✅ All phases verified with passing tests (23/23) ⚠️ Minor: Email template styling, no rate limiting 📋 Next: Add rate limiting, customize templates


**Why this is good:** Verification report shows evidence (test counts, specific issues), separates critical vs. nice-to-have, provides actionable next steps.
</Good>

<Bad>
```markdown

✅ All phases verified with passing tests (23/23) ⚠️ Minor: Email template styling, no rate limiting 📋 Next: Add rate limiting, customize templates


**为何合理：** 验证报告提供证据（测试数量、具体问题），区分关键与优化项，提供可操作的后续步骤。
</Good>

<Bad>
```markdown

Plan

Phase 1: Authentication
Phase 2: Registration
Phase 3: Email stuff
Phase 4: Tests

Everything is done! ✨


**Why this is bad:** No verification performed, no evidence work meets requirements, potentially incomplete work.
</Bad>

Phase 1: Authentication
Phase 2: Registration
Phase 3: Email stuff
Phase 4: Tests

Everything is done! ✨


**为何不合理：** 未执行验证，无证据证明工作符合要求，可能存在不完整工作。
</Bad>

Troubleshooting

故障排除

Problem: SESSION_PROGRESS.md getting too large (>1000 lines)

问题：SESSION_PROGRESS.md过大（超过1000行）

Cause: Not archiving completed work periodically.

Solution:

bash

undefined

原因： 未定期归档已完成工作。

解决方案：

bash

undefined

Archive completed phases to separate file

将已完成阶段归档到单独文件

cat SESSION_PROGRESS.md >> SESSION_ARCHIVE_2025-01.md

Keep only active phases in SESSION_PROGRESS.md

在SESSION_PROGRESS.md中仅保留活跃阶段


Move completed work to archive file monthly or after major milestones.


每月或重大里程碑后将已完成工作移至归档文件。

Problem: Lost track of what was being worked on

问题：忘记当前正在处理的内容

Cause: Didn't update "Current Status" before pausing session.

Solution:

Update SESSION_PROGRESS.md before asking user questions
Update before context resets
Update every 2-3 file modifications
Set reminder: "Last updated" timestamp should be recent

原因： 暂停会话前未更新「当前状态」。

解决方案：

向用户提问前更新SESSION_PROGRESS.md
上下文重置前更新
每修改2-3个文件后更新
设置提醒：「最后更新」时间戳应保持最新

Problem: Can't resume work after long break

问题：长时间休息后无法恢复工作

Cause: Not enough detail in "Next" field.

Solution: Include specific next action with file and function names:

markdown

Next: Add mutex lock in src/payment/processor.ts:handlePayment()
around lines 45-60 where paymentState is accessed

Not just: "Next: Fix the bug"

原因： 「下一步」字段不够详细。

解决方案： 包含具体的下一步操作，包括文件和函数名：

markdown

Next: Add mutex lock in src/payment/processor.ts:handlePayment()
around lines 45-60 where paymentState is accessed

而非仅写：「下一步：修复bug」

Problem: Repeated failed attempts with same approach

问题：重复使用相同方法导致多次失败

Cause: Not reading or updating "Failed Attempts" section.

Solution: Before trying new approach:

Check "Failed Attempts" section
Verify approach is different
Document why this attempt should work
Add failed attempt immediately when it fails

原因： 未查看或更新「失败尝试」部分。

解决方案： 尝试新方法前：

查看「失败尝试」部分
确认新方法不同
记录该尝试为何应该有效
尝试失败后立即添加记录

Problem: Resume fails with "No SESSION_PROGRESS.md found"

问题：恢复时提示「No SESSION_PROGRESS.md found」

Cause: Trying to resume without first saving a session.

Solution:

Use
```
/track-session
```
(no argument) to create initial session
Or use
```
/track-session save
```
to create SESSION_PROGRESS.md first
Resume only works when SESSION_PROGRESS.md already exists

原因： 未先保存会话就尝试恢复。

解决方案：

使用
```
/track-session
```
（无参数）创建初始会话
或先使用
```
/track-session save
```
创建SESSION_PROGRESS.md
仅当SESSION_PROGRESS.md已存在时，恢复模式才有效

Problem: Save mode stops work when you wanted to continue

问题：使用保存模式后停止了工作，但原本想继续

Cause: Using

save

argument instead of no argument.

Solution:

Use
```
/track-session save
```
ONLY when pausing work
Use
```
/track-session
```
(no arg) to checkpoint and continue
Default no-arg mode is for active work with checkpoints

原因： 使用了

save

参数而非无参数模式。

解决方案：

仅在暂停工作时使用
```
/track-session save
```
使用
```
/track-session
```
（无参数）创建检查点并继续工作
默认无参数模式适用于活跃工作时创建检查点

Problem: Unclear which mode to use

问题：不清楚应使用哪种模式

Cause: Not understanding the difference between modes.

Solution: Quick decision guide:

Continuing work? Use no argument (default)
Stopping for a break? Use
```
save
```
Coming back to work? Use
```
resume
```
Think you're done? Use
```
verify
```

原因： 不了解各模式的区别。

解决方案： 快速决策指南：

继续工作？ 使用无参数（默认模式）
休息停止？ 使用
```
save
```
返回工作？ 使用
```
resume
```
认为已完成？ 使用
```
verify
```

Problem: Verify reports work incomplete but all tasks are checked

问题：验证报告显示工作不完整，但所有任务已勾选

Cause: Tasks were marked complete without actually finishing the work, or requirements changed.

Solution:

Review each flagged item in the verification report
Either:
- Complete the missing work and re-verify, OR
- Update SESSION_PROGRESS.md if requirements changed
Never skip verification - checked boxes don't mean work is actually done

原因： 未实际完成工作就标记任务完成，或需求已变更。

解决方案：

查看验证报告中每个标记项
要么：
- 完成缺失工作并重新验证，或
- 若需求变更则更新SESSION_PROGRESS.md
切勿跳过验证 - 勾选任务不代表工作实际完成

Problem: Verify mode takes too long

问题：验证模式耗时过长

Cause: Too many completed tasks to verify at once.

Solution:

Run verify incrementally after each major phase
Don't wait until the end to verify everything
Use
```
/track-session verify
```
after completing each group of related tasks
Archive verified phases to SESSION_ARCHIVE.md to reduce scope

原因： 一次性验证过多已完成任务。

解决方案：

完成每个主要阶段后增量运行验证
不要等到最后才验证所有内容
完成每组相关任务后使用
```
/track-session verify
```
将已验证阶段归档到SESSION_ARCHIVE.md以缩小范围

Problem: Verify passes but work still has bugs

问题：验证通过但工作仍存在bug

Cause: Verification wasn't thorough enough (didn't run tests, check edge cases, etc.)

Solution: Verification should include:

Running test suites (unit, integration, e2e)
Manual testing of key user flows
Checking error handling and edge cases
Validating against original acceptance criteria
Code review of critical changes

原因： 验证不够彻底（未运行测试、检查边缘情况等）。

解决方案： 验证应包括：

运行测试套件（单元、集成、端到端）
关键用户流的手动测试
错误处理和边缘情况检查
根据原始验收标准验证
关键变更的代码审查

Integration

集成

This skill works with:

git-worktree - Each worktree should have its own SESSION_PROGRESS.md for parallel work tracking
All methodology skills - Track phase completion for TDD, debugging, code review workflows
generate-skill - Use SESSION_PROGRESS.md to track multi-phase skill creation
Long-running tasks - Any task requiring >15 minutes or multiple context resets

Integration pattern with git-worktree:

bash

undefined

该技能可与以下工具协作：

git-worktree - 每个工作树应拥有独立的SESSION_PROGRESS.md以跟踪并行工作
所有方法学技能 - 跟踪TDD、调试、代码审查工作流的阶段完成情况
generate-skill - 使用SESSION_PROGRESS.md跟踪多阶段技能创建
长时间运行的任务 - 任何需要15分钟以上或多次上下文重置的任务

与git-worktree的集成模式：

bash

undefined

Create worktree for feature

为功能创建工作树

git worktree add ../project-feature feature-branch cd ../project-feature

Create separate progress tracking

创建独立的进度跟踪

echo "# Session Progress - Feature Branch" > SESSION_PROGRESS.md

Work on feature with independent progress tracking

独立跟踪功能开发进度


**Pairs with:**
- Commit workflows - Track progress between commits
- Testing workflows - Track test implementation phases
- Refactoring - Track refactoring phases and rollback points


**搭配使用：**
- 提交工作流 - 跟踪提交之间的进度
- 测试工作流 - 跟踪测试实现阶段
- 重构 - 跟踪重构阶段和回退点