todo-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Todo Management

待办事项管理

Overview

概述

todo-management provides systematic task tracking throughout skill development. It manages task states, provides real-time progress updates, identifies blockers, and ensures momentum is maintained from start to finish.

Purpose: Track progress systematically, maintain visibility into work status, identify issues early, and ensure completion.

Value: Prevents work from being forgotten, provides clear progress visibility, enables course correction, and maintains momentum through completion.

When to Use:

After breaking down work with task-development
Throughout skill implementation (continuous tracking)
When coordinating multiple parallel tasks
When reporting progress to stakeholders
When ensuring all work gets completed

todo-management 为技能开发全流程提供系统化的任务跟踪功能。它管理任务状态、提供实时进度更新、识别障碍，并确保从开始到结束始终保持工作推进的动力。

用途：系统化跟踪进度，保持工作状态的可见性，提前识别问题，确保任务完成。

价值：防止工作被遗忘，提供清晰的进度可视化，支持及时调整方向，通过持续推进保持工作动力。

适用场景：

完成 task-development 任务拆分后
技能实现全流程（持续跟踪）
协调多个并行任务时
向利益相关者汇报进度时
确保所有工作都能完成时

Prerequisites

前置条件

Before using todo-management:

Task List: Complete task breakdown from task-development
Clear Objectives: Understanding of what "done" means for each task
Regular Updates: Commitment to updating task status as you work

使用 todo-management 前需满足以下条件：

任务列表：完成 task-development 生成的任务拆分
明确目标：清楚每个任务的“完成”标准
定期更新：承诺在工作过程中及时更新任务状态

Task-Based Operations

基于任务的操作

Operation 1: Initialize Todo List

操作1：初始化待办列表

When to Use: At start of skill development, after task breakdown complete

Process:

Import Task List from task-development
Set Initial State: All tasks to "pending"
Add Metadata: Skill name, start date, estimates
Verify Completeness: All tasks included

Output: Initial todo list ready for tracking

Example:

markdown

undefined

适用场景：技能开发开始时，完成任务拆分后

流程：

从 task-development 导入任务列表
设置初始状态：所有任务设为“pending”
添加元数据：技能名称、开始日期、预估时长
验证完整性：确认所有任务已包含

输出：可用于跟踪的初始待办列表

示例：

markdown

undefined

Todo List: my-skill

待办列表：my-skill

Started: 2025-11-06 Estimate: 12-15 hours

⬜ 1. Create directory (15 min) ⬜ 2. SKILL.md frontmatter (30 min) ⬜ 3. Write Overview (1h) ...

---

开始时间：2025-11-06 预估时长：12-15小时

⬜ 1. 创建目录（15分钟） ⬜ 2. SKILL.md 前置内容（30分钟） ⬜ 3. 撰写概述（1小时） ...

---

Operation 2: Start Task

操作2：启动任务

When to Use: When beginning work on specific task

Process:

Check Dependencies: Prerequisites complete?
Update State: pending → in_progress
Add Timestamp: Note start time
Focus: Only ONE task in_progress at a time

Output: Task marked as in_progress

Example:

markdown

Before: ⬜ 3. Write Overview (1h)
After:  🔄 3. Write Overview (1h) - Started 10:00 AM

Critical Rule: Maximum 1 task in_progress (prevents context switching)

适用场景：开始处理特定任务时

流程：

检查依赖：前置条件是否已完成？
更新状态：pending → in_progress
添加时间戳：记录开始时间
专注工作：同一时间仅能有一个任务处于 in_progress 状态

输出：任务标记为 in_progress

示例：

markdown

更新前：⬜ 3. 撰写概述（1小时）
更新后：🔄 3. 撰写概述（1小时） - 开始于 10:00

关键规则：同一时间最多只能有一个任务处于 in_progress 状态（避免上下文切换）

Operation 3: Complete Task

操作3：完成任务

When to Use: Immediately after finishing task

Process:

Verify Completion: Output exists, quality checked
Update State: in_progress → completed
Record Actual Time: Compare to estimate
Check Next: What's ready now?

Output: Task marked as completed

Example:

markdown

