todo-management

待办事项管理

概述

todo-management 在技能开发过程中提供系统化的任务跟踪。它管理任务状态、提供实时进度更新、识别阻碍因素，并确保从开始到结束始终保持推进势头。

目的：系统地跟踪进度，让工作状态清晰可见，及早发现问题，并确保任务完成。

价值：防止遗漏工作，让进度一目了然，便于及时调整方向，并保持推进势头直至完成。

使用时机：

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

前提条件

使用 todo-management 前：

1. 任务列表：完成 task-development 中的任务拆分
2. 明确目标：了解每项任务的“完成”标准
3. 定期更新：承诺在工作过程中更新任务状态

基于任务的操作

操作 1：初始化待办列表

使用时机：技能开发开始时，任务拆分完成后

流程：

1. 导入任务列表，来源为 task-development
2. 设置初始状态：将所有任务设为“pending”
3. 添加元数据：技能名称、开始日期、预估时间
4. 验证完整性：确保包含所有任务

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

示例：

# Todo List: 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)
...

---

操作 2：开始任务

使用时机：开始处理特定任务时

流程：

1. 检查依赖项：前置任务是否已完成？
2. 更新状态：pending → in_progress
3. 添加时间戳：记录开始时间
4. 专注执行：同一时间只有一个任务处于 in_progress 状态

输出：任务标记为 in_progress

示例：

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

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

---

操作 3：完成任务

使用时机：任务完成后立即执行

流程：

1. 验证完成情况：输出已生成，且质量已检查
2. 更新状态：in_progress → completed
3. 记录实际用时：与预估时间比较
4. 检查下一项：现在有哪些任务已就绪？

输出：任务标记为 completed

示例：

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

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

---

操作 4：报告进度

使用时机：每天、达到里程碑时或收到请求时

流程：

1. 计算指标：已完成、进行中、剩余任务
2. 整理报告：状态、当前工作、阻碍因素
3. 提交报告：与团队分享或记录存档

输出：包含指标的进度报告

示例：

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)

---

操作 5：识别阻碍因素

使用时机：任务无法继续，或耗时比预估长 >>20% 时

流程：

1. 识别阻碍：无法开始或完成任务
2. 记录详情：受阻事项、阻碍因素、可协助解除阻碍的人
3. 采取行动：请求帮助、切换任务或升级处理

输出：记录并处理阻碍因素

示例：

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

阻碍类型：

• 硬性阻碍：完全无法继续
• 软性阻碍：可以继续，但效率低下
• 等待：依赖外部条件

---

操作 6：更新预估时间

使用时机：实际用时与预估时间相差较大（>20%）时

流程：

1. 比较实际用时与预估时间：计算偏差
2. 识别模式：是所有任务都如此，还是特定类型的任务？
3. 调整剩余任务：应用校准系数
4. 沟通进展：更新完成时间表

输出：反映实际情况的修订后预估时间

示例：

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

---

操作 7：处理任务变更

使用时机：范围变更、发现新任务或任务已过时

流程：

1. 记录变更：变更内容、原因和影响
2. 更新列表：添加、移除或修改任务
3. 重新计算：新的预估时间和关键路径

输出：更新后的待办列表

示例——添加任务：

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

示例——移除任务：

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

---

操作 8：保持势头

使用时机：持续进行，尤其是在感到停滞时

流程：

1. 检查进度：定期每日回顾
2. 找出阻碍：耗时较长的任务、阻塞因素、频繁切换、完美主义
3. 应用策略：快速取胜、时间盒、先跳过再回来
4. 庆祝：标记已完成的任务，认可里程碑

保持势头检查清单：

• 每次工作时段至少完成 1 项任务？
• 每天都有进展？
• 没有停滞超过 2 天的任务？
• 阻塞因素在 1 天内得到处理？
• 保持专注（1 项进行中任务）？

遇到停滞时：

1. 查看已完成的任务（看看已有的进展！）
2. 选择最小的待处理任务（快速取胜）
3. 休息 15 分钟
4. 寻求帮助
5. 切换到其他任务

感到不堪重负时：

1. 只专注于当前任务
2. 进一步拆分任务
3. 设定更小的里程碑（下一个小时）
4. 提醒自己 MVP 的目标

---

任务状态模型

三种核心状态

pending（⬜）

• 尚未开始
• 可以着手处理（或正在等待依赖项）
• 所有任务的初始状态

in_progress（🔄）

• 当前正在处理
• 关键：同一时间只能有 1 项
• 正在进行中的工作

completed（✅）

• 已完成并经过验证
• 产出已就绪，质量已检查
• 终止状态（不再变更）

状态转换

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

特殊状态（可选）

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

---

进度跟踪格式

格式 1：简单清单

# My Skill Todos

- [ ] Task 1 (30 min)
- [x] Task 2 (1h)
- [ ] Task 3 (2h)

Progress: 1/3 (33%)

优点：简单、便携 缺点：没有进行中状态

---

格式 2：添加表情符号

# 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

优点：状态清晰、直观 缺点：需要支持表情符号

---

格式 3：表格格式

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

优点：结构化，可跟踪实际情况 缺点：内容冗长

---

格式 4：按阶段分组

# My Skill Todos

## Phase 1: Initialization ✅
- ✅ 1. Create directory (15 min)
- ✅ 2. SKILL.md frontmatter (30 min)

## Phase 2: Core Content 🔄
- ✅ 3. Write Overview (1h)
- 🔄 4. Write Step 1 (1.5h) - Working
- ⬜ 5. Write Step 2 (1h)
- ⬜ 6. Write Step 3 (1h)

## Phase 3: References ⬜
- ⬜ 7. Create ref-1.md (3h)
- ⬜ 8. Create ref-2.md (2h)

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

