# Progress Tracking

> 追踪项目进度和处理阻塞时使用。适用于项目执行阶段、定期状态汇报、阻塞升级。优先使用任务状态机 + 三级阻塞升级 + 进度摘要格式。

- Skill: `zhaoxuya520/progress-tracking` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zhaoxuya520/progress-tracking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaoxuya520/progress-tracking/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaoxuya520 (https://skillmd.com/u/zhaoxuya520)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhaoxuya520/progress-tracking

---


# 进度追踪与阻塞处理

## 适用场景

- 项目执行阶段的状态追踪
- 定期向用户汇报进度
- 阻塞发生时的升级处理
- 任务失败的恢复策略

## 任务状态机

每个任务在生命周期中经历以下状态：

```text
┌─────────────────────────────────────────────────────┐
│                                                       │
│  todo → in_progress → review → done                  │
│    ↓        ↓              ↓                          │
│  skipped  blocked        rework → in_progress        │
│              ↓                                        │
│           waiting_human                              │
│              ↓                                        │
│           in_progress                                │
│                                                       │
└─────────────────────────────────────────────────────┘
```

### 状态定义

```text
todo          - 未开始，等待依赖完成
in_progress   - 正在执行
blocked       - 被外部因素阻塞（依赖未完成、工具不可用）
waiting_human - 需要人工介入（审批、确认、提供材料）
review        - 执行完成，等待验收
rework        - 验收未通过，需要返工
done          - 验收通过，任务完成
skipped       - 经评估后跳过（需说明原因）
```

### 状态流转规则

```text
1. 只有依赖全部 done 的任务才能进入 in_progress
2. blocked 必须标注阻塞原因和预期解除时间
3. waiting_human 必须标注等待谁、等待什么、超时策略
4. review 失败后进入 rework，不能直接标 done
5. skipped 必须记录原因，且不能跳过门禁任务
```

## 阻塞升级策略

```text
L1（自动解决，5 分钟内）：
  - 工具暂时不可用 → 重试或换工具
  - 上游产物小问题 → 自动修复后继续
  - 处理：项目经理工作流自己解决，不打扰用户

L2（协调解决，15 分钟内）：
  - 工作流间产物不匹配 → 协调双方对齐
  - 依赖延迟但有替代路径 → 调整计划
  - 处理：项目经理协调相关工作流，简短通知用户

L3（人工介入，立即升级）：
  - 需求不清无法继续 → 请求用户澄清
  - 外部依赖完全不可用 → 通知用户等待
  - 安全/合规问题 → 暂停并请求授权
  - 处理：通知用户后等待响应，不可继续
```

## 进度摘要格式

```markdown
## 进度摘要 [日期/时间]

### 整体状态：🟢 正常 / 🟡 有风险 / 🔴 阻塞

### 完成情况

- 已完成：6 / 总任务数 10
- 当前阶段：开发阶段
- 关键路径状态：正常 / 延迟 N 分钟

### 正在执行

- T4 后端开发 by backend-engineer — 预计还需 15 分钟
- T5 前端开发 by frontend-engineer — 预计还需 20 分钟

### 已完成

- T1 PRD 评审 ✅
- T2 API 契约 ✅
- T3 数据库设计 ✅

### 阻塞项

- T6 联调 — 原因：等待 T4 完成 — 影响：关键路径 — 行动：等待
- T7 QA 测试 — 原因：等待 T6 完成 — 影响：关键路径 — 行动：等待

### 风险预警

- R3（QA 测试发现 Bug）— 概率变化：升高（T4 复杂度高于预期）— 建议行动：预留 30min 修复缓冲

### 下一步

- T6 联调（依赖 T4, T5 完成后开始）
- 用户决策点：是否需要在 QA 后增加性能测试？
```

## 失败恢复与回滚

### 任务失败处理

```text
当某个工作流执行失败时：

1. 评估失败类型：
   - 可重试失败（网络超时、工具暂时不可用）→ 自动重试（最多 2 次）
   - 逻辑失败（代码编译错误、测试不通过）→ 进入 rework
   - 不可恢复失败（依赖永久不可用）→ 升级到人工

2. 评估影响范围：
   - 只影响当前任务 → 局部处理
   - 影响下游任务 → 通知下游暂停
   - 影响关键路径 → 触发计划调整

3. 恢复策略：
   - 从最近的成功检查点恢复
   - 不要从头重跑整个流程
   - 保留失败日志用于复盘
```

### 项目级回滚

```text
当项目需要整体回滚时（如上线后发现严重问题）：

1. 立即止血：回滚到上一个稳定版本
2. 保留现场：保存所有日志和状态
3. 定位问题：哪个工作流的产出有问题
4. 评估修复成本：修复 vs 重做
5. 更新计划：加入修复任务和重新验证
6. 复盘：为什么门禁没有拦住这个问题
```

## 工作流程

```text
1. 项目执行中：
   - 实时维护任务状态机
   - 每个里程碑节点输出进度摘要
   ↓
2. 检测到异常：
   - 状态变 blocked → 应用阻塞升级策略
   - 验收失败 → 进入 rework
   - 任务失败 → 应用失败恢复
   ↓
3. 重要节点（每个里程碑）：
   - 输出进度摘要给用户
   - 检查关键路径是否延迟
   - 检查风险触发条件
   ↓
4. 项目结束：
   - 生成最终进度报告
   - 沉淀到 retrospective
```

## 质量自检

```text
□ 每个任务是否有明确状态（不是"做了一些"）
□ blocked 任务是否标注了原因和预期解除时间
□ 进度摘要是否包含关键路径状态
□ 阻塞是否按 L1/L2/L3 升级
□ 失败任务是否记录了原因和恢复路径
□ 用户是否能从摘要中知道项目健康度
```

## 常见坑

1. **状态只有"进行中"和"完成"**——缺少 blocked/rework/waiting_human 等中间状态
2. **阻塞后沉默**——不主动升级，等用户问才说
3. **进度摘要没有数字**——只有"还在做"
4. **关键路径状态不明确**——不知道是否会延期
5. **失败后从头重跑**——浪费已完成的工作
6. **不区分阻塞等级**——L1 也升级到用户，L3 自己硬撑
7. **预期解除时间不写**——blocked 不知道要等多久

## 配套模板

- `templates/status-report-template.md` — 进度摘要 + 阻塞报告 + 任务状态追踪模板

## 与其他 skill 的协作

```text
上游：
  wbs-decomposition → 任务列表
  critical-path → 关键路径
  milestone-gate → 里程碑节点

平行：
  risk-management → 监控风险触发条件
  change-control → 处理变更带来的状态变化

下游：
  retrospective → 复盘进度问题
  dora-metrics → 度量交付效能
```