Before: 🔄 3. Write Overview (1h) - Started 10:00 AM
After:  ✅ 3. Write Overview (1h) - Done 10:45 AM (45min actual)

Best Practice: Complete IMMEDIATELY, don't batch updates

适用场景：完成任务后立即执行

流程：

验证完成情况：输出已生成，且通过质量检查
更新状态：in_progress → completed
记录实际时长：与预估时长对比
规划下一步：确定下一个可执行的任务

输出：任务标记为 completed

示例：

markdown

更新前：🔄 3. 撰写概述（1小时） - 开始于 10:00
更新后：✅ 3. 撰写概述（1小时） - 完成于 10:45（实际耗时45分钟）

最佳实践：完成后立即标记，不要批量更新

Operation 4: Report Progress

操作4：汇报进度

When to Use: Daily, at milestones, or when requested

Process:

Calculate Metrics: Completed, in-progress, remaining
Format Report: Status, current work, blockers
Present: Share with team or document

Output: Progress report with metrics

Example:

markdown

Progress Report: my-skill (2025-11-06 14:00)

Overall: 8/20 tasks (40%), 6h spent, ~9h remaining

Completed Today:
- ✅ Directory structure
- ✅ SKILL.md frontmatter
- ✅ Overview
- ✅ Prerequisites

Currently: 🔄 Step 1 (1.5h est, 30min elapsed)

Next Up:
- Step 2
- Step 3

Blockers: None
Status: On track (ahead 30min)

适用场景：每日汇报、里程碑节点或按需汇报

流程：

计算指标：已完成、进行中、剩余任务数量
格式化报告：包含状态、当前工作内容、障碍
提交报告：分享给团队或存档

输出：带指标的进度报告

示例：

markdown

进度报告：my-skill（2025-11-06 14:00）

整体进度：20项任务完成8项（40%），已耗时6小时，剩余约9小时

今日完成：
- ✅ 目录结构
- ✅ SKILL.md 前置内容
- ✅ 概述
- ✅ 前置条件

当前进行中：🔄 步骤1（预估1.5小时，已耗时30分钟）

下一步计划：
- 步骤2
- 步骤3

障碍：无
状态：按计划推进（提前30分钟）

Operation 5: Identify Blockers

操作5：识别障碍

When to Use: When task cannot proceed or takes >>20% longer

Process:

Recognize Blocker: Cannot start/complete task
Document: What's blocked, what's the blocker, who can unblock
Take Action: Request help, switch tasks, escalate

Output: Blocker documented and addressed

Example:

markdown

BLOCKER: Task 7 - API integration guide
Issue: API documentation not available
Impact: 1 task blocked, 2 downstream affected (~5h work)
Action: Requested from API team, ETA Friday
Workaround: Working on independent tasks meanwhile

Blocker Types:

Hard: Cannot proceed at all
Soft: Can proceed but inefficiently
Waiting: External dependency

适用场景：任务无法推进或耗时远超预估20%以上时

流程：

识别障碍：无法启动/完成任务
记录信息：受阻任务、障碍内容、可协助解决的人员
采取行动：请求帮助、切换任务、升级问题

输出：障碍已记录并得到处理

示例：

markdown

障碍：任务7 - API集成指南
问题：API文档不可用
影响：1项任务受阻，2项下游任务受影响（约5小时工作量）
行动：已向API团队请求文档，预计周五提供
临时方案：同时处理独立任务

障碍类型：

硬障碍：完全无法推进
软障碍：可推进但效率极低
等待型障碍：依赖外部资源

Operation 6: Update Estimates

操作6：更新预估时长

When to Use: When actual time differs significantly from estimated (>20%)

Process:

Compare Actual vs Estimated: Calculate variance
Identify Pattern: All tasks or specific type?
Adjust Remaining: Apply calibration factor
Communicate: Update completion timeline

Output: Revised estimates reflecting reality

Example:

markdown

Original: 12-15h total
Actual (5 tasks): 7h vs 5.5h est (27% over)
Analysis: Writing tasks taking longer
Adjustment: 1.3x multiplier for remaining writing
Updated: 15-18h total (vs 12-15h)
New completion: Friday vs Thursday