优点：分组合理，包含里程碑 缺点：结构更复杂

---

最佳实践

待办事项管理最佳实践

1. 立即更新

   • 完成后立即标记
   • 不要批量更新
   • 工作时随时更新，不要等到一天结束

2. 一次只处理一项任务

   • 专注于单项任务
   • 避免上下文切换
   • 完成后再开始下一项

3. 完成后再继续

   • 先完成当前任务
   • “完成”意味着经过验证，而不是“基本完成”
   • 避免任务完成度停留在 90%

4. 跟踪实际情况

   • 记录实际耗时
   • 与预估时间比较
   • 从中吸取经验，以便更准确地估算

5. 迅速处理阻塞因素

   • 不要让阻塞因素搁置超过 1 天
   • 清楚记录
   • 立即采取行动

6. 庆祝进展

   • 认可已完成的任务
   • 清楚地标记里程碑
   • 通过取得成果保持势头

常见错误

错误 1：批量更新

• 问题：每天只更新一次
• 修正：工作时立即更新

错误 2：多项任务同时进行

• 问题：标记为进行中的任务有 3–4 项
• 修正：进行中的任务最多只能有 1 项

错误 3：没有完成任务

• 问题：任务“基本完成”时就转到下一项
• 修正：先完成当前任务，再开始下一项

错误 4：忽略阻塞因素

• 问题：受阻任务搁置数日
• 修正：在 1 天内处理

错误 5：不跟踪实际耗时

• 问题：无法改进预估
• 修正：跟踪实际耗时，并与预估比较

---

与其他技能集成

与 task-development 集成

流程：task-development → todo-management

task-development 创建任务清单 → todo-management 跟踪进度

---

与 planning-architect 集成

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

计划预估 → 包含预估时间的任务 → 跟踪直至完成

---

与 momentum-keeper 集成

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

momentum-keeper 检查是否有停滞的任务，以及推进速度是否下降

---

快速开始

5 分钟设置

步骤 1：获取任务清单（来自 task-development）

步骤 2：创建初始待办事项

# Todo: my-skill
⬜ 1. Task one (30 min)
⬜ 2. Task two (1h)
⬜ 3. Task three (2h)

步骤 3：开始第一项任务

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

步骤 4：完成并继续

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

---

示例

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

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

---

示例 2：包含阻塞项

# Todo: 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)

---

参考资料

特定方面的详细指南：

• 状态管理指南 - 关于任务状态、转换、特殊状态和验证规则的综合指南

• 进度报告指南 - 报告格式、指标计算、可视化技巧和沟通策略

---

自动化

使用待办事项管理脚本：

# 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"

---

成功标准

有效的待办事项管理：

✅ 定期更新 - 立即更新任务
✅ 清晰可见 - 一眼了解进度
✅ 保持势头 - 每个会话至少完成 1 个任务
✅ 切合实际地跟踪 - 根据实际情况更新估算
✅ 达成完成 - 最终完成所有任务

---

快速参考

8 项待办操作

操作	用途	使用时机	时间
初始化	根据任务创建待办列表	项目开始时	10-20 分钟
开始任务	将任务标记为进行中	开始处理任务时	1-2 分钟
完成任务	将任务标记为已完成	完成任务时	1-2 分钟
报告进度	生成进度报告	状态更新、签到时	5-10 分钟
识别阻塞项	标记受阻任务	任务卡住时	2-5 分钟
更新估算	调整时间估算	根据实际情况吸取经验时	10-15 分钟
处理变更	添加、移除或修改任务	需求变更时	5-15 分钟
保持势头	确保持续推进	保持工作进展时	持续进行

所有操作彼此独立 - 可在开发过程中按需使用

任务状态

状态	符号	含义	转换为
pending	⬜	尚未开始	in_progress
in_progress	🔄	正在处理	completed
completed	✅	已成功完成	-
blocked	🚫	卡住，正在等待	in_progress（解除阻塞后）
deferred	⏸	已推迟	pending 或 in_progress
obsolete	⊗	不再需要	-

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

常用命令（脚本）

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

# Start task #5
python scripts/update-todos.py --start 5

# Complete task #5
python scripts/update-todos.py --complete 5

# Mark task #7 as blocked
python scripts/update-todos.py --blocker 7 "Waiting for API docs"

# Generate progress report
python scripts/update-todos.py --report

# Update estimate for task #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"

进度指标

完成率：Completed / Total × 100%

速度：Completed tasks / Time elapsed

预计剩余时间：Sum of remaining task estimates

消耗率：Time spent / Total estimated time × 100%

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

最佳实践速查表

1. ✅ 立即更新（不要批量更新）
2. ✅ 仅一个 in_progress 任务（避免上下文切换）
3. ✅ 标记阻塞项（让问题清晰可见）
4. ✅ 完成当前任务再开始新任务（先完成当前任务）
5. ✅ 更新估算（从经验中学习并改进）
6. ✅ 定期报告（跟踪进度）
7. ✅ 处理变更（适应新需求）
8. ✅ 保持势头（每个会话至少完成 1 个任务）

状态转换图

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

常见问题快速修复

问题	快速修复
多个任务处于 in_progress 状态	完成或推迟除一个以外的所有任务
进度停滞	识别阻塞项并寻求帮助
估算偏差过大	更新剩余任务的估算
任务太多	推迟低优先级任务
失去势头	先完成容易快速完成的任务

更多信息

• 状态管理：references/state-management-guide.md
• 进度报告：references/progress-reporting-guide.md
• 自动化：scripts/update-todos.py --help

---

todo-management 对于推动工作从任务列表走向技能完成至关重要。请在开发过程中始终如一地使用它，以取得成功。