Tapd Story Evaluation

TAPD 需求评估

概述

本技能对 TAPD 需求进行逻辑分析，基于接口定义、公共功能库、前端模块、后端模块逻辑 划分进行子需求拆分，拆分后输出各子需求的规范需求文档，并进行 规模评分（size）（斐波那契） 与 业务价值（RICE）评分。整个流程由两个子技能协作完成：

• tapd-story-breakdown：负责需求拆分，输出各子需求的规范文档
• tapd-story-score：负责工时预估、规模评分（size）与 业务价值（RICE）评分

前置条件

• TAPD MCP 服务可用
• 用户提供至少一个需求 ID
• workspace_id 可由用户提供，或从项目根目录 project.json 读取
• 支持 Windows / Linux / macOS 系统（所有文件操作均使用跨平台方式）

输入

执行流程

1. 参数收集与环境准备

1.1 确定 workspace_id

按以下优先级确定：

1. 用户消息中显式指定 → 直接使用
2. project.json 中的 workspace_id → 使用 read_file 读取并解析
3. 以上均无 → 询问用户

1.2 收集背景知识

按以下优先级确定：

1. 用户显式指定背景文档路径 → 读取指定文档
2. 用户未指定 → 读取 AGENTS.md，从中按需查找以下文档：
   • 架构文档（如 docs/architecture.md）
   • 模块文档（如 docs/modules/）
   • 安全规范（如 docs/security.md）
   • 前端规范（如 docs/frontend-guide.md）
   • 后端规范（如 docs/backend-guide.md）
   • API 文档、Proto 文件等

只读取实际存在的文档，不存在的跳过。将收集到的背景知识作为后续评估的参考上下文。

1.3 解析需求 ID 列表

从用户输入中提取所有需求 ID，构建待处理列表。如果 ID 长度小于 19 位，后续使用 TAPD MCP tapd_id_get 转换为 19 位长 ID。

2. 逐一处理需求

对每个需求 ID 执行以下流程（顺序执行，完成一个再处理下一个）：

2.1 提取需求详情

使用 TAPD MCP stories_get 提取需求信息：

调用参数:
  workspace_id: <workspace_id>
  id: <需求ID>
  with_v_status: "1"

提取成功后检查 v_status：

• 如果 v_status 为"approved"→ 正常继续处理
• 如果 v_status 不为"approved"→ 询问用户是否跳过该需求
  • 用户选择跳过 → 继续处理下一个需求
  • 用户选择不跳过 → 继续处理当前需求

提取的关键信息：

• id（完整 19 位 ID）
• name（需求名称）
• description（需求描述，即规范需求文档）
• priority_label（优先级）
• owner（处理人）
• parent_id（父需求 ID）
• v_status（需求状态）
• category_id（需求分类 ID，用于查询 Category.name）

在本次 stories_get 成功后，从返回的 category_id 获取需求分类，并仅执行一次分类决策 写入当前需求上下文：

category_id = stories_get 返回的 category_id
调用 story_category_get(workspace_id)，按 category_id 找到对应 Category
分类原始值 = Category.name
标准化值 = trim(分类原始值)
若标准化值包含“运维”：需求类型 = “运维操作”
否则若标准化值包含“文档”：需求类型 = “文档编写”
否则：需求类型 = “开发需求”

category_id、对应 Category 或 Category.name 缺失、为空、无法解析或查询异常时，均按 “开发需求”继续，不得中断评估。需求上下文须同时记录 category_id、分类原始值 和 最终 需求类型，以便追溯映射结果。 后续所有步骤复用同一已决策的 需求类型 和 分类原始值，不得重新读取或推断分类。

2.2 需求拆分

整合背景知识与需求描述，调用子 skill tapd-story-breakdown 进行需求拆分。 调用时传递当前需求上下文中的 需求类型 和 分类原始值，以便拆分结果及其后续评分保留 同一分类说明。

子 skill 的详细流程见 tapd-story-breakdown/SKILL.md。

拆分结果处理：