适用场景：实际耗时与预估时长差异显著（超过20%）时

流程：

对比实际与预估：计算差异率
识别规律：是所有任务还是特定类型任务存在差异？
调整剩余预估：应用校准系数
同步信息：更新完成时间线

输出：基于实际情况修订后的预估时长

示例：

markdown

初始预估：总耗时12-15小时
实际情况（5项任务）：耗时7小时 vs 预估5.5小时（超出27%）
分析：撰写类任务耗时更长
调整：剩余撰写任务预估乘以1.3倍
更新后：总耗时15-18小时（原12-15小时）
新完成时间：周五（原周四）

Operation 7: Handle Task Changes

操作7：处理任务变更

When to Use: Scope changes, new tasks discovered, tasks obsolete

Process:

Document Change: What, why, impact
Update List: Add/remove/modify tasks
Recalculate: New estimate, critical path

Output: Updated todo list

Example - Add Task:

markdown

Added: 8a. Create advanced-patterns.md (3h)
Reason: Users need advanced examples
Impact: +3h (now 15-18h total)

Example - Remove Task:

markdown

Removed: 12. Create script (4h) - OBSOLETE
Reason: Manual process sufficient
Impact: -4h (now 8-11h total)

适用场景：范围变更、发现新任务、任务过时

流程：

记录变更：变更内容、原因、影响
更新列表：添加/移除/修改任务
重新计算：新的预估时长、关键路径

输出：更新后的待办列表

示例 - 添加任务：

markdown

新增：8a. 创建 advanced-patterns.md（3小时）
原因：用户需要进阶示例
影响：增加3小时（总耗时变为15-18小时）

示例 - 移除任务：

markdown

移除：12. 创建脚本（4小时）- 已过时
原因：手动流程已足够
影响：减少4小时（总耗时变为8-11小时）

Operation 8: Maintain Momentum

操作8：维持工作动力

Task State Model

任务状态模型

The Three Core States

三种核心状态

pending (⬜)

Not yet started
Ready to work on (or waiting for dependencies)
Initial state for all tasks

in_progress (🔄)

Currently being worked on
CRITICAL: Only ONE at a time
Active work happening now

completed (✅)

Finished and verified
Output exists, quality checked
Terminal state (no further changes)

pending（⬜）

尚未开始
可启动（或等待依赖）
所有任务的初始状态

in_progress（🔄）

当前正在处理
关键规则：同一时间仅能有一个
正在进行主动工作

completed（✅）

已完成并验证
输出已生成且通过质量检查
最终状态（无后续变更）

State Transitions

状态转换

pending → in_progress (start work)
in_progress → completed (finish and verify)
in_progress → pending (blocker discovered)

pending → in_progress（启动工作）
in_progress → completed（完成并验证）
in_progress → pending（发现障碍）

Special States (Optional)

特殊状态（可选）

blocked (🚫): Cannot proceed due to obstacle obsolete (⊗): Task no longer needed deferred (⏸): Postponed to later version

blocked（🚫）：因障碍无法推进 obsolete（⊗）：任务不再需要 deferred（⏸）：推迟到后续版本

Progress Tracking Formats

进度跟踪格式

Format 1: Simple Checklist

格式1：简单清单

markdown

undefined

markdown

undefined

My Skill Todos

我的技能待办

Task 1 (30 min)
Task 2 (1h)
Task 3 (2h)

Progress: 1/3 (33%)


**Pros**: Simple, portable
**Cons**: No in-progress state

---

任务1（30分钟）
任务2（1小时）
任务3（2小时）

进度：1/3（33%）


**优点**：简单、易迁移
**缺点**：无进行中状态

---

Format 2: Enhanced with Emoji

格式2：带表情符号的增强版

markdown

undefined

markdown

undefined

My Skill Todos

我的技能待办

⬜ 1. Create directory (15 min) ✅ 2. SKILL.md frontmatter (30 min) - Done 10:30 🔄 3. Write Overview (1h) - Started 10:45 ⬜ 4. Write Step 1 (1.5h)

Progress: 1/4 complete (25%), 1 in progress


