SuperAPI AI Directory

progress-tracking

General & other

View repository

Updated 10-16 09:31

About this skill

Progress Tracking and Blocker Handling

Applicable Scenarios

  • Status tracking during the project execution phase
  • Regularly reporting progress to the user
  • Escalation handling when blockers occur
  • Recovery strategies for task failures

Task State Machine

Each task goes through the following states during its lifecycle:

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

State Definitions

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

State Transition Rules

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

Blocker Escalation Strategy

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

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

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

Progress Summary Format

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

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

### 完成情况

- 已完成: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 后增加性能测试?

Failure Recovery and Rollback

Task Failure Handling

当某个工作流执行失败时:

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

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

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

Project-Level Rollback

当项目需要整体回滚时(如上线后发现严重问题):

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

Workflow

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

Quality Self-Check

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

Common Pitfalls

  1. States are only "in progress" and "complete"——lacking intermediate states such as blocked/rework/waiting_human
  2. Silence after being blocked——not proactively escalating, only speaking when the user asks
  3. Progress summaries have no numbers——only "still working on it"
  4. Critical path status is unclear——not knowing whether there will be a delay
  5. Rerunning from scratch after failure——wasting completed work
  6. Not distinguishing blocker levels——escalating L1 to the user too, while toughing out L3 alone
  7. Expected resolution time is not written——when blocked, not knowing how long to wait

Supporting Templates

  • templates/status-report-template.md — progress summary + blocker report + task status tracking template

Collaboration with Other Skills

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

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

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