• 无需拆分（子 skill 按用户故事数与规模档位综合判定）→ 直接进入步骤 2.3 对原需求评分
• 有子需求输出 → 进入步骤 2.4

2.3 单需求评分（无需拆分时）

如果需求不需要拆分，直接调用子 skill tapd-story-score 对该需求进行工时预估、 规模评分（size）（斐波那契）和业务价值（RICE）评分：

tapd-story-score(需求文档, 背景知识, 需求类型, 分类原始值)

评分完成后按结果分流：

• E ≤ 24 人时 且 size ≤ 5 → 该需求处理结束，跳过后续步骤；
• size = 8 且 E ≤ 24 人时 → 记录“建议评估拆分”，不阻塞该需求结束；
• E > 24 人时 或 size ≥ 13 → 将原需求视作待重拆的小父需求，回到步骤 2.2 重新拆分，再进入步骤 2.4 确认和步骤 2.5 的回拨控制。不得直接结束或创建超阈值单据。

子 skill 的详细流程见 tapd-story-score/SKILL.md。

2.4 用户确认拆分结果

将拆分产出的多个子需求文档汇总展示给用户：

• 列出每个子需求的名称、核心功能点、依赖关系
• 若启用接口契约先行（详见 tapd-story-breakdown/SKILL.md §3 与 references/requirement-splitting-guide.md §5），一并展示并发波次/可并行分组
• 说明拆分逻辑和理由
• 等待用户确认

用户反馈处理：

• 用户确认通过 → 进入步骤 2.5
• 用户确认不通过 → 收集用户的修改意见和问题，结合反馈回到步骤 2.2 重新拆分
• 终止条件：累计 3 轮确认仍未通过时，终止拆分流程，告知用户"拆分方案无法达成共识，建议用户手动调整需求描述后重试"，跳过该需求继续处理下一个

2.5 逐一评分与规模/工时超阈值回拨

用户确认拆分结果后，对每个子需求执行“评分 → 规模与工时校验 → 超阈值回拨重拆”控制循环。 工时上限为 24 人时（强约束，见 references/requirement-splitting-guide.md §4）；size 为 13 同样表示工作项过大，必须拆分。对同一触发回拨的子需求最多回拨 3 次。 size 为 8 且工时不超过 24 人时只标注“建议评估拆分”，不阻塞建单；size 为 13 的强制 回拨不得被该建议规则豁免。

控制循环（伪流程，非代码）：

对每个子需求 sub:
  调 tapd-story-score(子需求文档, 背景知识, 需求类型, 分类原始值)
  对 sub 完成工时预估、size 规模评分与业务价值（RICE）评分，更新文档
  retry = 0
  while (sub.预估工时 > 24 人时 或 sub.size >= 13) 且 retry < 3:
    调 tapd-story-breakdown 对 sub 做二次拆分（将 sub 视作“小父需求”，
      继承已决策的需求类型和分类原始值）
    对二次拆分产生的每个新子需求，调
      tapd-story-score(子需求文档, 背景知识, 需求类型, 分类原始值) 逐一评分
    retry = retry + 1
    （后续以新产生的子需求集合替代 sub 进入评分校验；若新子需求仍超阈值，
      在其各自的循环中继续回拨，回拨次数独立计数，上限同为 3）
  若 retry 已达 3 且（仍有子需求.预估工时 > 24 人时 或 子需求.size >= 13）:
    将该子需求标注「⚠️ 规模或工时超阈值未解决」
    保留当前拆分与评分结果，继续后续流程（不阻塞）
    在 §4 汇总报告中显式列出，提示用户手动处理
  否则:
    若 sub.size = 8，记录「ℹ️ size=8，建议评估拆分」
    校验通过，进入步骤 3 单据创建

职责边界：回拨控制逻辑置于本主 skill；tapd-story-breakdown 对任意输入执行 相同拆分流程，不感知"首次/二次"，不引入额外模式参数。重拆子需求必须继承父需求 已决策的 需求类型 和 分类原始值，不得再次读取或推断分类。 每次二次拆分产生的新子需求集合都必须在 tapd-story-breakdown 内部完成 §4 拆分后完整性与一致性校验；校验回拨预算独立计数（每次拆分调用各 2 次）。

