Requirement Mining

---
name: requirement-mining
description: 从用户的功能描述深度挖掘真实需求（打穿表象找根因），转译为可落地的技术需求清单，并在分析阶段用「现状 → 预期」图示（Mermaid / ASCII）呈现流程、数据流、UI 变化。触发："我想做一个 xxx"、"帮我分析需求"、"这个流程改动前后是啥样"，或需在需求分析阶段看清改动对比。
---

## 概述

**目的**：从用户功能描述中深度挖掘真实需求，打穿表象找到根因，将产品需求转译为可落地的技术需求清单

**功能**：
- 自主推理用户真实动机与场景，识别"伪装成需求的解决方案"
- 批判性评估方案根本性，提供短期/长期建议
- 需求转译为结构化需求清单（优先级、依赖、验收标准）
- **图形化表达变化**：涉及流程/数据流/UI/状态变化的需求，在分析阶段即给出「现状 → 预期」图示对比（Mermaid / ASCII），让用户一眼看到哪里会变、变成什么样
- 复杂度评估与快速实现判断，基于需求特征推荐下一步行动
- **外部依赖文档可查阅性判定**：依赖可行性分析时按规模判断"直接查 / 登记待建 / 现在建索引"（调用 `web-index`，判定表 SSOT 在其「被其它 skill 集成」章节）
- 快速实现时调用 use_skill("expert-solution-workflow") 查询相关经验、解决方案或记忆，复用已有资产加速编码
- **快速实现（用户选择直接实现）默认调用 use_skill("plan-track") 建档**：跳过设计文档后，台账是进度与验证证据的唯一载体（见 Step 8.1）
- 维护需求目录索引文件，自动归档过时文档
- 复杂需求可拆分为子需求文档（可选行动），供多窗口并行设计/实现

**使用场景**：
- 用户提出产品功能描述或改善诉求时
- 用户抱怨/吐槽系统体验问题时
- 用户探索性提问"有什么优化空间"时
- 需要从原始需求出发理清背后真正动机和场景时
- 需要将产品需求拆分为技术需求时

## 核心原则

- **效果导向，不关心实现**：只关注需求实现后的具体效果和用户体验，不关心代码如何实现、用什么技术栈、架构如何设计
- **先猜后问**：优先自主推理，给出假设性结论让用户确认或纠正，而非一上来就提问
- **打到根因**：必须追问"这个功能要解决的核心问题是什么"，分析该功能是否从根本上解决问题，而非打补丁
- **挑战方案**：用户提出的功能不一定合理。如果发现是治标不治本的方案，必须指出并提供更根本的替代思路
- **识别伪需求**：用户说的可能是"伪装成需求的解决方案"，需要还原出真正的需求本身
- **场景完整性**：识别多场景分支，确保分析覆盖所有相关场景
- **图形化表达**：涉及流程/数据流/UI/状态变化的需求，**必须在分析阶段（Step 3）给出「现状 → 预期」图示对比**——图的价值是让用户在确认阶段最快发现理解偏差。只画"变什么"（效果层），不画"怎么实现"（设计层），现状不臆造（画法见 [references/diagram-guide.md](references/diagram-guide.md)）
- **界面变更先出图再确认**：命中 UI 变更面（页面 / 组件的样式、布局）时，**必须调用 `use_skill("ui-to-ascii")` 的描述生成模式**，按其「界面确认闸门」出 ASCII 并取得用户确认；**未经 Step 4A 确认前不得进入 Step 5 及之后的分析与转译**，也不得把布局细节当既成事实写进需求清单
- **假设可验证**：关键假设必须可验证，验证难度需评估
- **最小化交互**：理想情况仅 1-2 轮确认即可完成
- **容错迭代**：用户纠正后快速更新理解，不反复确认
- **仅卡壳时提问**：只有信息严重不足、无法合理推断时，才提最小化的澄清问题

## 执行流程

> **重要**：AI 在阅读需求文档时，**必须自动忽略 `archive/` 目录下的文档**。归档目录中的文档已过时或废弃，不应作为需求分析的依据。

### Step -1：需求类型识别

在开始分析之前，先识别需求类型：

| 需求类型 | 特征 | 处理方式 |
|----------|------|----------|
| **明确需求** | 用户描述了具体功能、场景、目标 | 进入 Step 0 开始分析 |
| **探索性需求** | 用户说"看看有什么优化空间"、"分析一下"、"有什么可能性" | 先引导用户聚焦：询问关注的重点（转化率、用户体验、技术性能等），根据回答确定分析方向 |
| **模糊需求** | 描述含糊，缺乏具体信息 | 提 1-2 个关键问题，帮助用户明确范围后再分析 |

**探索性需求引导模板**：
```markdown
您提到的是一个探索性需求，为了更精准地分析，请确认以下几点：

1. 您关注的重点是什么？（可多选）
   - 转化率/业务指标
   - 用户体验/满意度
   - 技术性能/稳定性
   - 功能完整性
   - 其他：[请说明]

2. 您希望分析的范围是？
   - 整个系统
   - 特定模块/流程
   - 特定用户角色

请根据您的回答，我将聚焦分析方向。
```

### Step 0：前置筛查

在深入分析之前，先做快速判断：

**检查是否存在以下误判情况：**

| 误判类型 | 特征 | 处理方式 |
|----------|------|----------|
| **实为 Bug** | 用户描述的能力系统本应具备，但当前不可用或行为异常 | 提醒用户："这看起来像是已有功能的 Bug，建议先确认是否为缺陷而非新需求" |
| **已有功能** | 用户请求的能力系统中已经存在，只是用户不知道 | 提醒用户："当前系统已有类似能力（简述），请确认是否满足需求" |

如果命中以上任一情况，先输出提醒，等用户确认后再继续。如果确认不是误判，进入 Step 1。

### Step 1：自主推理

根据用户的功能描述，从以下维度进行自主分析推理：

1. **需求形态判断**：用户描述的是真实需求，还是伪装成需求的解决方案？如果是方案，还原出背后的真正需求是什么
2. **功能本质**：这个功能到底解决了什么问题？不是复述描述，而是提炼底层诉求
3. **动机与原因**：为什么用户/使用者需要它？背后的驱动因素是什么？
4. **使用场景识别**：
   - **单场景**：直接描述
   - **多场景**：识别所有相关场景，分别描述，标注场景间关联性
5. **角色识别**：
   - **角色明确**：直接描述
   - **角色不明确**：推断最可能的用户角色（基于场景），列出可能选项让用户选择
