action-item-organizer

行动项整理器

此技能提供了一个系统化框架，用于从非结构化文档中提取可执行事项，并将其转换为组织有序、按优先级排列且可跟踪的 Markdown 清单。

何时使用此技能

• 将代码审查报告转换为待办事项清单
• 从会议记录中提取行动项
• 将审计发现整理为整改清单
• 将项目规划文档拆解为任务清单
• 将问题报告整理为可执行的工作项
• 从任何包含内嵌行动项的文档中创建可跟踪的清单
• 按优先级整理团队待办事项
• 创建迭代规划清单

核心原则

1. 提取信息并保留上下文

提取行动项时必须保留足够的上下文，以便任何阅读清单的人都能理解：

• 要做什么
• 为何重要
• 适用于何处（文件、系统、组件）
• 由谁负责
• 应何时完成（优先级和预估时间）

2. 按优先级组织

使用清晰的优先级框架，按紧急程度和影响组织事项：

• P0 / 阻塞项：阻碍进展、部署或合并的关键问题
• P1 / 高优先级：需要及时处理的重大质量、安全或正确性问题
• P2 / 中优先级：有助于改进系统的重要优化和重构
• P3 / 低优先级：未来的优化、细微建议以及锦上添花的改进

在每个优先级内，按逻辑对相关事项分组（例如，将安全事项放在一起，性能事项放在一起）。

3. 为复杂任务建立嵌套结构

将复杂的行动项拆分为分层清单：

• 父级事项表示主要任务或目标
• 子级事项表示具体步骤或子任务
• 孙级事项表示详细的实施步骤

这样可以明确执行路径，并细粒度地跟踪进度。

4. 可追溯性和元数据

维护行动项与其来源之间的关联：

• 文件路径和行号
• 问题或跟踪 ID
• 负责人或责任团队
• 时间预估
• 源文档中的原始上下文

这样可以实现双向追溯，并支持基于充分信息进行优先级排序。

提取工作流

步骤 1：分析文档

1. 阅读完整的源文档
2. 找出包含可执行内容的章节：
   • “行动项”、“待办事项清单”、“建议”
   • “问题”、“发现”、“后续跟进”
   • “下一步”、“任务”、“要求”
3. 理解文档的结构和惯例

步骤 2：识别行动项

提取符合以下条件的事项：

• 可执行：可以完成的具体任务
• 可测试：具有明确的完成标准
• 已分配或可分配：可由个人或团队负责
• 包含上下文：包含足够的信息以理解任务

跳过以下事项：

• 纯信息类内容（除非其中隐含行动要求）
• 已完成事项
• 缺乏额外上下文时含糊不清的事项

步骤 3：提取元数据

对于每个行动项，提取：

必需元数据：

• 任务描述
• 优先级

可选元数据（如有则提取）：

• 文件路径和行号
• 负责人／责任方
• 时间预估
• 问题／跟踪编号
• 类别或领域（安全、性能等）
• 实施步骤或子任务

第 4 步：优先级分类

根据以下标准为每项任务分配优先级：

P0 标准：

• 阻碍部署或合并
• 严重安全漏洞
• 存在数据丢失或损坏风险
• 影响系统可用性
• 违反合规要求

P1 标准：

• 重大安全问题
• 严重影响性能
• 影响功能的正确性问题
• 重要的架构问题
• 高技术债务

P2 标准：

• 代码质量改进
• 中等程度的重构需求
• 测试覆盖率缺口
• 文档需求
• 轻微的性能优化

P3 标准：

• 代码风格与一致性
• 未来增强
• 可有可无的功能
• 轻微优化
• 探索性任务

第 5 步：层级组织

使用嵌套复选框组织任务：

