Tapd Story Clarification

---
name: tapd-story-clarification
slug: tapd-story-clarification
version: 1.0.0
description: |
  TAPD 需求澄清技能。从 TAPD 提取"规划中"状态的需求，按照研发最佳实践对需求进行
  多维度澄清（业务逻辑、外部系统交互、上下文），整合项目背景知识，输出符合需求文档
  规范的标准化 Markdown 需求文档，并回写 TAPD。
  Use this skill whenever the user mentions 需求澄清, 澄清需求, clarify story,
  clarify requirement, 需求细化, 需求整理, 需求规范化, 补充需求, 完善需求描述,
  story clarification, requirement clarification, 需求文档整理,
  or any workflow involving TAPD story description refinement and standardization.
metadata:
  requires:
    mcps: ["tapd"]
---

# TAPD 需求澄清

## 概述

本技能从 TAPD 提取处于"规划中"状态的需求，采用研发最佳实践（5W1H 结构化提问、
BDD 验收标准、流程可视化）对需求进行多维度澄清，结合项目背景知识生成标准化需求
文档，最终回写到 TAPD 需求描述字段并推进状态。

## 前置条件

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

## 输入

| 参数 | 来源 | 必需 | 说明 |
|------|------|------|------|
| 需求 ID | 用户输入 | 是 | 一个或多个 TAPD 需求短 ID |
| workspace_id | 用户输入 > project.json | 是 | TAPD 工作空间 ID |
| 背景知识 | 用户指定 > AGENTS.md 自动查找 | 否 | 架构文档、模块文档、安全规范等路径 |

## 执行流程

### 1. 参数收集与环境准备

#### 1.1 确定 workspace_id

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

#### 1.2 收集背景知识

按以下优先级确定：
1. 用户显式指定背景文档路径 → 读取指定文档
2. 用户未指定 → 读取项目根目录 `AGENTS.md`，从中识别项目的架构文档、模块文档、
   规范文档、API 文档等（具体路径因项目而异，按 AGENTS.md 中的描述定位）

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

#### 1.3 解析需求 ID 列表

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

### 2. 逐一处理需求

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

#### 2.1 提取需求详情

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

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

如果查询结果为空：
- 提示用户该需求不存在或状态不是"backlog"
- 跳过该需求，继续处理下一个

提取成功后记录需求的关键信息：
- `id`（完整 19 位 ID）
- `name`（需求名称）
- `description`（原始需求描述）
- `priority_label`（优先级）
- `owner`（处理人）
- `parent_id`（父需求 ID，用于判断是否子需求）
- `detail_link`（TAPD 详情链接）

#### 2.2 需求澄清

整合背景知识与需求原始描述，按照 `references/clarification-guide.md` 中的最佳
实践进行多维度澄清。

> **执行前必读** `references/clarification-guide.md`，其中定义了完整的澄清维度
> （业务价值、用户故事、验收标准、外部系统交互、数据模型、非功能需求、边界条件）
> 和各维度的具体检查项。按需求复杂度选择需要覆盖的维度子集。

##### 按需触发的方法（复杂需求才展开）

以下方法**按条件触发**，简单需求可全部跳过；触发时详见 `clarification-guide.md`：

- **业务目标模糊** → 强制量化目标 + 明确期望的行为变化（§一 Why 行）
- **业务规则 ≥ 2 条 或 含条件分支/阈值** → 使用 **Example Mapping**（§五）：
  每条规则至少绑定 1 正例 + 1 反例
- **问题总数 > 3 或存在范围疑问** → **两轮制**（§二 · 两轮制触发条件）：
  先 Framing 锁范围，再 Detailing 补细节
- **写完 AC** → 走一遍 **BDD 反模式清单**（§四）

##### 澄清流程

1. **通读需求描述**，结合背景知识，按上述七个维度逐一排查信息缺失
2. **整理问题清单，所有问题统一编号**，一次性向用户提出（避免碎片式逐条追问）：
   - 问题需要可行的选择项A、B、C等（便于用户选择）
   - 🔴 阻塞性问题放前面（缺少这些信息无法开始实现）
   - 🟡 非阻塞性问题放后面（可以先假设后确认）
3. **等待用户回复**，可能需要多轮对话：
   - 用户提供接口文档路径时，直接读取文档提取关键信息
   - 用户提供设计稿链接时，记录链接地址
   - 对于用户无法即时回答的问题，记录为"待确认"
4. **确认理解**：将澄清结论复述给用户确认，避免理解偏差

##### 跳过澄清的条件

**Skip 只跳过交互式追问，不跳过质量门禁**——`references/dor-checklist.md` 与
"假设与未决问题"章节的填写始终必须完成。

完全放行的快速通道**仅限**：纯文案 / 配置变更，且原始需求描述中已明确给出验收标准。

其它场景（用户口头表示"很清楚"、提供了完善文档等），可以简化交互，但仍必须：
- 按模板补齐所有章节
- 走一遍 DoR 8 项门禁
- 显式声明"假设"（无假设时写"无"）

即使跳过交互，也要在文档中标注"用户确认需求描述充分，无额外澄清交互"。

#### 2.3 生成规范化需求文档

整合原始需求信息和澄清内容，按照 `references/requirement-doc-template.md` 中的
文档模板生成标准化 Markdown 需求文档。

##### 文档生成规则