6. **现状替代方案**：在没有这个功能之前，用户是怎么绕过去的？绕行的代价是什么？
7. **期望体验**：理想状态下用户完成操作后的感受是什么？"最爽的一点"是什么？
8. **上下文检查**：这个需求是否基于之前的讨论、已知问题或历史数据？是否需要参考相关文档？
9. **非功能性需求识别**：
   - 性能要求（响应时间、并发量、数据量）
   - 安全要求（数据安全、权限控制）
   - 可用性要求（易用性、学习成本）
   - 兼容性要求（浏览器、设备、系统版本）
10. **变更面识别**（画图的总开关）：这个需求做完，**什么东西的"形状"会变**？
    - **执行流程**：步骤增删、顺序调整、分支/异常路径变化、同步改异步
    - **数据流**：数据的产生位置、流向、存储位置、消费方变化
    - **UI**：界面布局、元素、入口位置、状态显示变化 → Step 3 出图时**必须走 `use_skill("ui-to-ascii")` 的「界面确认闸门」**（ASCII 界面图 + 用户确认，确认前不进入下游）
    - **状态流转**：业务对象（订单/任务/工单等）的状态机变化
    - **无明显形状变化**：纯性能、兼容性、文案、权限、安全加固 → **不出图**
    命中前四类任一 → Step 3 输出假设时附「现状 → 预期」图示；命中多类优先画最主要的一类，其余有独立价值的各出 1 组，总数 ≤ 3 组（信号表与画法见 [references/diagram-guide.md](references/diagram-guide.md)）
    - **变更面不明**（探索性需求尚未聚焦、用户未说改什么）：标 `待定`，**不得直接归为"无明显形状变化"**——待 Step -1 聚焦后再判，本轮不出图

**推理要求**：不做复读机（不复述原话，推断须有逻辑链条）；场景具象（含角色、时间点、触发条件、完成状态）；识别到"方案即需求"必须还原需求本身；多场景分别分析并标注关联性，角色不明时推断并列出选项。

### Step 2：判断是否可推理

完成推理后，做判断：

- **信息充足 → 直接输出假设**，进入 Step 3
- **信息部分缺失但有方向 → 给出 2-3 种可能解读，让用户选择或纠正**
  > 给出多种解读时，**只为最可能的一种画「现状 → 预期」图**，其余用文字描述——每种解读都配图会使图数量翻倍，突破成本闸门且让用户更迷茫（图上差异往往只是"某个分支有没有"）
- **信息严重不足 → 提 1 个最小化关键问题**，拿到答案后回到 Step 1 继续推理

**迭代限制**：如果用户多次纠正假设（超过 3 次），建议用户重新描述需求，以确保分析基础清晰。重新描述时引导用户提供：1. 明确目标用户角色，2. 具体描述使用场景，3. 说明期望的解决效果。

### Step 3：输出假设，请用户确认

将推理结论以结构化形式呈现，**务必列出推理所依赖的关键假设和验证建议**：

```markdown
## 需求理解（请确认或纠正）

基于你的描述，我的分析如下：

**需求形态**：[真实需求 / 伪装成需求的方案 → 还原后的真实需求]

**功能本质**：[一句话概括这个功能要解决的核心问题]

**使用场景**：
- 场景 1：[角色] 在 [时间/条件] 下 [做什么]，[期望结果]
- 场景 2：[如有多个场景]
- 场景关联性：[场景间的关系：并行/互斥/依赖]

**用户角色**：[明确角色 / 推断的角色：A/B/C，请选择]

**核心痛点**：[当前没有这个功能时的具体困境]

**期望体验**：[用户理想中的完成状态]

**深层动机**：[为什么要做这件事的原因链]

**非功能性需求**：
- 性能：[如有明确要求]
- 安全：[如有明确要求]
- 可用性：[如有明确要求]
- 兼容性：[如有明确要求]

**本次推理的关键假设**：

| 假设 ID | 假设内容 | 验证难度 | 验证建议 |
|---------|----------|----------|----------|
| H-01 | [假设1：例如"假设目标用户是运营人员而非开发者"] | 中 | [如何验证：询问用户角色构成] |
| H-02 | [假设2：例如"假设当前没有其他系统承担类似职能"] | 低 | [如何验证：系统调研] |
| H-03 | [假设3] | 高 | [如何验证：需要数据支撑] |

假设如有错误，纠正后会直接影响后续分析的准确性，请重点核实。

---

**变更面**：[执行流程 / 数据流 / UI / 状态流转 / 无形状变化]

**现状 → 预期（图示）**：[命中变更面时必填；未命中则写"本次无明显形状变化，不出图"]

[预期图（必画）+ 现状图（现状不可知时可省略，注明"现状待确认"）：Mermaid 双图并排 / 单图差分标注 / ASCII 双屏，按变更面选型]

**现状来源**：[用户提供 / 读代码确认（{文件}）/ ⚠️ AI 推断（对应**上方**假设 H-xx，请重点确认）/ 现状不可知，本轮未画现状图]

**变更点**：
| 变更点 | 现状 | 预期 | 类型 | 关联假设 |
|--------|------|------|------|----------|
| [元素/步骤名] | [现在怎样] | [做完怎样] | 新增/修改/删除 | H-01 / - |

**界面布局确认**（命中 UI 变更面时必填）：[已按 `ui-to-ascii` 界面确认闸门出 ASCII，需你确认：区块增删 / 排列方向 / 入口位置 / 显隐与层级 / 断点行为——**须单独表态**，对"需求理解"的整体确认不等同于布局确认；未确认不进入后续分析与转译]；未命中写"本次无界面变更"

> **顺序硬约束**：假设表在前、图在后。图中每个"⚠️ AI 推断"必须引用**上方已列出**的假设 ID；画图时若发现缺少对应假设（如"现状为同步阻塞"），**先补进假设表再引用**，禁止引用不存在的 H-xx。

---
请确认以上理解是否准确？如有偏差请直接指出，我会更新理解。
命中 UI 变更面时，请**另对「界面布局确认」单独表态**（布局未确认前我不进入后续分析与转译）。
```

### Step 4A：用户确认 → 进入根本性分析

用户确认后，进入根本性分析阶段。

### Step 4B：用户纠正 → 更新后重新确认

根据用户的纠正更新理解，再次输出修正后假设。**若纠正涉及现状、预期或变更点，图示必须同步重绘**——不得沿用旧图让用户确认（旧图即旧错误，确认依据失效）。