**Pros**: Clear states, visual
**Cons**: Need emoji support

---

⬜ 1. 创建目录（15分钟） ✅ 2. SKILL.md 前置内容（30分钟） - 完成于10:30 🔄 3. 撰写概述（1小时） - 启动于10:45 ⬜ 4. 撰写步骤1（1.5小时）

进度：4项任务完成1项（25%），1项进行中


**优点**：状态清晰、可视化
**缺点**：需要支持表情符号

---

Format 3: Table Format

格式3：表格格式

markdown

| # | Task | Est | Status | Actual | Notes |
|---|------|-----|--------|--------|-------|
| 1 | Create dir | 15m | ✅ | 15m | Done |
| 2 | Frontmatter | 30m | ✅ | 25m | Done |
| 3 | Overview | 1h | 🔄 | - | Working |
| 4 | Step 1 | 1.5h | ⬜ | - | Ready |

Progress: 2/4 (50%), Time: 40min / 3.25h

Pros: Structured, tracks actuals Cons: Verbose

markdown

| 序号 | 任务 | 预估时长 | 状态 | 实际时长 | 备注 |
|---|------|-----|--------|--------|-------|
| 1 | 创建目录 | 15m | ✅ | 15m | 已完成 |
| 2 | 前置内容 | 30m | ✅ | 25m | 已完成 |
| 3 | 概述 | 1h | 🔄 | - | 进行中 |
| 4 | 步骤1 | 1.5h | ⬜ | - | 待启动 |

进度：4项完成2项（50%），耗时：40分钟 / 3.25小时

优点：结构化、跟踪实际时长缺点：内容繁琐

Format 4: Grouped by Phase

格式4：按阶段分组

markdown

undefined

markdown

undefined

My Skill Todos

我的技能待办

Phase 1: Initialization ✅

阶段1：初始化 ✅

✅ 1. Create directory (15 min)
✅ 2. SKILL.md frontmatter (30 min)

✅ 1. 创建目录（15分钟）
✅ 2. SKILL.md 前置内容（30分钟）

Phase 2: Core Content 🔄

阶段2：核心内容 🔄

✅ 3. Write Overview (1h)
🔄 4. Write Step 1 (1.5h) - Working
⬜ 5. Write Step 2 (1h)
⬜ 6. Write Step 3 (1h)

✅ 3. 撰写概述（1小时）
🔄 4. 撰写步骤1（1.5小时） - 进行中
⬜ 5. 撰写步骤2（1小时）
⬜ 6. 撰写步骤3（1小时）

Phase 3: References ⬜

阶段3：参考资料 ⬜

⬜ 7. Create ref-1.md (3h)
⬜ 8. Create ref-2.md (2h)

Progress: 3/8 (37.5%), Phase 1 complete


**Pros**: Logical grouping, milestones
**Cons**: More structure

---

⬜ 7. 创建 ref-1.md（3小时）
⬜ 8. 创建 ref-2.md（2小时）

进度：8项完成3项（37.5%），阶段1已完成


**优点**：逻辑分组、里程碑清晰
**缺点**：结构复杂

---

Best Practices

最佳实践

Todo Management Best Practices

待办事项管理最佳实践

Update Immediately
- Mark complete right after finishing
- Don't batch updates
- Update as you work, not end of day
One Task In-Progress
- Focus on single task
- Prevents context switching
- Finish before starting next
Complete Before Moving
- Finish current task first
- "Done" = verified, not "mostly done"
- Avoid 90% complete tasks
Track Actuals
- Record actual time
- Compare to estimates
- Learn for better estimation
Address Blockers Fast
- Don't let blockers sit >1 day
- Document clearly
- Take action immediately
Celebrate Progress
- Acknowledge completed tasks
- Mark milestones visibly
- Maintain momentum with wins

立即更新
- 完成后立即标记
- 不要批量更新
- 工作过程中更新，不要等到一天结束
仅一个进行中任务
- 专注于单个任务
- 避免上下文切换
- 完成当前任务后再启动下一个
完成后再切换
- 先完成当前任务
- “完成”指已验证，而非“基本完成”
- 避免出现90%完成的任务
跟踪实际时长
- 记录实际耗时
- 与预估时长对比
- 学习提升预估准确性
快速处理障碍
- 不要让障碍存在超过1天
- 清晰记录
- 立即采取行动
庆祝进展
- 认可已完成任务
- 清晰标记里程碑
- 通过小胜利维持动力