- 原始需求描述必须完整保留在"原需求描述"章节
- 澄清过程中的问答必须记录在"澄清记录"章节
- 信息充分的章节详细填写，信息不足的标注"待确认"
- 所有验收标准必须使用 Given-When-Then 格式
- 性能指标必须使用可量化的数字
- 避免使用"较快""较好"等模糊词汇

##### 文档保存

生成需求文档后，将文档保存为本地 Markdown 文件，存放在项目根目录的 `docs/reqs/`
下。

**文件命名规则**：

从需求名称中提炼核心关键词作为文件名，要求：
- 长度：最少 4 个字，最多 10 个字
- 去除需求名称中的修饰词、量词、连接词等冗余成分，保留最能概括需求本质的关键词
- 使用中文
- 文件扩展名统一为 `.md`
- 如果文件名已存在，追加需求短 ID 后缀以区分（如 `用户权限管理_12345.md`）

**命名示例**：

| 需求名称 | 提炼后文件名 |
|---------|------------|
| 新增用户权限管理模块 | `用户权限管理.md` |
| 优化首页加载性能提升用户体验 | `首页性能优化.md` |
| 对接第三方支付系统完成订单结算 | `三方支付对接.md` |
| Add OAuth2 login support | `OAuth2登录.md` |

**保存流程**：

1. 确保 `docs/reqs/` 目录存在，不存在则创建
2. 从需求名称提炼 4-10 字文件名
3. 检查同名文件是否已存在，若存在则追加需求短 ID 后缀
4. 将完整需求文档写入该文件
5. 告知用户文件保存路径

#### 2.4 DoR 门禁自检

在向用户展示文档并请求确认之前，按 `references/dor-checklist.md` 中 8 项二值判断项
逐条自检：

- **全部通过** → 进入 §2.5 用户确认，回写时可将状态推进为 `approved`
- **任一项未通过** → 记录未通过项，进入 §2.5 用户确认；回写时**必须**保持
  `v_status: backlog`，不允许推进为 `approved`

自检结果需在最终汇总输出（§3）中体现，便于下一流程接收方判断需求成熟度。

#### 2.5 用户确认

将生成的需求文档展示给用户，请求确认：
- 文档内容是否准确完整
- 是否有需要调整的部分
- 确认后进入回写步骤

如果用户提出修改意见，修改文档后再次确认，直到用户满意。

#### 2.6 回写 TAPD

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

使用 TAPD MCP `stories_update` 将最终需求文档以 markdown 格式全量更新至 TAPD
（无需精简信息）。

**状态字段（`v_status`）由 §2.4 DoR 门禁结果决定**：

- DoR 全部通过 → `v_status: approved`
- DoR 任一项未通过 → `v_status: backlog`（描述照常更新，状态不推进）

```
调用参数:
  workspace_id: <workspace_id>
  id: <需求完整19位ID>
  description: <读取本地文件 docs/reqs/<文件名>.md 所得的完整内容>
  v_status: <approved 或 backlog，取决于 DoR 门禁结果>
```

回写成功后记录：
- 需求 ID
- 需求名称
- 更新时间
- 新状态

回写失败时：
- 重试一次
- 仍失败则告知用户，输出文档内容供用户手动更新

### 3. 汇总输出

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

```markdown
## 需求澄清完成

| 需求 ID | 需求名称 | 处理结果 | DoR | 状态 | 本地文件 |
|---------|---------|---------|-----|------|---------|
| xxx | xxx | ✅ 已澄清并回写 | 8/8 通过 | approved | docs/reqs/xxx.md |
| yyy | yyy | ⚠️ DoR 未过（第 1、6 项） | 6/8 | backlog | docs/reqs/yyy.md |
| zzz | zzz | ⚠️ 回写失败，文档已输出 | - | backlog | docs/reqs/zzz.md |

共处理 N 个需求，DoR 通过 M 个，未通过 K 个（详见各自本地文件）。
```

## 错误处理

| 错误场景 | 处理方式 |
|---------|---------|
| TAPD MCP 不可用 | 终止执行，提示用户检查 MCP 配置 |
| 需求 ID 不存在 | 跳过该需求，继续处理下一个 |
| 需求状态不是"backlog" | 提示用户，询问是否仍要澄清（可能已被处理过） |
| 回写 TAPD 失败 | 重试一次，仍失败则输出文档供手动更新 |
| DoR 门禁未通过 | 回写描述，保持 `backlog` 状态；在汇总输出中标注未过项 |
| 用户中断澄清 | 保存当前内容，标注"澄清未完成" |

## 参考文件

| 文件 | 用途 | 何时读取 |
|------|------|---------|
| `references/clarification-guide.md` | 需求澄清最佳实践指南（含 Example Mapping / BDD 反模式 / 两轮制） | 执行澄清时 |
| `references/requirement-doc-template.md` | 标准化需求文档模板 | 生成文档时 |
| `references/dor-checklist.md` | 回写前门禁清单（8 项二值判断） | §2.4 DoR 自检时 |

## 产出

- 规范化需求文档保存至 `docs/reqs/<提炼文件名>.md`（4-10 字精简文件名）
- TAPD 需求 `description` 字段更新为规范化需求文档
- TAPD 需求状态更新为：DoR 全过 → `approved`；否则保持 `backlog`
- 控制台输出处理汇总（含本地文件保存路径与 DoR 通过情况）