**迭代规则**：最多迭代 3 次，每次必须输出修正后的假设让用户确认；超过 3 次后建议用户重新描述需求（沿用 Step 2 的迭代限制）。

### Step 5：根本性分析（关键步骤）

此步骤是需求挖掘的核心。用户提出的功能不一定合理，描述的表面诉求和真实根因往往不同。

#### 5.1 定位核心问题

基于已确认的需求理解，提炼出**底层核心问题**：

- 用户描述的功能在"解决什么"？用一个问题陈述句表达（不是方案，是问题本身）
- 这个问题为什么存在？它的根因是什么？
- 如果根因消除，是否还需要当前这个功能？
- **如果根因超出技术范畴**（如组织流程、人力配置、业务模式问题），标注出来但不展开，聚焦于技术层面能解决的部分，并说明技术手段能覆盖的边界

#### 5.2 评估方案的根本性

对用户提出的功能方案做批判性评估：

| 评估维度 | 问自己 |
|----------|--------|
| **问题-方案匹配度** | 这个功能是对症下药，还是头痛医头？ |
| **症状 vs 根因** | 功能是在消除表面症状，还是在解决根本原因？ |
| **效果覆盖度** | 方案能否覆盖核心场景？覆盖了多少百分比的痛点？ |
| **普适性** | 只解决了当前场景，还是能覆盖同一类问题的其他变体？ |
| **副作用** | 实现后是否会引入新的问题？用户操作流程是否变复杂？ |

#### 5.3 给出判定

根据评估结果，输出判定结论：

**情况 A：方案对症**
> 结论：用户提出的功能方案合理，能从根本上解决问题。
> 直接进入需求转译。

**情况 B：方案部分有效**
> 结论：该功能能缓解问题，但未触及根因。根因是 [XXX]，建议额外考虑 [更根本的方案]。
> 当前功能可作为短期方案，长期建议 [XXX]。
> 转译时将**同时产出短期和长期两套需求条目**，长期条目标记为"远期"，便于分期规划。
> 请确认是否按此方向继续？

**情况 C：方案治标不治本**
> 结论：该功能是对症状的处理，不能真正解决问题。根本原因是 [XXX]。
> 建议替代方案：[描述更根本的解决思路]。
> 请确认：1) 坚持原方案（打补丁），2) 按替代方案重新分析，3) 两者结合？

输出格式：

```markdown
## 根本性分析

### 核心问题
[用 1-2 句话描述底层问题本身，不是方案]

### 根因链
[导致这个问题的根本原因，可以是一层或多层因果链]

### 方案评估
**你描述的功能**：[方案简述]
**我的判断**：[情况 A / B / C]
**理由**：[为什么这么判断，逻辑链]

### 预期效果分析
- **核心场景覆盖度**：[高/中/低] - [能覆盖多少核心场景]
- **痛点解决程度**：[高/中/低] - [能在多大程度上解决痛点]
- **用户体验提升**：[感受与效率的变化；**操作流程的变化直接引用 Step 3 的图示（报告 §2.10），不重复文字描述**，避免图与文字双写不一致]
- **潜在副作用**：[是否引入新的问题或复杂度]

### 建议
- **短期**：[如果可以接受的临时方案]
- **长期/根本**：[更根本的解决思路]
- **如果坚持原方案**：[用户否决 AI 建议后需接受的局限性]

### 关键决策点
| 决策 | 选择 | 理由 | 备选方案 | 否决原因 | 重新评估触发条件 |
| --- | --- | --- | --- | --- | --- |
| `<决策点 1>` | `<选择>` | `<理由>` | `<方案 A>` | `<否决原因>` | `<可观测判据，写不出填「无」>` |
| | | | `<方案 B>` | `<否决原因>` | |

> 说明：本小节做**决策轨迹留痕**而非决策定论——把散在「方案评估」（被否决方案及理由）与「如果坚持原方案」（用户否决 AI 建议后需接受的局限性）的决策信息**收敛到一处**，供后续回顾"当初为什么这么定、砍掉了什么"。本小节**不写 ki**：需求阶段决策比设计阶段更易变，只作决策记忆的数据源，模块实现落地后可由 `expert-team` 收割入 ki。

**需求分析前置——ki 记忆查询**（涉及既有模块时可选；调用 `use_skill("ki-memory-lookup")`，失败或无记录则忽略继续）：① **强关联策略**——检索"改动会牵动哪些其他模块"，补充影响范围与依赖分析；② **决策记忆策略**——核对本次新建议是否恰是已被否决的方案，若是，先核对原否决理由再重新提出，避免把已否决方案当新建议重复建议。

---
请确认后续方向：[继续原方案 / 按替代方案分析 / 结合方案]
```

将结论和建议发给用户确认，待用户选择方向后再进入需求转译。

### Step 5.5：需求可行性分析

方案方向确认后，在需求转译前评估需求的**可落地性**。与 Step 5（方案是否合理）和 Step 6.6（复杂度/能否快速实现）区分：本步骤回答"**技术上能不能做、值不值得做、有什么落地障碍**"，复杂度评估回答"工作量多大、能否快速实现"。

#### 5.5.1 可行性评估维度

| 维度 | 问自己 |
|------|--------|
| **技术可行性** | 是否有成熟技术/方案支持？是否涉及未验证的技术假设或高风险技术？ |
| **依赖可行性** | 所需外部依赖/系统/数据是否可用？是否有前置依赖未满足？ |
| **文档可查阅性** | 外部依赖的文档**能不能查到该看的那一页**？是查一次就够，还是要建索引（见 5.5.3）？ |
| **资源可行性** | 时间、人力、预算是否匹配？ |
| **成本效益** | 投入产出比是否合理？是否有更轻量的替代方案？ |
| **风险等级** | 技术失败风险、进度风险、上线风险如何？ |

#### 5.5.2 给出可行性结论

- **可行**：无障碍或障碍可规避，直接进入需求转译。
- **条件可行**：存在可管理障碍，列出前置条件与规避方案，标注需满足的条件后再转译。
- **不可行**：存在硬性障碍，给出原因与替代建议，请用户确认是否继续。

> 结论写入报告 §4.9，五字段：可行性结论 / 外部依赖文档（直接查·消费·现在建·登记待建）/ 落地障碍 / 前置条件 / 可行性约束（条件可行·不可行时须在需求清单上标注）。