子 skill 的详细流程见 tapd-story-score/SKILL.md 与 tapd-story-breakdown/SKILL.md。

3. 创建子需求单据

对拆分产出的多个子需求，按以下四阶段创建协议逐一处理（顺序执行，完成一个再处理下一个）：

必需字段清单

每个子需求单据必须填入以下字段（description 为需求文档全量信息，便于后续流程流转）：

阶段 1 — 前置检查（Pre-check）

遍历必需字段清单，检查每个字段的值是否可从以下来源确定：子需求文档、project.json、步骤 1.1 已收集的上下文变量（如 workspace_id），或为固定值（with_v_status=1、v_status="approved"、created=当前时间）。

• 所有字段均有值 → 进入阶段 2
• 有字段缺失且值无法确定 → 阻断：以列表形式展示缺失字段，告知用户补充后可重试，跳过该子需求，继续处理下一个

阶段 2 — 创建（Create）

⚠️ 前置操作：调用 stories_create 前，必须先通过读取 §3.4 保存的子需求本地文件（docs/reqs/<子需求文件名>.md）获取完整内容，将读取结果作为 description 参数值传入，禁止从上下文直接 inline。

调用 TAPD MCP stories_create，传入上述必需字段清单中的全部字段：

stories_create(..., effort=本次评分输出.E, size=本次评分输出.斐波那契规模分,
  business_value=本次评分输出.RICE业务价值分,
  description=评分后的完整子需求文档)

需求类型和估时依据随 description 保留，不新增 TAPD 字段。若调用失败，按错误处理表格中 「子需求创建失败」的处理方式执行（重试一次，仍失败则输出文档供手动创建），记录状态 「❌ 创建失败」，跳过阶段 3 和阶段 4。

阶段 3 — 后置验证（Post-verify）

调用 TAPD MCP stories_get（参数：workspace_id（步骤 1.1）、id（阶段 2 返回的 story ID）），提取实际写入的字段值，对以下业务字段逐一检验是否有非空值（with_v_status 和 created 为写入辅助参数，API 不回写，不参与验证）：name、parent_id、description、v_status、owner、creator、developer、priority_label、effort、size、business_value。

• 全部字段均有非空值 → ✅ 验证通过，记录状态「✅ 通过」
• 有字段为空或缺失 → 进入阶段 4

阶段 4 — 自动修复（Fix）

由于阶段 1 已确认所有必需字段的值可确定，对每个验证缺失的字段，直接从原来源（子需求文档、project.json、步骤 1.1 上下文或固定值）取值，调用 TAPD MCP stories_update 补全（调用参数：workspace_id（步骤 1.1）、id（阶段 2 返回的 story ID）、以及各缺失字段的键值对）。调用成功，记录「🔧 已修复（{字段列表}）」；若调用失败，记录「⚠️ 修复失败（{字段列表}）」并告知用户手动补全对应字段。

⚠️ 注意：从子需求文档取值时，必须通过读取本地文件 docs/reqs/<父需求名>/<子需求文件名>.md 获取，禁止从上下文直接 inline。

每个子需求最终输出状态之一：

• ✅ 通过：所有字段验证通过
• 🔧 已修复（{字段列表}）：有字段缺失但已自动补全
• ⚠️ 修复失败（{字段列表}）：stories_update 调用失败，已告知用户手动补全
• ❌ 创建失败：stories_create 重试后仍失败，已输出文档供手动创建
• ⏭ 已跳过（前置检查缺失：{字段列表}）：必需字段值无法确定，未创建单据

4. 汇总输出

所有需求处理完毕后，简短总结输出处理内容。

「单据状态」聚合规则（将该父需求下各子需求的终态汇总为一个单元格）：

