Back to Details

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:
  1. Task List: Complete task breakdown from task-development
  2. Clear Objectives: Understanding of what "done" means for each task
  3. Regular Updates: Commitment to updating task status as you work
使用 todo-management 前需满足以下条件：
  1. 任务列表：完成 task-development 生成的任务拆分
  2. 明确目标：清楚每个任务的“完成”标准
  3. 定期更新：承诺在工作过程中及时更新任务状态

Task-Based Operations

基于任务的操作

Operation 1: Initialize Todo List

操作1：初始化待办列表

When to Use: At start of skill development, after task breakdown complete
Process:
  1. Import Task List from task-development
  2. Set Initial State: All tasks to "pending"
  3. Add Metadata: Skill name, start date, estimates
  4. Verify Completeness: All tasks included
Output: Initial todo list ready for tracking
Example:
markdown
undefined
适用场景：技能开发开始时，完成任务拆分后
流程：
  1. 从 task-development 导入任务列表
  2. 设置初始状态：所有任务设为“pending”
  3. 添加元数据：技能名称、开始日期、预估时长
  4. 验证完整性：确认所有任务已包含
输出：可用于跟踪的初始待办列表
示例：
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:
  1. Check Dependencies: Prerequisites complete?
  2. Update State: pending → in_progress
  3. Add Timestamp: Note start time
  4. 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)
适用场景：开始处理特定任务时
流程：
  1. 检查依赖：前置条件是否已完成？
  2. 更新状态：pending → in_progress
  3. 添加时间戳：记录开始时间
  4. 专注工作：同一时间仅能有一个任务处于 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:
  1. Verify Completion: Output exists, quality checked
  2. Update State: in_progress → completed
  3. Record Actual Time: Compare to estimate
  4. 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
适用场景：完成任务后立即执行
流程：
  1. 验证完成情况：输出已生成，且通过质量检查
  2. 更新状态：in_progress → completed
  3. 记录实际时长：与预估时长对比
  4. 规划下一步：确定下一个可执行的任务
输出：任务标记为 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:
  1. Calculate Metrics: Completed, in-progress, remaining
  2. Format Report: Status, current work, blockers
  3. 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)
适用场景：每日汇报、里程碑节点或按需汇报
流程：
  1. 计算指标：已完成、进行中、剩余任务数量
  2. 格式化报告：包含状态、当前工作内容、障碍
  3. 提交报告：分享给团队或存档
输出：带指标的进度报告
示例：
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:
  1. Recognize Blocker: Cannot start/complete task
  2. Document: What's blocked, what's the blocker, who can unblock
  3. 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%以上时
流程：
  1. 识别障碍：无法启动/完成任务
  2. 记录信息：受阻任务、障碍内容、可协助解决的人员
  3. 采取行动：请求帮助、切换任务、升级问题
输出：障碍已记录并得到处理
示例：
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:
  1. Compare Actual vs Estimated: Calculate variance
  2. Identify Pattern: All tasks or specific type?
  3. Adjust Remaining: Apply calibration factor
  4. 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%）时
流程：
  1. 对比实际与预估：计算差异率
  2. 识别规律：是所有任务还是特定类型任务存在差异？
  3. 调整剩余预估：应用校准系数
  4. 同步信息：更新完成时间线
输出：基于实际情况修订后的预估时长
示例：
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:
  1. Document Change: What, why, impact
  2. Update List: Add/remove/modify tasks
  3. 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)
适用场景：范围变更、发现新任务、任务过时
流程：
  1. 记录变更：变更内容、原因、影响
  2. 更新列表：添加/移除/修改任务
  3. 重新计算：新的预估时长、关键路径
输出：更新后的待办列表
示例 - 添加任务：
markdown
新增：8a. 创建 advanced-patterns.md（3小时）
原因：用户需要进阶示例
影响：增加3小时（总耗时变为15-18小时）
示例 - 移除任务：
markdown
移除：12. 创建脚本（4小时）- 已过时
原因：手动流程已足够
影响：减少4小时（总耗时变为8-11小时）

Operation 8: Maintain Momentum

操作8：维持工作动力

When to Use: Continuously, especially when feeling stuck
Process:
  1. Check Progress: Regular daily review
  2. Identify Killers: Long tasks, blockers, switching, perfectionism
  3. Apply Strategies: Quick wins, timeboxing, skip and return
  4. Celebrate: Mark completions, acknowledge milestones
Momentum Checklist:
  • ≥1 task completed per session?
  • Making progress daily?
  • No tasks stuck >2 days?
  • Blockers addressed <1 day?
  • Focus maintained (1 in-progress)?
When Stuck:
  1. Review completed tasks (see progress!)
  2. Pick smallest pending task (quick win)
  3. Take 15-min break
  4. Ask for help
  5. Switch to different task
When Overwhelmed:
  1. Focus on current task only
  2. Break task down further
  3. Set smaller milestone (next hour)
  4. Remind yourself of MVP
适用场景：持续执行，尤其是感到停滞时
流程：
  1. 检查进度：每日定期回顾
  2. 识别动力杀手：长任务、障碍、上下文切换、完美主义
  3. 应用策略：快速完成小任务、时间盒管理、先跳过后续再处理
  4. 庆祝成果：标记已完成任务，认可里程碑