> **交互控制**：可行性高时简要带过（1-2 句结论），仅在"条件可行"或"不可行"时才详细展开并请用户确认，避免与"最小化交互"原则冲突。**Step 5 判定"情况 A（方案对症）"且需求明显可行、无突出技术风险时**，可直接简要带过，无需独立成章。

> **资产复用**：评估"是否涉及未验证技术假设/高风险技术"时，可先调用 use_skill("expert-solution-workflow") 查询相关经验、解决方案或记忆（如业务专家资产包中的技术风险与已知坑），复用已有可行性判断，与快速实现路径保持一致；未找到则自主判断。

#### 5.5.3 外部依赖文档：直接查 / 登记待建 / 现在建

需求涉及外部服务、SDK、API、平台文档时，先判"文档怎么查"，**不要一律去建索引**（判定表 SSOT 见 `web-index` 的「被其它 skill 集成」章节，此处只给需求阶段的落地口径）：

| 信号 | 结论 | 动作 |
|------|------|------|
| 只是确认"这个东西能不能用"，查一页就够 | **直接查** | `web_fetch` / `web_search`，不产出文件 |
| 已在 `.web-index/INDEX.md` 在册 | **消费** | 查索引定位页面后 fetch，**不重建** |
| 手里**没有明确的入口 URL**（只知道"要用 Stripe"） | **登记待建** | 需求阶段不去猜入口；等设计阶段由 `dependency-docs` 确定官方文档入口后再决定 |
| 多页文档站 + 需求已确认 + 后续设计/编码/测试会反复参考 | **现在建** | 调用 `web-index` 建造模式 |
| 多页文档站 + 但**需求尚未确认**（本步只做可行性判断） | **登记待建** | 把站点写进待建清单，交给后续阶段，**本步不建** |

> 站点是否"多页文档站"拿不准时，用 `web-index` 的抓取脚本试抓一次（成本极低）即可判定，不必靠猜。分出"登记待建"的理由：需求阶段方案还没定，此时花一轮上下文建索引，需求一转向就全白费——**先登记，等确定要用再建**。

输出并入 5.5.2 结论与报告 §4.9，一行一条「站点 → 结论 → 动作」：`Stripe 文档：多页站 + 需求已确认 + 后续反复参考 → 现在建（slug 由 web-index 生成）` / `Twilio：只需确认能否发短信 → 直接查` / `OpenAI Assistants：方案未定 → 登记待建`。

### Step 6：需求转译

根据确认后的方向，将需求转译为需求清单。**只关注需求实现后的具体效果，不关心如何实现**。若 Step 5.5 判定为"条件可行"或"不可行"，转译时需在对应需求上**标注可行性约束**（前置条件、技术风险、需先验证项）。输出以下结构：

> **图示回扣（情况 B/C 必做）**：Step 5 判定为情况 B（方案部分有效）或情况 C（治标不治本）、且方向已按替代方案调整时，**Step 3 的预期图已过时**——必须在转译前**重绘预期图**（现状图不变），使变更点表与最终方案一致。否则报告内图与清单互相矛盾，下游会按被否决的旧图理解。重绘后旧图作废、不并存。

```markdown
## 需求清单

### 需求拆分

| 优先级 | 需求 ID  | 需求描述 | 预期效果 | 变更点 | 依赖 | 验收标准 |
|--------|----------|----------|----------|--------|------|----------|
| P0     | REQ-01   | ...      | ...      | 步骤2：同步写库→异步 | -    | ...      |
| P1     | REQ-02   | ...      | ...      | 新增"完成通知"环节 | REQ-01 | ...    |
| P2     | REQ-03   | ...      | ...      | -      | -    | ...      |

- **P0（核心）**：缺这个功能无法运转
- **P1（增强）**：显著提升体验或效率
- **P2（锦上添花）**：有更好，没有也能用
- **变更点**：该需求对应「现状 → 预期」图中的哪个元素/步骤（与 §2.10 图元、变更点表一致，便于追溯"这条需求动了哪一块"）；**本次无图或该需求不改变形状时填 `-`**，远期需求表不填此列

[如为情况 B，额外列出远期需求]

| 阶段 | 需求 ID | 需求描述 | 预期效果 | 依赖 | 验收标准 |
|------|---------|----------|----------|------|----------|
| 远期 | REQ-F01 | ...      | ...      | ... | ...      |

### 需求依赖图

[需求 ≥3 条时用 Mermaid 画图；≤2 条直接用文字说明依赖关系]

```mermaid
flowchart LR
    REQ01[REQ-01 用户注册优化] --> REQ02[REQ-02 注册引导完善] --> REQ03[REQ-03 注册转化提升]
```

**依赖关系说明**：
- REQ-02 依赖 REQ-01（优化注册流程后才能完善引导）
- REQ-03 依赖 REQ-01、REQ-02（需要整体体验提升才能提升转化）

**功能重叠**：
- 无

### 需求验证标准

| 需求 ID | 验证方式 | 验证指标 | 验证时机 |
|---------|----------|----------|----------|
| REQ-01 | 用户验收 | 注册流程步骤减少 50% | 开发完成后 |
| REQ-02 | 用户验收 | 引导完成率提升至 80% | 用户测试阶段 |
| REQ-03 | 数据分析 | 注册转化率提升至 30% | 上线后 1 周 |

### 成功度量指标

| 度量维度 | 指标名称 | 当前基线 | 目标值 | 度量方式 |
|----------|----------|----------|--------|----------|
| 用户体验 | 注册流程满意度 | 3.5/5 | 4.5/5 | 用户满意度调查 |
| 效率 | 注册完成时间 | 3 分钟 | <1 分钟 | 行为日志分析 |
| 业务指标 | 注册转化率 | 20% | 30% | 数据分析 |
| 业务指标 | 注册完成率 | 60% | 80% | 数据分析 |

### 非功能性约束

列出用户体验、数据安全、合规性等方面的约束（不涉及技术实现）。
```
（潜在风险与注意事项属报告 §5 独有章节，见「报告模板」，此处不重复输出）

### Step 6.5：需求确认与细化

需求转译完成后，先请用户确认整体需求清单是否正确。确认后，对每个需求进行深度细化，因为需求可能比表面看起来更复杂。

**统一确认模板**（6.5.1 与 6.5.3 共用，检查项按场景替换）：

```markdown
## {标题}确认

以上是基于{来源}的{对象}，请确认：
1. {检查项1}？  2. {检查项2}？  3. {检查项3}？  4. {检查项4}？

请确认以上内容是否准确？如有补充或修改请直接指出。
```