Common Mistakes

常见错误

Mistake 1: Batching Updates

Problem: Update once per day
Fix: Update immediately as you work

Mistake 2: Multiple In-Progress

Problem: 3-4 tasks marked in-progress
Fix: ONE task in-progress maximum

Mistake 3: Not Completing

Problem: Move to next when "mostly done"
Fix: Complete current before next

Mistake 4: Ignoring Blockers

Problem: Blocked tasks sit for days
Fix: Address within 1 day

Mistake 5: No Actual Tracking

Problem: Can't improve estimates
Fix: Track actuals, compare to estimates

错误1：批量更新

问题：每天更新一次
解决：工作过程中立即更新

错误2：多个进行中任务

问题：3-4个任务标记为进行中
解决：最多仅保留一个进行中任务

错误3：未完全完成就切换

问题：“基本完成”就切换到下一个任务
解决：完成当前任务后再启动新任务

错误4：忽略障碍

问题：受阻任务停滞数天
解决：1天内处理障碍

错误5：不跟踪实际时长

问题：无法提升预估准确性
解决：跟踪实际时长并与预估对比

Integration with Other Skills

与其他技能的集成

With task-development

与 task-development 集成

Flow: task-development → todo-management

task-development creates task list → todo-management tracks progress

流程：task-development → todo-management

task-development 生成任务列表 → todo-management 跟踪进度

With planning-architect

与 planning-architect 集成

Flow: planning-architect → task-development → todo-management

Plan estimate → Tasks with estimates → Track to completion

流程：planning-architect → task-development → todo-management

计划预估 → 带预估的任务列表 → 跟踪至完成

With momentum-keeper

与 momentum-keeper 集成

Flow: todo-management ← monitors ← momentum-keeper

momentum-keeper checks for stuck tasks, declining velocity

流程：todo-management ← 监控 ← momentum-keeper

momentum-keeper 检查停滞任务和速度下降情况

Quick Start

快速开始

5-Minute Setup

5分钟设置

Step 1: Get task list (from task-development)

Step 2: Create initial todos

markdown

undefined

步骤1：获取任务列表（来自 task-development）

步骤2：创建初始待办列表

markdown

undefined

Todo: my-skill

待办：my-skill

⬜ 1. Task one (30 min) ⬜ 2. Task two (1h) ⬜ 3. Task three (2h)


**Step 3**: Start first task
```markdown
🔄 1. Task one (30 min) - Started
⬜ 2. Task two (1h)
⬜ 3. Task three (2h)

Step 4: Complete and continue

markdown

✅ 1. Task one (30 min) - Done!
🔄 2. Task two (1h) - Started
⬜ 3. Task three (2h)

⬜ 1. 任务一（30分钟） ⬜ 2. 任务二（1小时） ⬜ 3. 任务三（2小时）


**步骤3**：启动第一个任务
```markdown
🔄 1. 任务一（30分钟） - 已启动
⬜ 2. 任务二（1小时）
⬜ 3. 任务三（2小时）

步骤4：完成任务并继续

markdown

✅ 1. 任务一（30分钟） - 已完成！
🔄 2. 任务二（1小时） - 已启动
⬜ 3. 任务三（2小时）

Examples

示例

Example 1: Simple Skill (5 tasks)

示例1：简单技能（5项任务）

markdown

undefined

markdown

undefined

Todo: calculator-skill

待办：calculator-skill

Started: 2025-11-06 09:00 Estimate: 3 hours

✅ 1. Create directory (15 min) - Done 09:15 ✅ 2. SKILL.md frontmatter (20 min) - Done 09:35 🔄 3. Write operations (1.5h) - Started 09:35 ⬜ 4. Write examples (45 min) ⬜ 5. Validate (15 min)

Progress: 2/5 (40%), 35min / 3h, On track

---

