从用户的功能描述中深度挖掘真实需求，打穿表象找到根因，转译为可落地的技术需求清单，并在分析阶段就用「现状 → 预期」图示（Mermaid 流程 / ASCII 界面）呈现流程、数据流、UI 的变化。采用"先推理后确认"模式。适用场景：用户提出功能描述/改善诉求、抱怨问题、性能反馈、探索性提问，需从原始需求理清动机和场景，或需在需求分析阶段看清改动前后流程/数据流/界面对比时（单纯"把图画出来/把设计稿转文本"属 ui-to-ascii、archify）。
Scanned 9/20/2026
Install to Claude Code
Skills Directorynpx -y skills add HACK-WU/skills --skill requirement-mining --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Requirement Mining?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/hack-wu-requirement-mining)More formats (shields.io, HTML) on the badges page.
---
name: requirement-mining
description: 从用户的功能描述中深度挖掘真实需求，打穿表象找到根因，转译为可落地的技术需求清单，并在分析阶段就用「现状 → 预期」图示（Mermaid 流程 / ASCII 界面）呈现流程、数据流、UI 的变化。采用"先推理后确认"模式。适用场景：用户提出功能描述/改善诉求、抱怨问题、性能反馈、探索性提问，需从原始需求理清动机和场景，或需在需求分析阶段看清改动前后流程/数据流/界面对比时（单纯"把图画出来/把设计稿转文本"属 ui-to-ascii、archify）。
---
## 概述
**目的**：从用户功能描述中深度挖掘真实需求，打穿表象找到根因，将产品需求转译为可落地的技术需求清单
**功能**：
- 自主推理用户真实动机与场景，识别"伪装成需求的解决方案"
- 批判性评估方案根本性，提供短期/长期建议
- 需求转译为结构化需求清单（优先级、依赖、验收标准）
- **图形化表达变化**：涉及流程/数据流/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)）
- **假设可验证**：关键假设必须可验证，验证难度需评估
- **最小化交互**：理想情况仅 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 输出假设时附「现状 → 预期」图示；命中多类优先画最主要的一类，其余有独立价值的各出 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 / - |
> **顺序硬约束**：假设表在前、图在后。图中每个"⚠️ AI 推断"必须引用**上方已列出**的假设 ID；画图时若发现缺少对应假设（如"现状为同步阻塞"），**先补进假设表再引用**，禁止引用不存在的 H-xx。
---
请确认以上理解是否准确？如有偏差请直接指出，我会更新理解。
```
### 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`；**如报告含 SVG 独立图形**，先写入需求目录 `assets/`（kebab-case 命名），md 内用 `` 相对路径引用，并同步进 `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），而非上述完整报告模板。
## 图形化表达规范（SSOT: [references/diagram-guide.md](references/diagram-guide.md)）
需求阶段出图的**全部规则**（选型表、变更面信号、三种差分画法、ASCII 绘制约束、诚实闸门、边界闸门、成本闸门、样式约束、反模式）见 reference。此处只留执行时必须记住的六条：
1. **何时画**：命中「执行流程 / 数据流 / UI / 状态流转」任一变更面 → 在 **Step 3 确认假设时就出图**（不是等到最终报告）。纯性能、兼容性、文案、权限类**不出图**
2. **用什么画**：流程/数据流/状态 → **Mermaid**（默认）；UI 界面与终端输出 → **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 设计稿要求**存档**时，转 `ui-to-ascii` skill；本 skill 只做需求侧的轻量双屏对照。
## 参考
完整示例见 [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}` 检查是否成功（条目存在、字段与预期一致）；验证失败时修正重试，禁止未验证通过就宣告完成
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