- **6.5.1 检查项**（需求清单确认）：需求完整性、优先级合理性、依赖关系准确性、验收标准清晰可测量
- **6.5.3 检查项**（细化结果确认）：细节完整性、优先级调整、验收标准补充、风险识别

#### 6.5.1 需求清单确认

首先输出需求清单摘要，按统一确认模板（使用 6.5.1 检查项）请用户确认。

#### 6.5.2 需求深度细化

用户确认后，对每个需求进行深度细化。需求往往比表面描述更复杂，需要考虑更多细节。**注意：只输出对该需求有价值的细化内容，避免无意义的模板填充。重点关注用户可能需要修改或确认的细节，省略那些无实际价值的部分。**

```markdown
## 需求深度细化

### REQ-XX：[需求名称]

#### 细化方向
- **验收标准**：[明确验收条件与边界]
- **异常场景**：[关键异常处理]
- **用户体验**：[核心交互流程]
- **性能要求**：[如有明确要求]
- **安全权限**：[如有明确要求]
- **兼容性**：[如有特殊要求]
- **扩展性**：[如有扩展需求]
- **依赖约束**：[外部依赖或限制]
- **使用场景**：[现实场景体验、未来扩展场景、场景切换与边界、场景覆盖完整性]

---
```

#### 6.5.3 细化结果确认

对每个需求细化完成后，沿用统一确认模板（使用 6.5.3 检查项）请用户确认。

#### 6.5.4 迭代规则

- 每个需求的细化最多迭代 2 次
- 如果用户多次纠正（超过 2 次），建议用户重新描述该需求
- 细化过程中发现的新需求，需要重新评估优先级并加入清单

### Step 6.6：复杂度评估与快速实现判断

需求确认与细化完成后，进行复杂度评估，判断是否可以跳过设计文档直接快速实现。

#### 6.6.1 复杂度评估维度

从以下维度评估需求复杂度：

| 评估维度 | 低复杂度特征 | 中复杂度特征 | 高复杂度特征 |
|----------|--------------|--------------|--------------|
| **技术难度** | 使用现有技术栈，无新技术挑战 | 涉及部分新技术，但可参考现有实现 | 涉及未使用过的技术，需要技术验证 |
| **范围大小** | 单个模块/页面，改动范围小 | 涉及 2-3 个模块，有中等影响 | 涉及多个模块/系统，影响广泛 |
| **依赖关系** | 无外部依赖，或依赖已就绪 | 依赖 1-2 个外部系统，需协调 | 依赖多个外部系统或团队 |
| **需求清晰度** | 需求明确，验收标准清晰 | 需求基本明确，部分细节需确认 | 需求存在不确定性，需要探索 |
| **时间约束** | 无紧迫 deadline，有充足时间 | 有一定时间压力，但可规划 | 紧急需求，需要快速交付 |
| **风险程度** | 风险低，失败影响小 | 中等风险，需控制 | 高风险，失败影响大 |

> **与 Step 5.5 的边界**：技术风险、依赖可行性已在 Step 5.5 可行性分析中评估。此处侧重**工作量与范围**判断（是否可跳过设计阶段快速实现），不重复评估可落地性。若 5.5 已判定"不可行"或"条件可行"，此处直接按高复杂度处理并推荐设计/验证类行动。

#### 6.6.2 复杂度评分

根据评估维度，统计高维度数（H）和中维度数（M），按以下**互斥规则**计算复杂度评分（从高到低判断，命中即止）：

- **高复杂度**：H ≥ 2，或（H = 1 且 M ≥ 3）
- **中复杂度**：H = 1 且 M < 3，或（H = 0 且 M ≥ 2）
- **低复杂度**：H = 0 且 M ≤ 1

#### 6.6.3 快速实现可行性判断

基于复杂度评分直接判断，不再附加额外条件：

- **可快速实现**：复杂度评分为**低**
- **不可快速实现**：复杂度评分为**中或高**

#### 6.6.4 建议步骤生成

根据复杂度评估结果和需求特征，推荐最匹配的下一步行动。**不是所有行动都需要执行，而是根据需求的具体特征，有针对性地推荐 1-2 个最适合的下一步**。

**第一步：判断是否可快速实现**

- **可快速实现（低复杂度）** → 先调用 use_skill("expert-solution-workflow") 查询相关经验、解决方案或记忆复用已有资产，**默认调用 use_skill("plan-track") 建档**，再直接进入编码实现，跳过设计阶段（建档内容与降级见 8.1）
- **不可快速实现** → 进入特征匹配，推荐最合适的下一步

> **流程衔接**：本步骤为纯评估，不与用户交互。推荐结果写入报告 §4.8，并作为 Step 8 动态推荐菜单的排序依据，后续方向的选择统一在 Step 8 一次完成。

**第二步：需求特征匹配**

根据需求的具体特征，匹配最合适的下一步行动。每个需求只需匹配与其特征最相关的行动，无需全部执行：

| 需求特征 | 推荐行动 | 推荐理由 |
|----------|----------|----------|
| 需求条目多（≥3个P0需求）、范围大、涉及多模块 | **work-breakdown（工作项拆分）** | 需求范围大，拆分为独立工作项后可并行开发，提高效率 |
| 需求条目多、范围大、涉及多模块、**需多窗口并行** | **子需求拆分（requirement-split）** | 拆为独立子需求文档，供多个对话窗分别设计/实现，加速进度 |
| 存在大量用户交互、UI流程复杂、多角色操作 | **interaction-design（交互设计）** | 交互流程复杂，需先理清用户操作流程再设计实现 |
| 涉及复杂数据结构、多系统数据流转、数据一致性要求 | **data-flow-model（数据流设计）** | 数据关系复杂，需先明确数据模型和流向 |
| 技术实现复杂、涉及多模块改动、架构选型不明确 | **design-craft（技术设计）** | 技术方案不明确，需先进行技术设计再编码 |
| 涉及未使用过的技术/API、性能敏感路径、第三方集成 | **demo-verify（验证原型）** | 存在技术风险，需先验证可行性再投入开发 |

**匹配规则**：
1. 一个需求可能同时命中多个特征，按以下**优先级排序**选出最相关的 2 个：
   - 优先级 1：技术风险类（demo-verify）— 存在技术不确定性时优先验证
   - 优先级 2：范围类（子需求拆分 / work-breakdown）— 需求条目多时优先拆分；需多窗口并行 → 子需求拆分，单窗口分批实施 → work-breakdown
   - 优先级 3：数据类（data-flow-model）— 数据关系复杂时优先设计
   - 优先级 4：交互类（interaction-design）— 交互流程复杂时优先设计
   - 优先级 5：技术类（design-craft）— 技术方案不明确时优先设计