启动时间：2025-11-06 09:00 预估时长：3小时

✅ 1. 创建目录（15分钟） - 完成于09:15 ✅ 2. SKILL.md 前置内容（20分钟） - 完成于09:35 🔄 3. 撰写操作说明（1.5小时） - 启动于09:35 ⬜ 4. 撰写示例（45分钟） ⬜ 5. 验证（15分钟）

进度：5项完成2项（40%），耗时35分钟 / 3小时，按计划推进

---

Example 2: With Blocker

示例2：带障碍场景

markdown

undefined

markdown

undefined

Todo: medical-integration

待办：medical-integration

✅ 1-6: Completed (6h) 🚫 7. FHIR integration guide (3h) - BLOCKED ⬜ 8-15: Pending

Blocker: FHIR API docs not available Impact: 3 tasks affected (~5h work) Action: Requested docs, ETA Friday Workaround: Working on tasks 8-11 (independent)

---

✅ 1-6：已完成（6小时） 🚫 7. FHIR集成指南（3小时） - 受阻 ⬜ 8-15：待启动

障碍：FHIR API文档不可用影响：3项任务受影响（约5小时工作量）行动：已请求文档，预计周五提供临时方案：处理任务8-11（独立任务）

---

References

参考资料

Detailed guides for specific aspects:

State Management Guide - Comprehensive guide to task states, transitions, special states, validation rules
Progress Reporting Guide - Reporting formats, metrics calculation, visualization techniques, communication strategies

各细分领域的详细指南：

状态管理指南 - 任务状态、转换、特殊状态、验证规则的全面指南
进度汇报指南 - 汇报格式、指标计算、可视化技巧、沟通策略

Automation

自动化

Use the todo management script:

bash

undefined

使用待办事项管理脚本：

bash

undefined

Initialize from task list

从任务列表初始化

python scripts/update-todos.py --init task-list.md

Start task

启动任务

python scripts/update-todos.py --start 5

Complete task

完成任务

python scripts/update-todos.py --complete 5

Progress report

生成进度报告

python scripts/update-todos.py --report

Mark blocker

标记障碍

python scripts/update-todos.py --blocker 7 "Waiting for docs"

---

python scripts/update-todos.py --blocker 7 "等待文档"

---

Success Criteria

成功标准

Effective todo management:

✅ Regular Updates - Tasks updated immediately ✅ Clear Visibility - Progress at a glance ✅ Momentum Maintained - ≥1 task completed per session ✅ Realistic Tracking - Estimates updated based on actuals ✅ Completion Achieved - All tasks eventually completed

有效的待办事项管理需满足：

✅ 定期更新 - 任务完成后立即更新 ✅ 清晰可见 - 一眼即可了解进度 ✅ 动力维持 - 每次工作会话至少完成1项任务 ✅ 真实跟踪 - 根据实际情况更新预估 ✅ 全部完成 - 最终所有任务都已完成

Quick Reference

快速参考

The 8 Todo Operations

8项待办操作

Operation	Purpose	When to Use	Time
Initialize	Create todo list from tasks	Start of project	10-20m
Start Task	Mark task in progress	Beginning work on task	1-2m
Complete Task	Mark task done	Finishing task	1-2m
Report Progress	Generate progress report	Status updates, check-ins	5-10m
Identify Blockers	Mark blocked tasks	When task stuck	2-5m
Update Estimates	Adjust time estimates	Learning from actuals	10-15m
Handle Changes	Add/remove/modify tasks	Requirements change	5-15m
Maintain Momentum	Ensure continuous progress	Keeping work moving	Ongoing

All operations are independent - use as needed throughout development

操作	用途	适用场景	耗时
初始化	从任务列表创建待办列表	项目启动时	10-20分钟
启动任务	标记任务为进行中	开始处理任务时	1-2分钟
完成任务	标记任务为已完成	完成任务时	1-2分钟
汇报进度	生成进度报告	状态更新、检查时	5-10分钟
识别障碍	标记受阻任务	任务停滞时	2-5分钟
更新预估	调整时长预估	根据实际情况学习时	10-15分钟
处理变更	添加/移除/修改任务	需求变更时	5-15分钟
维持动力	确保持续推进	保持工作节奏时	持续进行