动力检查清单：
  • 每次工作会话至少完成1项任务？
  • 每日都有进展？
  • 没有任务停滞超过2天？
  • 障碍在1天内得到处理？
  • 保持专注（仅1项进行中任务）？
感到停滞时：
  1. 回顾已完成任务（看到自己的进展！）
  2. 选择最小的待办任务（快速获胜）
  3. 休息15分钟
  4. 请求帮助
  5. 切换到其他任务
感到压力过大时：
  1. 仅专注于当前任务
  2. 将任务进一步拆分
  3. 设置更小的里程碑（下一小时）
  4. 提醒自己关注最小可行产品（MVP）

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

待办事项管理最佳实践

  1. Update Immediately
    • Mark complete right after finishing
    • Don't batch updates
    • Update as you work, not end of day
  2. One Task In-Progress
    • Focus on single task
    • Prevents context switching
    • Finish before starting next
  3. Complete Before Moving
    • Finish current task first
    • "Done" = verified, not "mostly done"
    • Avoid 90% complete tasks
  4. Track Actuals
    • Record actual time
    • Compare to estimates
    • Learn for better estimation
  5. Address Blockers Fast
    • Don't let blockers sit >1 day
    • Document clearly
    • Take action immediately
  6. Celebrate Progress
    • Acknowledge completed tasks
    • Mark milestones visibly
    • Maintain momentum with wins
  1. 立即更新
    • 完成后立即标记
    • 不要批量更新
    • 工作过程中更新，不要等到一天结束
  2. 仅一个进行中任务
    • 专注于单个任务
    • 避免上下文切换
    • 完成当前任务后再启动下一个
  3. 完成后再切换
    • 先完成当前任务
    • “完成”指已验证，而非“基本完成”
    • 避免出现90%完成的任务
  4. 跟踪实际时长
    • 记录实际耗时
    • 与预估时长对比
    • 学习提升预估准确性
  5. 快速处理障碍
    • 不要让障碍存在超过1天
    • 清晰记录
    • 立即采取行动
  6. 庆祝进展
    • 认可已完成任务
    • 清晰标记里程碑
    • 通过小胜利维持动力

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
python scripts/update-todos.py --init task-list.md

Start task

启动任务

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

Complete task

完成任务

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

Progress report

生成进度报告

python scripts/update-todos.py --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项待办操作

OperationPurposeWhen to UseTime
InitializeCreate todo list from tasksStart of project10-20m
Start TaskMark task in progressBeginning work on task1-2m
Complete TaskMark task doneFinishing task1-2m
Report ProgressGenerate progress reportStatus updates, check-ins5-10m
Identify BlockersMark blocked tasksWhen task stuck2-5m
Update EstimatesAdjust time estimatesLearning from actuals10-15m
Handle ChangesAdd/remove/modify tasksRequirements change5-15m
Maintain MomentumEnsure continuous progressKeeping work movingOngoing
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

任务状态

StateSymbolMeaningTransition To
pending⬜Not yet startedin_progress
in_progress🔄Currently working oncompleted
completed✅Finished successfully-
blocked🚫Stuck, waitingin_progress (when unblocked)
deferred⏸Postponedpending 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
python scripts/update-todos.py --init task-list.md

Start task #5

启动任务5

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

Complete task #5

完成任务5

python scripts/update-todos.py --complete 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
python scripts/update-todos.py --report

Update estimate for task #3

更新任务3的预估时长

python scripts/update-todos.py --update-estimate 3 "2h"
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

最佳实践速查

  1. ✅ Update immediately (not in batches)
  2. ✅ One in_progress (no context switching)
  3. ✅ Mark blockers (visibility of issues)
  4. ✅ Complete before new (finish current task first)
  5. ✅ Update estimates (learn and improve)
  6. ✅ Report regularly (track progress)
  7. ✅ Handle changes (adapt to new requirements)
  8. ✅ Maintain momentum (≥1 completed per session)
  1. ✅ 立即更新（不批量）
  2. ✅ 仅一个进行中任务（无上下文切换）
  3. ✅ 标记障碍（问题可见）
  4. ✅ 完成后再启动新任务（先结束当前）
  5. ✅ 更新预估（学习提升）
  6. ✅ 定期汇报（跟踪进度）
  7. ✅ 处理变更（适应新需求）
  8. ✅ 维持动力（每次会话至少完成1项）

State Transition Diagram

状态转换图

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

Troubleshooting Quick Fixes

故障排除快速修复

ProblemQuick Fix
Multiple in_progressComplete or defer all but one
Stalled progressIdentify blockers, seek help
Estimates way offUpdate remaining estimates
Too many tasksDefer low-priority tasks
Losing momentumComplete quick wins
问题快速修复
多个进行中任务完成或推迟其他任务，仅保留一个
进度停滞识别障碍，寻求帮助
预估偏差大更新剩余任务预估
任务过多推迟低优先级任务
动力不足完成快速小任务

For More Information

更多信息

  • State management: references/state-management-guide.md
  • Progress reporting: references/progress-reporting-guide.md
  • Automation: scripts/update-todos.py --help
todo-management is essential for maintaining progress from task list to completed skill. Use it consistently throughout development for successful outcomes.
  • 状态管理：references/state-management-guide.md
  • 进度汇报：references/progress-reporting-guide.md
  • 自动化：scripts/update-todos.py --help
todo-management 是从任务列表到技能完成过程中维持进度的必备工具。开发过程中持续使用可确保成功交付。