2. 最多推荐 2 个行动，避免信息过载
3. 如果命中多个特征且特征间有依赖关系，说明执行顺序
4. 推荐必须给出具体理由，说明为什么这个行动对这个需求最合适
5. **兜底规则**：如未命中任何特征（中复杂度但无突出特征），推荐 **design-craft（技术设计）** 作为默认行动，理由为"需求有一定复杂度但无突出风险点，建议进行简要技术设计后再开发"

**推荐示例**：

> 示例 1：需求条目多但交互简单
> - 推荐：work-breakdown（工作项拆分）
> - 理由：本需求包含 5 个 P0 需求，涉及 3 个模块，范围较大。交互流程简单，无需先做交互设计。建议先拆分为独立工作项，再逐个进入技术设计。

> 示例 2：数据流复杂 + 技术复杂
> - 推荐：data-flow-model（数据流设计）→ design-craft（技术设计）
> - 理由：本需求涉及 3 个系统间的数据同步，数据一致性要求高。同时技术实现涉及架构调整。建议先设计数据模型和流向，再进行技术设计。

#### 6.6.5 输出格式

```markdown
## 复杂度评估与快速实现判断

**综合复杂度**：[低/中/高]（附 6.6.1 六维度评分表：维度 | 评分 | 说明）
**快速实现可行性**：[可快速实现 / 不可快速实现]

### 建议下一步
**命中的需求特征**：
- [特征1：例如"需求条目多，涉及多模块"] → 推荐：[行动]
- [特征2：例如"交互流程复杂"] → 推荐：[行动]（如有）

**推荐行动**：[行动名称]
**推荐理由**：[为什么这个行动对这个需求最合适]
（可快速实现时推荐"先查询专家团复用资产 → 默认建档跟踪 → 直接编码"，无需设计阶段）
```

写入报告 §4.8，并作为 Step 8 推荐菜单的排序依据。

### Step 7：输出完整需求挖掘报告

将确认结果、根本性分析、转译结果合并为一份结构化 Markdown 文档输出。

### Step 7.5：索引文件维护与过时文档归档

输出报告后，AI 应主动检查需求目录的文档状态：

#### 7.5.1 生成/更新索引文件

在需求目录下维护 `index.md`（标题「{需求名称} 文件索引」，内容为目录树 + 每个文件一句话说明）：

- **收录**：所有非归档目录下的文件与目录（`requirement.md`、`design/`、`api/`、`review/`、`test/` 等）
- **不收录**：`archive/` 下任何文件（已归档即不活跃）
- **必收录**：`assets/` 图形目录——图是需求报告的组成部分，丢了 §2.10 就是空白
- **时机**：每次生成报告或更新文档后同步更新

#### 7.5.2 检查并归档过时文档

在生成索引文件的同时，AI 应检查是否有过时文档需要归档：

**检查条件**：
1. 文档内容与当前需求明显不符（如设计已重构、需求已变更）
2. 文档版本过旧且有更新版本存在
3. 文档被标记为"废弃"或"待归档"

**归档操作**：
```bash
# 归档单个文档（路径相对需求目录）
req archive {REQ-NNN} --doc {path/to/outdated-doc.md} --reason "文档已过时，新版本已生成"

# 示例
req archive REQ-20260723-001 --doc design/old-design.md --reason "设计已重构，新版在 design/DESIGN.md"
```

**归档后处理**：
- 从 `docs` 列表中移除归档文档
- 更新 `index.md` 索引文件
- 在 changelog 中记录归档操作

> **重要**：归档操作应谨慎执行，仅在确认文档确实过时且不影响当前分析时进行。如有疑问，建议先与用户确认。

### Step 8：后续行动选择

需求挖掘报告输出完成后，基于 Step 6.6 的评估结果**动态生成**推荐排序菜单，提示用户选择后续行动：

```text
🚀 后续行动选择
━━━━━━━━━━━━━━━━

需求挖掘已完成，报告已输出。
综合复杂度：[低/中/高]

📌 推荐行动（基于复杂度评估与需求特征，越靠前越推荐）：

1. ⭐ [推荐行动1]
   理由：[来自 6.6.4 特征匹配的具体理由]
2. ⭐ [推荐行动2]（如有）
   理由：[...]

📋 其他可选行动：

3. 📁 落盘归档 — 将需求挖掘报告保存到 .requirements/ 目录
4. [其余未推荐的行动，每个一行：行动名 — 一句话说明]
...
N. ⏭️ 跳过 — 不进行后续操作，结束需求挖掘流程

请选择 [1..N]：
```

**菜单生成规则**：

1. **推荐区**（1-2 项，越靠前越推荐）：
   - 低复杂度 → 「🚀 快速实现」固定为推荐第 1
   - 中/高复杂度 → 放入 6.6.4 特征匹配命中的 1-2 个行动，按其优先级排序（含兜底规则命中的 design-craft）
2. **其他可选区**：「📁 落盘归档」固定为该区首位；其余未被推荐的行动各占一行，候选池：快速实现、子需求拆分（requirement-split）、工作项拆分（work-breakdown）、交互设计（interaction-design）、数据流设计（data-flow-model）、技术设计（design-craft）、验证原型（demo-verify）。中/高复杂度时「快速实现」仍列入本区供用户选择，选中后按 8.1 的复杂度防呆分支处理
3. 「⏭️ 跳过」永远是最后一项；选项编号按实际生成顺序连续排列
4. 每个推荐项必须附带 6.6.4 输出的具体推荐理由，不得只给行动名

#### 8.1 快速实现（跳过设计文档）

**第一步：默认建档（本路径的唯一台账）**

用户选择快速实现 → **默认调用 use_skill("plan-track")** 建档，再按下方分支执行（中/高复杂度分支的建档时机见下方「时机」）。本路径跳过设计文档，执行进度与验证证据没有其他载体；plan-track 的「证据绑定」正对"改完就宣称完成"（未验证只能标「已改未验」）。

建档内容**全部取自本报告**，不额外设计：

| 台账项 | 取值 |
|--------|------|
| 工作项 | §4.1 需求清单 REQ-*（报告未落盘同样可用；无清单时现场粗拆 3-8 项） |
| 完成判据 | §4.4 需求验证标准 |
| `related` | 需求 ID（未落盘则填需求名） |