- [ ] **Category: Main task description** (#tracking-id)
  - [ ] Sub-task 1
  - [ ] Sub-task 2
    - [ ] Detailed implementation step
  - **File**: `path/to/file.ext:lines`
  - **Owner**: Team/Person
  - **Estimate**: Time estimate
  - **Context**: Why this matters and what it achieves

第 6 步：生成摘要

针对每个优先级部分，计算：

• 任务总数
• 预计总工时（如有）
• 完成百分比（如需跟踪现有复选框）

第 7 步：输出格式

创建结构化的 Markdown 文档，包含：

1. 标题：标题、生成元数据、来源引用
2. 概览：所有优先级的任务总数和时间
3. 优先级部分：P0、P1、P2、P3 及其摘要
4. 完成情况跟踪：底部的进度指标

复选清单格式规范

基本复选框任务

- [ ] Task description

带元数据的任务

- [ ] **Category: Task description** (#123)
  - **File**: `src/file.js:45-67`
  - **Owner**: Backend Team
  - **Estimate**: 3 hours
  - **Context**: Explanation of why this matters

嵌套子任务

- [ ] **Security: Implement authentication** (#456)
  - [ ] Add session validation
  - [ ] Implement rate limiting
  - [ ] Add authorization checks
  - **File**: `api/auth.ts`
  - **Owner**: Security Team
  - **Estimate**: 8 hours

部分摘要

## P0 - Blockers (Must Fix Before Merge)

**Summary**: 5 items | 12 hours estimated

- [ ] Item 1...
- [ ] Item 2...

完整输出模板

# TODO List

> Generated from: [source-document.md]
> Date: YYYY-MM-DD HH:MM:SS
> Total Items: X | Total Estimated Hours: Y

## P0 - Blockers (Must Fix Before Merge)

**Summary**: N items | M hours estimated

- [ ] **Category: Task description** (#id)
  - [ ] Sub-task
  - **File**: `path/file.ext:lines`
  - **Owner**: Team
  - **Estimate**: X hours
  - **Context**: Why this matters

## P1 - High Priority

**Summary**: N items | M hours estimated

[items...]

## P2 - Medium Priority

**Summary**: N items | M hours estimated

[items...]

## P3 - Low Priority / Future

**Summary**: N items | M hours estimated

[items...]

---

## Completion Tracking

- P0 Blockers: 0/N completed (0%)
- P1 High Priority: 0/M completed (0%)
- P2 Medium Priority: 0/K completed (0%)
- P3 Low Priority: 0/J completed (0%)

**Overall Progress**: 0/X tasks completed (0%)

最佳实践

保留上下文

• 提供足够的细节，让读者理解每项任务为何重要
• 保留原始理由和依据
• 链接相关问题或文档
• 说明未完成任务的影响

逻辑分组

• 在各优先级中对相关任务分组
• 使用类别前缀（安全、性能、测试等）
• 将相互依赖的任务放在一起
• 分组时考虑执行顺序

可执行性

• 每个复选框都应对应一项明确且可完成的操作
• 避免使用“提升性能”等含糊任务
• 使用具体动词：实现、添加、移除、重构、修复
• 适当时加入成功标准

可追溯性

• 始终链接到源文件和行号
• 包含问题或跟踪 ID
• 引用原始文档
• 支持双向导航

完整性

• 确认已包含源中的所有操作项
• 保留嵌套关系
• 提取时不要丢失元数据
• 明确处理边缘情况

处理边缘情况

缺少优先级

• 放在底部的“未分类”部分
• 标记为待审核和确定优先级
• 如可能，根据上下文线索推断

缺少元数据

• 对缺失的预估值使用“TBD”标记
• 注明“文件：TBD”，提示后续调查
• 标记上下文不足的任务

优先级冲突

• 遵从源中明确标注的优先级
• 考虑影响和紧迫性
• 记录优先级分配的依据

现有 TODO 文件

• 覆盖前先确认
• 考虑使用带时间戳的文件名
• 适当时与现有文件合并

多个来源

• 分别处理每个来源
• 或合并成一个带来源标记的清单
• 适当时去重

应避免的反模式

丢失上下文

反例：- [ ] 修复 bug
正例：- [ ] **错误修复：处理用户信息获取时的 null 响应**（#789）

扁平结构

反例：一个复杂任务拆成十个独立任务
正例：一个父任务包含嵌套子任务

缺少可追溯性

反例：没有文件路径或行号
正例：始终包含位置元数据

任务含糊

反例：- [ ] 提升性能
正例：- [ ] **性能：为用户查询添加缓存**——将数据库调用从每个请求 100 次降至 1 次

优先级虚高

反例：所有任务都是 P0
正例：仅将真正的阻塞项列为 P0

示例

示例 1：将代码审查报告转换为 TODO

输入：包含安全问题的代码审查报告

输出：

# TODO List

> Generated from: CODE_REVIEW_REPORT.md
> Date: 2025-12-09 10:30:00
> Total Items: 8 | Total Estimated Hours: 23

## P0 - Blockers (Must Fix Before Merge)

**Summary**: 2 items | 5 hours estimated

- [ ] **Security: Add authentication to token endpoint** (#1)
  - [ ] Implement getServerSession check
  - [ ] Add authorization verification
  - [ ] Add rate limiting (10 req/min per IP)
  - **File**: `app/api/livekit/token/route.ts:15-30`
  - **Owner**: Backend Team
  - **Estimate**: 4 hours
  - **Context**: Public endpoint exposed without auth allows unauthorized access

- [ ] **Security: Remove hardcoded credentials** (#2)
  - [ ] Remove fallback values from environment reads
  - [ ] Add explicit validation for required credentials
  - [ ] Fail fast if credentials missing at startup
  - **File**: `experiments/livekit/src/index.ts:182-183`
  - **Owner**: Backend Team
  - **Estimate**: 1 hour
  - **Context**: Hardcoded fallbacks create security risk in production

示例 2：将会议记录整理为行动项

输入：包含零散行动项的团队会议记录

输出：

# Action Items - Q4 Planning Meeting

> Generated from: team-meeting-2025-12-09.md
> Date: 2025-12-09 14:00:00
> Total Items: 12 | Total Estimated Hours: 45

## P1 - High Priority

**Summary**: 5 items | 20 hours estimated

- [ ] **Architecture: Design new API gateway** (#45)
  - [ ] Research existing solutions (Kong, Tyk, AWS API Gateway)
  - [ ] Document requirements and constraints
  - [ ] Create comparison matrix
  - [ ] Present findings to team
  - **Owner**: Sarah
  - **Estimate**: 8 hours
  - **Context**: Current gateway hitting scale limits at 1000 req/s

- [ ] **Documentation: Update onboarding guide** (#46)
  - [ ] Add sections on local development setup
  - [ ] Document deployment process
  - [ ] Add troubleshooting guide
  - **Owner**: Mike
  - **Estimate**: 4 hours
  - **Context**: New engineers spending 2 days on setup

参考文件

有关行动项组织方式各个方面的详细指导：

• references/priority-framework.md：全面的优先级分类标准，包含特定领域的示例
• references/metadata-extraction-patterns.md：从各种文档格式中提取不同类型元数据的详细模式
• references/TODO_LIST.template.md：按优先级（P0-P3）组织的 TODO 列表模板，包含受阻任务和完成情况跟踪

当您需要更深入地了解优先级决策或元数据提取策略时，请加载这些参考文件。

相关工作流

• 代码审查流程
• Sprint 规划
• 问题分类
• 项目管理
• 审计整改
• 会议引导
• 文档审查