• 全部为 ✅ 通过 → ✅ 全部通过
• 有修复/失败/跳过/超阈值时，逐类计数，如 2✅ 1🔧、2✅ 1⏭、1✅ 1❌、2✅ 1⚠️
• 无子需求（无需拆分）→ —

⚠️ 表示该子需求经 3 次回拨后仍工时超阈值（>24 人时）或 size ≥13，需用户手动处理； ℹ️ 表示 size=8 且工时合格，仅建议评估拆分。

## 需求评估完成

| 需求 ID | 需求名称 | 处理结果 | 子需求数 | 需求类型 | 估时依据摘要 | 预估工时(E) | size | 业务价值（RICE） | 校验 | 单据状态 | 本地文件 |
|---------|---------|---------|---------|----------|--------------|------------|------|------------------|------|---------|---------|
| xxx | xxx | ✅ 已拆分并评分（含 1 次回拨重拆） | 3 | 运维操作 | 操作范围、变更风险、执行复杂度、验证与回滚 | 16/12/8 | 3/2/2 | 80/65/45 | 覆盖 18/18 · 一致 6/6 | ✅ 全部通过 | docs/reqs/xxx/ |
| aaa | aaa | ⚠️ 已拆分并评分（1 个子需求规模或工时超阈值未解决） | 3 | 开发需求 | 命中的开发类基线与调整因子 | 28/16/12 | 13/3/2 | 70/50/40 | 覆盖 17/18 ⚠️ · 一致 5/6（依赖成环） | 2✅ 1⚠️ | docs/reqs/aaa/ |
| yyy | yyy | ℹ️ 无需拆分，size=8，建议评估拆分 | 0 | 文档编写 | 内容范围、资料调研、技术验证、评审轮次、维护影响 | 8 | 8 | 120 | — | — | docs/reqs/yyy.md |

> 「处理结果」列须显式标注回拨重拆轮次（如"含 N 次回拨重拆"）及是否存在
> 「⚠️ 规模或工时超阈值未解决」的子需求；size=8 的建议标记使用 `ℹ️`。「本地文件」列对
> 已拆分需求填子目录路径 `docs/reqs/<父需求目录名>/`。
> 每行的「需求类型」和「估时依据摘要」必须可关联到同一行的预估工时(E)、业务价值（RICE）分数、
> size/24 人时阈值、回拨结果和单据状态。
> 「校验」列格式：`覆盖 X/Y · 一致 M/N`；未走拆分（无需拆分场景）填 `—`；
> 若 3 次校验后仍未通过，格式为 `覆盖 X/Y ❌ · 一致 M/N（用户处理）`，并保持后续流程不阻塞。

共处理 N 个需求，拆分产出 M 个子需求，已创建 K 个 TAPD 子需求单据。

错误处理

子技能

本 Skill 包含两个子技能，各自独立运作，由主流程编排调用：

参考文件

产出

• 拆分后的子需求文档（如发生拆分），保存在 docs/reqs/ 目录
• 包含工时预估、规模评分（size）（斐波那契）和 业务价值（RICE）评分的需求文档
• 创建的 TAPD 子需求单据（v_status 为"approved"，含 size 和 business_value 字段）
• 处理汇总报告

使用示例

用户输入：评估需求 12345

系统处理：
1. 获取 workspace_id，收集项目背景知识
2. 使用 TAPD MCP 获取需求 12345 详情
3. 分析需求包含 4 个用户故事，需要拆分
4. 调用 tapd-story-breakdown 拆分为 3 个子需求
5. 展示拆分结果，等待用户确认
6. 用户确认后，逐一调用 tapd-story-score 评分
7. 按四阶段协议（前置检查→创建→后置验证→自动修复）创建 3 个子需求单据
8. 输出评估汇总

用户输入：评估需求 67890，这个需求比较简单

系统处理：
1. 获取 workspace_id，收集项目背景知识
2. 使用 TAPD MCP 获取需求 67890 详情
3. 分析需求只有 1 个用户故事，无需拆分
4. 直接调用 tapd-story-score 评分
5. 输出评估结果