- **时机**：中/高复杂度分支在「仍坚持直接实现」（含未回应时的默认处理）确认后再建档——先告知风险、后建档，避免方向改走设计后留下废弃档案
- **降级**：`plan-track` 未安装 → 跳过建档、直接编码，不阻塞流程
- **可跳过**：命中其「不建档」场景（单文件小改 / 文案 typo / 单步问答 / 纯咨询），或用户说"不用建计划" → 不建档，不阻塞
- **唯一活台账**：后续走 `work-breakdown` 拆分时，拆分结果并入本台账，不另立平行计划

建档后按 `plan-track` 流程执行（更新 → 完成自评审 → 收尾），本节不复述。

**第二步：按复杂度评估结果处理**

**可快速实现（低复杂度）**：
1. 先调用 use_skill("expert-solution-workflow") 查询可复用资产（查询失败或不可用则忽略继续）；找到则加载（契约层等）以专家视角编码，未找到则直接进入编码
2. 编码前确保验收标准清晰
3. 编码后补简单单元测试并快速迭代验证

**不可快速实现（中/高复杂度）**：
> 当前需求复杂度较高，不建议跳过设计阶段。请优先选择 Step 8 菜单推荐区的行动（来自 Step 6.6 特征匹配）。
> **注意**：如推荐 action 为 `design-craft`（技术设计），design-craft 内部会自动执行专家团查询，无需在本阶段重复调用。

**用户仍坚持快速实现时**：
1. **提醒分批计划**：提示用户"当前需求复杂度较高、代码量较大，直接整体实现存在验证困难、返工成本高的风险，建议先创建分批实现计划"
2. **确认是否先拆分**：询问用户是否先创建分批实现计划
   - **确认创建** → 调用 `work-breakdown` 编写分批实现计划（拆分为独立垂直切片工作项）→ **拆分结果并入本步第一步已建的 `plan-track` 台账**（唯一活台账）→ 按计划分批实施：每个切片独立实现并验证，全部完成后整体联调；切片内如出现新的设计需求，再按需进入 design-craft
   - **仍坚持直接实现** → 尊重用户最终决定，直接进入编码实现，并标注风险（中途发现复杂度超预期时，可随时回头补拆分）
   - **用户未回应** → 默认按"仍坚持直接实现"处理并标注风险，不阻塞流程

#### 8.2 落盘归档

用户选择落盘归档时，引导用户确认落盘内容，然后按 **`requirement-doc-store`** skill 的「创建场景」流程执行：

1. 确认落盘：提示用户落盘内容为需求挖掘报告（`requirement.md`），确认后继续
2. 创建需求：使用 `req create` 命令创建目录并注册到 meta.json
3. 写入文档：使用 `write_to_file` 按 frontmatter 模板写入 `requirement.md`；**Step 3 的「现状 → 预期（图示）」节必须随正文落盘**——图内嵌代码块（Mermaid 标 `mermaid`，ASCII 不标语言），不得只留在对话、不得因"精简摘要"压缩而删图（压缩的是细节文字，不是图）；**如报告含 SVG 独立图形**，先写入需求目录 `assets/`（kebab-case 命名），md 内用 `![说明](./assets/xxx.svg)` 相对路径引用，并同步进 `index.md`——SVG 是 `requirement.md` 的附属资源，**不注册进 `docs`**（文档类型枚举无 diagram，硬塞会污染 meta.json）
4. 验证添加成功（必须执行）：落盘后使用 `req list --id {REQ-NNN}` 检查需求是否添加成功——确认条目存在、`feature`/`status`/`tags` 与创建参数一致、需求目录下 `requirement.md` 已写入。验证失败时根据错误信息修正后重试，禁止未验证通过就宣告落盘完成

> 详细步骤、frontmatter 模板和命令参数见 `requirement-doc-store` skill。

#### 8.3 技能类行动衔接

用户选择技能类行动后，**直接调用对应 skill 并传入需求挖掘报告，不再复述该行动的流程或内容**：

| 行动 | 调用 skill |
|------|-----------|
| 子需求拆分 | 加载本目录 `requirement-split.md`（内置能力，非独立 skill） |
| 工作项拆分 | `work-breakdown` |
| 交互设计 | `interaction-design` |
| 数据流设计 | `data-flow-model` |
| 技术设计 | `design-craft` |
| 验证原型 | `demo-verify` |

**衔接规则**：
- 传入内容：需求挖掘报告（核心目标、涉及角色、关键行为、需求清单、**含「现状 → 预期」图与变更点表**——图作为下游设计/交互/数据流的现状基线，避免下游从零重新理解；**界面类图须注明「已由用户确认」**，未确认的先补确认再接力，避免下游拿未定稿布局当基线）
- 下游 skill 执行完成后的后续提示由其自身负责，本 skill 不预写"输出衔接"文案

#### 8.4 跳过

用户选择跳过时，直接结束需求挖掘流程：

输出结束语：报告已输出、后续行动已跳过，如需继续可随时执行 8.3 表中任一行动（此处不再逐条列举，避免与 8.3 双写）。

## 报告模板（章节来源映射）

最终报告 = 各 Step 的模板输出按序拼接。**此处只定义映射关系与「报告独有章节」**，其余直接取对应 Step 的模板输出——重复定义必然双写不一致。

| 报告章节 | 来源 | 备注 |
|----------|------|------|
| §1 原始需求描述 | 独有（见下） | 用户原话原文引用 |
| §2 需求澄清（2.1-2.10） | Step 3 输出 | **§2.9 假设表须在 §2.10 图之前**（顺序硬约束）；Step 5 判定 B/C 时 §2.10 取重绘后版本 |
| §3 根本性分析（3.1-3.6） | Step 5 输出 | 3.4「用户体验提升」引用 §2.10 图，不重复文字描述 |
| §4 需求清单（4.1-4.9） | Step 6 + §6.6.5 + §5.5.2 | 4.1-4.6 取 Step 6 各小节；4.7 仅子需求拆分时填（见 `requirement-split.md`）；4.8 取 §6.6.5；4.9 取 §5.5.2（含五字段） |
| §5 潜在风险与注意事项 | 独有（见下） | |
| §6 迭代建议（6.1-6.3） | 独有（见下） | |

> 小节与 Step 模板逐项对应（§2.1 需求形态 ← Step 3「需求形态」、2.2 功能本质 ← 「功能本质」，依此类推）；拼装时逐节核对，**不得漏节**。