所有操作相互独立 - 开发过程中按需使用

Task States

任务状态

State	Symbol	Meaning	Transition To
pending	⬜	Not yet started	in_progress
in_progress	🔄	Currently working on	completed
completed	✅	Finished successfully	-
blocked	🚫	Stuck, waiting	in_progress (when unblocked)
deferred	⏸	Postponed	pending or in_progress
obsolete	⊗	No longer needed	-

Critical Rule: Only ONE task in_progress at a time (prevents context switching)

状态	符号	含义	可转换至
pending	⬜	尚未开始	in_progress
in_progress	🔄	当前处理中	completed
completed	✅	成功完成	-
blocked	🚫	停滞、等待	in_progress（障碍解决后）
deferred	⏸	推迟	pending 或 in_progress
obsolete	⊗	不再需要	-

关键规则：同一时间仅能有一个 in_progress 任务（避免上下文切换）

Common Commands (Script)

常用命令（脚本）

bash

undefined

bash

undefined

Initialize from task list

从任务列表初始化

python scripts/update-todos.py --init task-list.md

Start task #5

启动任务5

python scripts/update-todos.py --start 5

Complete task #5

完成任务5

python scripts/update-todos.py --complete 5

Mark task #7 as blocked

标记任务7为受阻

python scripts/update-todos.py --blocker 7 "Waiting for API docs"

python scripts/update-todos.py --blocker 7 "等待API文档"

Generate progress report

生成进度报告

python scripts/update-todos.py --report

Update estimate for task #3

更新任务3的预估时长

python scripts/update-todos.py --update-estimate 3 "2h"

Add new task

添加新任务

python scripts/update-todos.py --add "Validate new feature" "1h" "Phase 4"

undefined

python scripts/update-todos.py --add "验证新功能" "1h" "阶段4"

undefined

Progress Metrics

进度指标

Completion Rate:

Completed / Total × 100%

Velocity:

Completed tasks / Time elapsed

Estimated Remaining:

Sum of remaining task estimates

Burn Rate:

Time spent / Total estimated time × 100%

On Track?: Burn rate ≈ Completion rate (±10%)

完成率：

已完成任务数 / 总任务数 × 100%

交付速度：

已完成任务数 / 耗时

剩余预估时长：

剩余任务预估时长总和

消耗率：

已耗时 / 总预估时长 × 100%

是否按计划推进？：消耗率 ≈ 完成率（±10%）

Best Practices Quick List

最佳实践速查

✅ Update immediately (not in batches)
✅ One in_progress (no context switching)
✅ Mark blockers (visibility of issues)
✅ Complete before new (finish current task first)
✅ Update estimates (learn and improve)
✅ Report regularly (track progress)
✅ Handle changes (adapt to new requirements)
✅ Maintain momentum (≥1 completed per session)

✅ 立即更新（不批量）
✅ 仅一个进行中任务（无上下文切换）
✅ 标记障碍（问题可见）
✅ 完成后再启动新任务（先结束当前）
✅ 更新预估（学习提升）
✅ 定期汇报（跟踪进度）
✅ 处理变更（适应新需求）
✅ 维持动力（每次会话至少完成1项）

State Transition Diagram

状态转换图

pending ──start──> in_progress ──complete──> completed
   ↑                    ↓
   └────────────────blocked
                        ↓
                    deferred

pending ──启动──> in_progress ──完成──> completed
   ↑                    ↓
   └────────────────受阻
                        ↓
                    推迟

Troubleshooting Quick Fixes

故障排除快速修复

Problem	Quick Fix
Multiple in_progress	Complete or defer all but one
Stalled progress	Identify blockers, seek help
Estimates way off	Update remaining estimates
Too many tasks	Defer low-priority tasks
Losing momentum	Complete quick wins

问题	快速修复
多个进行中任务	完成或推迟其他任务，仅保留一个
进度停滞	识别障碍，寻求帮助
预估偏差大	更新剩余任务预估
任务过多	推迟低优先级任务
动力不足	完成快速小任务