### 报告独有章节

```markdown
## 1. 原始需求描述
> 用户原始描述原文

## 5. 潜在风险与注意事项
[列出用户体验层面可能的问题、容易忽略的边界情况]

## 6. 迭代建议
### 6.1 反馈收集计划
- 收集方式：[用户访谈/行为分析/满意度调查]
- 收集频率：[每周/每月/每次使用后]
- 收集渠道：[应用内反馈/邮件/客服]

### 6.2 迭代规划
| 阶段 | 阶段目标（一句话） | 覆盖需求 ID | 预期效果（用户可感知的状态变化） | 进入下一阶段条件 |
|------|-------------------|-------------|--------------------------------|------------------|
| 一 | [核心链路跑通] | [§4.1 的 P0 需求 ID] | [现状 → 预期，如：导出点了没反应 → 30s 内收到文件且可查进度] | [核心场景验收通过/关键假设已验证] |
| 二 | [体验优化] | [§4.1 P1 + 反馈驱动需求] | [现状 → 预期] | [§6.1 反馈中的高频痛点已解决] |
| 三 | [扩展与规模化] | [§4.2 远期需求 ID] | [现状 → 预期] | [§4.5 成功度量指标达标] |

> **写法约束**：① 「预期效果」写**用户视角的状态变化**（对齐 §4.1「预期效果」列口径），不写"完成 XX 模块开发"这类任务措辞；② 「覆盖需求 ID」必须来自 §4.1/§4.2，出现无需求支撑的阶段 = 需求遗漏或阶段虚构，须补需求或删阶段；③ 「进入下一阶段条件」须可判定，能挂钩 §4.4 验证标准或 §4.5 度量指标的优先挂钩，写不出可判定条件说明该阶段目标不成立。

### 6.3 长期演进建议
- [基于根因分析，建议的长期系统演进方向]
```

> **持久化时的文档结构**：实际写入 `requirement.md` 时的格式为精简摘要（见 `requirement-doc-store` skill），而非上述完整报告模板——但**「现状 → 预期（图示）」节必须完整保留**（Mermaid / ASCII 内嵌代码块），落盘时不得删图，压缩只压文字细节。

## 图形化表达规范（SSOT: [references/diagram-guide.md](references/diagram-guide.md)）

需求阶段出图的**全部规则**（选型表、变更面信号、三种差分画法、ASCII 绘制约束、诚实闸门、边界闸门、成本闸门、样式约束、反模式）见 reference。此处只留执行时必须记住的六条：

1. **何时画**：命中「执行流程 / 数据流 / UI / 状态流转」任一变更面 → 在 **Step 3 确认假设时就出图**（不是等到最终报告）。纯性能、兼容性、文案、权限类**不出图**
2. **用什么画**：流程/数据流/状态 → **Mermaid**（默认）；UI 界面与终端输出 → **ASCII**（UI 必须走 `use_skill("ui-to-ascii")` 的「界面确认闸门」，确认后才可进入下游）；仅当已落盘且 mermaid 讲不清 → SVG 独立文件入 `assets/`
3. **画什么**：只画「变什么」——用户操作步骤、业务数据流向、界面布局、状态迁移的效果层变化；**不画**技术架构、表结构、接口时序（属 `design-craft` / `data-flow-model` / `interaction-design`）
4. **现状不臆造**：现状图必须标注来源三态（用户提供 / 读代码确认 / ⚠️ AI 推断）；**推断部分须挂到假设 ID**，假设表中尚无对应条目则**新增一条**（如 H-05「现状导出为同步阻塞」）——否则"挂 H-xx"无处可挂；拿不准画骨架 + `[待确认]`；现状完全不可知时**只画预期图**并注明"现状待确认"
5. **图后必附变更点**：图下方给「变更点 | 现状 | 预期 | 类型 | 关联假设」表或编号锚点说明，并在需求清单「变更点」列回填；**反向校验——图上每个变更点都应至少对应一条需求**，找不到归属说明需求遗漏（补需求，或明确标注该变更点不由本批实现）
6. **成本闸门**：图 ≤ 3 组，UI ASCII 每屏 ≤ 38 字符（并排 ≤ 80），浅底深字、mermaid 不启用深色主题；**图比重超过文字即为失败**，退回文字。**尺寸口径**：报告内联的对照图沿用本节约束；作为界面确认闸门单独交付的图按 `ui-to-ascii` 规范（单屏 ≤ 80 字符）

> **与 `ui-to-ascii` 的分工**：用户粘贴 UI 设计稿要求**存档** → 走其模式 A；界面变更需要出 ASCII 并确认 → 走其「界面确认闸门」（模式 B，**强制**）。本 skill 的需求侧「现状 → 预期」图是**确认用的效果层对照**，与 ui-to-ascii 的界面布局图可用同一张图（避免重复画两遍）。

## 参考

完整示例见 [references/example.md](references/example.md)；图示画法详规与反模式见 [references/diagram-guide.md](references/diagram-guide.md)

## 行为边界

以下只列**正文未覆盖或非显性**的约束。Step 内已有的硬约束（可行性分析、复杂度评估、图形化六条、索引维护与归档、快速实现查资产与建档等）见对应章节，**此处不重复**：

- **不做价值判断，但做方案判断**：不评价"这个需求值不值得做"，但必须评价"这个方案能不能从根本上解决问题"
- **不替代需求评审**：输出的是分析报告，不是最终方案。需要人工评审确认
- **不编造不存在的信息**：推理必须基于用户原描述，不得凭空添加需求细节
- **方案质疑要有逻辑链**：当指出方案治标不治本时，必须给出清晰的因果逻辑，不能凭感觉否定
- **最终决定权归用户**：即使判定为"情况 C（治标不治本）"，用户仍可选择坚持原方案。遵从用户决策进行后续转译
- **处理多需求混合**：如果用户一次性提出多个不相关的功能需求，先请用户挑一个最优先的深入挖掘，不要混在一起处理
- **元数据管理**：需求文档的 frontmatter 和 meta.json 必须通过 `req` 命令操作（`req create` / `req update`），禁止手动拼接路径写入。命令保证原子性与并发安全
- **持久化后验证**：任何创建或更新操作（含 `req update --docs add`）后，必须用 `req list --id {REQ-NNN}` 检查是否成功（条目存在、字段与预期一致）；验证失败时修正重试，禁止未验证通过就宣告完成