name	hs-req-facilitator-skill
description	Use this skill when users want to analyze, clarify, or improve requirements documents. Works well for projects with unclear requirements, missing specifications, or multiple requirement documents that need consolidation. Automatically generates spec-workflow format requirements documents. Activate when users mention "requirements", "specifications", "analyze needs", or "clarify ambiguous requirements".
type	configuration-driven
implementation	mcp-services
version	2.0.4
author	Suzhou Heshuo Intelligent Technology Co., Ltd.
email	limian@norkern.com
website	www.norker.com
company	Suzhou Heshuo Intelligent Technology Co., Ltd.
mcp-services	["spec-workflow"]

HS Req Facilitator Skill

智能需求分析助手 | Intelligent Requirements Facilitator

🤖 开源项目: hs-req-facilitator-skill v2.0.4
👤 苏州核朔智能科技有限公司 | 📧 limian@norkern.com
🌐 www.norkern.com | 📖 文档: README.md

启动流程：激活技能后立即开始执行工作流程

🚀 启动步骤

工作流检查点：按以下顺序执行每个步骤，完成验证后进入下一步

执行规范：

执行启动流程：不要只显示"技能已启动"或"等待指令"等消息
立即开始：技能激活后立即开始工作流程，避免停顿等待
执行顺序：按照步骤顺序执行，确保每步完成并验证

启动后立即执行：

执行步骤0检查（确认工作流规则）
执行步骤1：扫描代码和文档
根据扫描结果决定流程并继续执行

步骤0：工作流检查（首先执行）

执行前检查：确认以下工作流规则

Stage 2（需求分析）：完成以下4个子步骤（按顺序执行）：
- 步骤2.1：读取需求文档和代码文件
- 步骤2.2：理解项目功能（输出功能概述）
- 步骤2.3：分析问题和缺失信息（输出模糊点、缺失信息、不一致性）
- 步骤2.4：列出功能需求清单并展示给用户
Stage 3（交互澄清）：执行用户交互
- Stage 2完成后，立即进入Stage 3
- 与用户交互（获取补充信息）
- 即使没有发现问题，也至少进行一次用户交互
用户交互要求：
- 使用AskUserQuestion：必须使用 AskUserQuestion 工具调用
- 等待回答：等待用户回答后再继续，不要直接进入下一步
- 确保交互：在提问后实际等待用户回答
Stage 2 验证要求（全部满足）：
- 步骤2.2输出：项目功能概述、每个需求的实际功能、代码与需求一致性分析
- 步骤2.3输出：模糊点识别结果、缺失信息识别结果、不一致性识别结果（每个类别至少1个或明确说明"无"）
- 输出具体分析结果：不要只是说"已理解"或"未发现问题"
- 步骤2.4输出完整的功能需求清单并展示给用户

步骤1：扫描代码和文档（第一步）

执行步骤：技能启动后立即执行此步骤

立即执行以下命令并查看结果：

# 1. 扫描需求文档
find . -type f \( -name "requirements.md" -o -name "*requirement*.md" -o -name "需求*.md" \) | grep -v node_modules | grep -v ".git"

# 2. 扫描代码文件
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" \) | grep -v node_modules | grep -v ".git" | head -50

统计结果：

需求文档数量：[X]
代码文件数量：[Y]

📋 Stage 1: 根据扫描结果决定流程

选择流程：根据扫描结果决定执行哪个流程

空项目（没有需求文档）：
- 使用 AskUserQuestion 询问用户是否要创建需求文档
- 详细指南：参见项目文档中的空项目引导相关章节
多个需求文档：
- 使用 AskUserQuestion 询问用户是否要合并需求文档
- 如果用户同意，进入Stage 5（需求文档合并）
- 详细指南：参见项目文档中的文档合并相关章节
有需求文档（常规流程）：
- 直接进入Stage 2（需求分析），不需要先询问用户
- 完成Stage 2后，再进入Stage 3（交互澄清）

📋 Stage 2: 需求分析（在交互澄清之前完成）

执行顺序：按以下顺序执行每个步骤

读取需求文档和代码文件
理解项目功能
分析问题和缺失信息（在列出功能需求清单之前完成）
列出功能需求清单（在分析完成后列出并展示给用户）

完成阶段2后，进入阶段3（交互澄清）

流程检查点：

✅ Stage 2完成后 → 进入Stage 3（交互澄清）
✅ Stage 3完成后 → 进入Stage 4（需求完善）
跳过禁止：Stage 2 → 直接进入Stage 4（跳过Stage 3）

📋 使用场景

Use this skill when:

User asks to "analyze requirements" or "review specifications"
User mentions "unclear requirements" or "ambiguous specifications"
User wants to "consolidate multiple requirement documents"
User needs to "identify missing information" in requirements
User says "improve requirements quality" or "enhance specifications"
Working with requirements files (*requirements.md, requirement.md)
Queries contain keywords: "requirements", "specs", "needs analysis", "clarify"

典型触发场景：

"完善需求"
"分析需求文档"
"澄清不明确的需求"
"合并需求文档"
"识别缺失信息"
"提升需求质量"

🔄 工作流程

📊 工作流程图

┌─────────────────────────────────────────────────────────────────────────────┐
│                          HS-REQ-FACILITATOR 工作流程                          │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐
│   Stage 0       │ ◄─── 工作流检查（首先执行）
│  工作流检查      │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   Stage 1       │ ◄─── 扫描代码和文档（必需，第一步）
│    扫描          │
│  ├─需求文档      │
│  └─代码文件      │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   决策点 1       │ ◄─── 根据扫描结果决定流程
│  (Scan Results) │
└───────┬─────────┘
        │
        ├─────────────────────────────┬─────────────────────────────┐
        │                             │                             │
        ▼                             ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  空项目流程      │         │  多文档流程      │         │  常规流程        │
│  (Empty Project)│         │  (Multi-Docs)   │         │  (Regular)      │
└───────┬─────────┘         └───────┬─────────┘         └───────┬─────────┘
        │                         │                             │
        ▼                         ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AskUserQuestion│         │  AskUserQuestion│         │  直接进入        │
│  "创建需求文档?" │         │  "合并需求文档?" │         │  Stage 2        │
│  ↓             │         │  ↓             │         │                 │
│  [EMPTY-PROJECT]│        │  [同意] ───────→│         │  需求分析        │
│                 │         │  Stage 5       │         │  (MANDATORY)    │
│                 │         │  文档合并       │         │                 │
└─────────────────┘         │                 │         │  ┌─────────────┐
                            └─────────────────┘         │  │ Stage 2.1   │
                                                          │  ├─读取文档    │
                                                          │  └─读取代码    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.2   │
                                                          │  ├─理解功能    │ ◄─── 必须输出项目概述
                                                          │  └─需求分析    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.3   │
                                                          │  ├─模糊点识别  │ ◄─── 必须输出分析结果
                                                          │  ├─缺失信息    │
                                                          │  └─不一致性    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.4   │
                                                          │  ├─需求清单    │ ◄─── 必须展示给用户
                                                          │  └─需求分类    │
                                                          │
                                                          └────────┬────────┘
                                                                   │
                                                                   ▼
                                                          ┌─────────────────┐
                                                          │   Stage 3       │ ◄─── 关键检查点（不能跳过！）
                                                          │  交互澄清        │
                                                          │                  │
                                                          │  🔴 关键阶段     │ ◄─── 不能跳过！
                                                          │                  │
                                                          └────────┬─────────┘
                                                                   │
                                                                   ▼
                                                          ┌─────────────────┐
                                                          │ AskUserQuestion │ ◄─── 必须使用AskUserQuestion工具
                                                          │     工具        │
                                                          │                  │
                                                          │ ├─检测工具可用性 │
                                                          │ ├─生成澄清问题   │
                                                          │ ├─等待用户回答   │ ◄─── 必须等待用户回答！
                                                          │ └─收集回答       │
                                                          └────────┬─────────┘
                                                                   │
                                ┌────────────────────────────────────┘
                                │
                                ▼
                      ┌─────────────────┐
                      │  错误处理流程     │
                      │  (Error Handler) │
                      │                  │
                      │ ├─工具不可用      │ ◄─── 降级到对话方式
                      │   ↓              │
                      │ └─❓ 格式交互     │
                      │                  │
                      │ ├─无响应         │ ◄─── 继续重试
                      │   ↓              │
                      │ └─再次询问       │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │   Stage 3       │
                      │   继续执行       │
                      │                  │
                      │ ├─调整问题       │
                      │ ├─持续交互       │ ◄─── 至少一次交互
                      │ └─完成澄清       │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │   Stage 4       │ ◄─── 条件：Stage 3完成后
                      │  需求完善        │
                      │  (Optional)     │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │ Spec-Workflow   │
                      │   集成          │
                      │                  │
                      │ ├─检测项目结构    │
                      │ ├─生成需求文档    │
                      │ └─更新规格       │
                      └─────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              流程说明                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  🔴 关键阶段: Stage 3 是关键阶段，不能跳过                            │
│                                                                             │
│  🔵 AskUserQuestion: 必须使用 AskUserQuestion 工具与用户交互                 │
│     - 如果工具可用：使用 AskUserQuestion 工具                               │
│     - 如果工具不可用：降级到对话方式（❓ 格式）                              │
│                                                                             │
│  ✓ 检查点: 关键检查点，等待用户回答后才能继续                      │
│                                                                             │
│  📋 DECISION POINTS:                                                       │
│     1. 扫描结果 → 空项目/多文档/常规流程                                    │
│     2. Stage 2 → 必须完成所有4个子步骤                                      │
│     3. Stage 3 → 交互澄清（至少一次交互）                                │
│     4. Stage 4 → 必须在Stage 3完成后执行                                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Stage 1: 根据扫描结果决定流程

根据步骤1的扫描结果，决定执行哪个流程：

空项目（没有需求文档）：
- 使用 AskUserQuestion 询问用户是否要创建需求文档
- 详细指南：参见项目文档中的空项目引导相关章节
多个需求文档：
- 使用 AskUserQuestion 询问用户是否要合并需求文档
- 如果用户同意，进入阶段5（需求文档合并）
- 详细指南：参见项目文档中的文档合并相关章节
常规流程（有需求文档）：
- 直接进入Stage 2（需求分析），不需要先询问用户
- 完成Stage 2后，再进入Stage 3（交互澄清）

Stage 2: 需求分析（必须在交互澄清之前完成）

执行要求：此阶段按以下顺序执行，每个步骤输出明确结果，完成后进入Stage 3（交互澄清）！

执行前检查：在开始Stage 2之前，确认已执行步骤1（扫描代码和文档）并获得扫描结果！

步骤2.1：读取需求文档和代码文件（必须执行）

执行要求：实际读取文件，不能跳过：

查找并读取需求文档：

# 必须执行：查找需求文档
find . -type f \( -name "requirements.md" -o -name "*requirement*.md" -o -name "需求*.md" \) | grep -v node_modules | grep -v ".git"

# 必须执行：读取找到的需求文档
# 使用 Read 工具读取每个找到的需求文档

读取关键代码文件：

# 必须执行：查找代码文件
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" \) | grep -v node_modules | grep -v ".git" | head -20

# 必须执行：读取关键代码文件（至少5-10个文件）
# 使用 Read 工具读取主要业务逻辑文件

如果项目使用 spec-workflow，获取上下文：
- 尝试使用 spec-workflow MCP 工具获取模板和上下文
- 如果MCP不可用，使用 spec-workflow CLI 或直接生成标准格式

验证点：实际读取文件内容，不能只是列出文件名！

步骤2.2：理解项目功能（关键步骤，不能跳过）

重要步骤：先理解项目的实际功能，再分析缺失信息！

⚠️ 执行前检查：

步骤2.1已完成（已读取需求文档和代码文件）
已准备好开始理解项目功能

📌 核心要求：此步骤必须向用户展示项目功能概述！

⚠️ 重要：用户启动技能后，需要知道被分析的项目是什么、解决什么问题、主要功能和技术栈，这样才能理解后续的需求分析。

必须输出以下内容（每个部分都必须有具体输出并展示给用户，不能为空）：

项目整体功能描述（必须输出并展示给用户，不能只是说"已理解"）：

## 项目功能概述

基于读取的代码和文档，分析并回答：

### 1. 项目是什么？
[明确说明：这个项目是什么？它的核心功能是什么？]

### 2. 项目解决的问题
[明确说明：这个项目解决什么问题？为谁服务？]

### 3. 主要功能模块
[列出主要功能模块，每个模块说明其功能]
- 模块1：[功能描述]
- 模块2：[功能描述]
...

### 4. 项目技术栈
[列出项目使用的主要技术栈]

重要要求：

✅ 必须向用户展示这个项目功能概述，让用户了解被分析的软件是干什么的
✅ 输出明确的项目功能描述，不能只是说"已理解"
✅ 确保用户能够理解项目的基本情况后再继续分析

每个需求的实际功能（必须输出，必须分析每个需求）：

## 需求功能分析

基于对项目的理解，分析每个需求：

### 需求1: [需求标题或编号]
- **需求描述**：[需求文档中的原始描述]
- **实际功能**：[这个需求对应的实际功能是什么]
- **功能行为**：[这个功能做什么、怎么做、具体行为是什么]
- **输入输出**：[输入是什么、输出是什么、参数格式]
- **代码实现情况**：[代码中是否已实现、如何实现的、代码位置]
- **实现状态**：[已实现/未实现/部分实现]

### 需求2: [需求标题或编号]
...

**执行要求：分析所有需求，不能跳过任何需求！**

代码与需求的一致性（必须输出，必须对比代码和文档）：

## 代码与需求一致性分析

对比代码实现和需求文档：

### 代码中已实现但需求文档中未描述的功能
- 功能1：[功能名称]
  * 代码位置：[文件路径和行号]
  * 功能描述：[功能做什么]
  * 建议：[是否应该在需求文档中补充]

### 需求文档中描述但代码中未实现的功能
- 功能1：[功能名称]
  * 需求位置：[需求文档中的位置]
  * 功能描述：[需求描述的功能]
  * 状态：[计划实现/已废弃/待实现]

### 代码和需求一致的功能
- 功能1：[功能名称]
  * 需求位置：[需求文档中的位置]
  * 代码位置：[代码中的位置]
  * 一致性说明：[说明为什么一致]

验证点：输出明确的对比结果，不能只是说"已对比"！

扩展2.2.1：代码注释分析（自动提取隐含需求）

执行位置：在步骤2.2完成后，步骤2.3之前执行

功能说明：从代码注释中提取隐含的业务需求、技术约束、设计决策等文档中未明确说明的信息。

执行步骤：

步骤A：扫描代码注释

扫描所有支持的代码文件（.js, .ts, .py, .java, .go, .rs, .cpp, .c#）
提取所有注释内容（行内注释、块注释、文档注释）
识别注释中的关键词和模式

步骤B：分析注释内容 使用AI分析注释，提取以下类型的信息：

TODO/FIXME注释：未完成的功能或需要修复的问题
业务逻辑注释：解释为什么这样做的业务原因
技术决策注释：为什么选择特定技术或架构
约束说明注释：性能、安全、兼容性等约束
设计模式注释：使用的设计模式和意图
边缘情况注释：特殊处理逻辑和原因

步骤C：映射到需求类型 将提取的信息映射到标准需求类型：

功能需求：未实现的功能、预期行为
非功能需求：性能、安全、可靠性要求
约束条件：技术约束、业务规则
假设条件：隐含的假设和前置条件

输出格式：

## 代码注释分析结果

### 从代码注释提取的隐含需求

#### 功能相关注释
1. **[文件名:行号]** [注释摘录]
   - **提取的需求**：[描述]
   - **需求类型**：[功能/非功能/约束]
   - **优先级**：[P0/P1/P2]
   - **实现状态**：[已实现/未实现/部分实现]
   - **代码位置**：[具体位置]

#### 技术约束注释
1. **[文件名:行号]** [注释摘录]
   - **约束类型**：[性能/安全/兼容/其他]
   - **约束描述**：[具体要求]
   - **影响范围**：[影响的模块或功能]
   - **建议**：[如何处理]

#### 设计决策注释
1. **[文件名:行号]** [注释摘录]
   - **决策内容**：[做了什么决策]
   - **决策原因**：[为什么这样做]
   - **替代方案**：[考虑过的其他方案]
   - **影响**：[对系统的影响]

#### 待办事项注释
1. **[文件名:行号]** TODO: [内容]
   - **任务描述**：[需要做什么]
   - **优先级**：[高/中/低]
   - **预计工作量**：[大/中/小]
   - **关联功能**：[与哪个功能相关]

### 统计摘要
- 总注释数：[X]
- 发现隐含需求数：[Y]
- 其中功能需求：[A]个
- 其中非功能需求：[B]个
- 其中技术约束：[C]个
- 待办事项：[D]个

提示词模板：

你是一个需求分析专家。请分析以下代码注释，提取其中的隐含需求。

代码文件：{file_path}
注释内容：
{comment_text}

请从以下维度分析：
1. 业务需求：注释中暗示的用户需求或业务规则
2. 功能需求：需要实现但未文档化的功能
3. 非功能需求：性能、安全、可靠性等要求
4. 技术约束：技术选择的原因和限制
5. 设计决策：架构或实现决策的理由
6. 待办事项：TODO、FIXME、HACK等标记

请以JSON格式返回：
{
  "implied_requirements": [
    {
      "type": "functional|non-functional|constraint",
      "category": "业务需求|功能需求|性能|安全|约束|决策|待办",
      "description": "需求描述",
      "priority": "P0|P1|P2",
      "rationale": "提取依据",
      "code_location": "文件:行号",
      "implementation_status": "已实现|未实现|部分实现"
    }
  ],
  "statistics": {
    "total_comments": 0,
    "implied_requirements_count": 0,
    "functional_count": 0,
    "non_functional_count": 0,
    "constraints_count": 0,
    "todo_count": 0
  }
}

步骤2.3：分析问题和缺失信息（必需，必须在列出功能需求清单之前完成）

执行要求：此步骤不能跳过！必须基于步骤2.2的功能理解来分析问题！

⚠️ 执行前检查：

步骤2.1已完成（已读取需求文档和代码文件）
步骤2.2已完成（已理解项目功能并输出功能概述）
已准备好开始分析问题和缺失信息

必须输出以下内容（每个部分都必须有具体输出，不能为空）：

模糊点识别（必须输出，至少列出1个或明确说明"无"）：

## 模糊点识别结果

基于功能理解，识别以下模糊点：

模糊点1：[具体描述]
- 位置：[需求文档中的位置，如：requirements.md 第X行]
- 问题：[为什么模糊、缺失什么信息]
- 是否为误报：[代码实现是否已经说明了这部分信息]
- 如何修复：[需要什么信息来修复]

模糊点2：[具体描述]
...

如果未发现模糊点，必须明确说明：
"经过详细分析，未发现模糊点。代码实现和需求文档都清晰明确。"

缺失信息识别（必须输出，至少列出1个或明确说明"无"）：

## 缺失信息识别结果

基于功能理解，识别以下缺失信息：

缺失信息1：[缺少什么，如：验收标准、输入输出定义、错误处理等]
- 关联需求：[哪个需求缺少，引用具体需求名称或编号]
- 为什么是问题：[为什么需要这个信息，对功能理解的影响]
- 是否为误报：[代码实现是否已经说明了，如果是误报请说明原因]
- 如何修复：[需要什么信息来修复]

缺失信息2：[缺少什么]
...

如果未发现缺失信息，必须明确说明：
"经过详细分析，未发现缺失信息。所有功能需求都有完整的信息。"

不一致性识别（必须输出，至少列出1个或明确说明"无"）：

## 不一致性识别结果

对比代码和文档，识别以下不一致：

不一致1：[描述不一致的地方]
- 代码中：[代码中如何实现的，引用具体代码位置]
- 文档中：[文档中如何描述的，引用具体文档位置]
- 影响：[这种不一致对功能理解的影响]
- 建议：[如何修复，建议保留代码实现还是文档描述]

不一致2：[描述不一致的地方]
...

如果未发现不一致，必须明确说明：
"经过详细对比，未发现不一致。代码实现与需求文档完全一致。"

验证点（全部满足）：

✅ 必须输出具体的模糊点、缺失信息和不一致性（每个类别至少1个或明确说明"无"）
✅ 不能只是说"没有发现问题"，必须对每个类别明确说明
✅ 每个识别到的问题都必须包含：位置、问题描述、是否为误报、如何修复
✅ 如果没有发现问题，必须明确说明："经过分析，未发现模糊点、缺失信息或不一致性。"
✅ 输出格式必须清晰，便于后续生成澄清问题

常见错误示例（避免）：

❌ "未发现问题"（太笼统，必须分类说明）
❌ "需求文档很完善"（必须明确说明每个类别的情况）
❌ 跳过此步骤直接进入步骤2.4（禁止）

步骤2.4：列出功能需求清单（必需，必须在分析完成后列出并展示给用户）

执行条件：完成步骤2.2和2.3后，才能执行此步骤！

必须输出以下内容：

## 功能需求清单

### 核心功能需求（P0）
1. [功能名称]
   - 功能描述：[这个功能做什么]
   - 功能行为：[这个功能怎么做]
   - 输入输出：[输入是什么、输出是什么]
   - 代码实现情况：[已实现/未实现/部分实现]
   - 需求文档位置：[文档中的位置]

2. [功能名称]
   ...

### 重要功能需求（P1）
...

### 一般功能需求（P2）
...

### 非功能性需求
- 性能需求：[列出]
- 安全需求：[列出]
- 可靠性需求：[列出]

验证点：输出完整的功能需求清单，包含所有功能需求和分类！

关键检查点：Stage 2完成后，必须进入Stage 3（交互澄清），不能跳过！

详细指南：参见项目文档中的需求分析相关章节

Stage 3: 交互澄清（通过AskUserQuestion与用户交互补充需求）

重要阶段，不能跳过！

重要：

✅ 必须在Stage 2完成后才能进入此阶段
✅ 不能在Stage 2之后直接进入Stage 4（需求完善）
✅ 必须通过 AskUserQuestion 工具与用户交互，补充缺失的需求信息
✅ 基于Stage 2的分析结果（功能需求清单和问题分析）生成澄清问题
✅ 必须至少进行一次 AskUserQuestion 交互，即使分析结果很完善

执行检查清单：

注意：完成Stage 3的所有交互后，才能进入Stage 4（需求完善）！

基于AI分析结果生成澄清问题：
- 先理解每个需求的实际功能（基于功能概述）
- 针对具体功能问问题，而不是通用的检查清单
- 问题应该基于功能的实际行为，而不是模板化的问题
- 针对功能需求清单中缺失的信息生成问题
使用 AskUserQuestion 工具与用户交互（必需，不能跳过）：

执行要求：必须与用户交互，不能跳过此步骤！

AskUserQuestion 工具调用方式：
```
必须使用 AskUserQuestion 工具调用，格式：
  AskUserQuestion({
    questions: [
      {
        header: "澄清问题",
        question: "[具体问题]",
        options: [
          {label: "[选项1]", description: "[描述]"},
          {label: "[选项2]", description: "[描述]"},
          {label: "[选项3]", description: "[描述]"},
          {label: "[选项4]", description: "[描述]"}
        ],
        multiSelect: false
      }
    ]
  })

  然后必须等待用户回答后再继续。
```
重要说明：
- 使用 questions 数组（单元素数组）
- 每个问题必须有 header（简短标签，≤12字符）
- 提供2-4个 options（选项列表）
- 设置 multiSelect 为false（单选）或true（多选）
- 等待用户回答，不能跳过
⚠️ 交互要求：
- 如果有问题（步骤2.3中识别到模糊点、缺失信息或不一致性）：
  - 必须基于功能需求清单和问题分析结果，生成澄清问题
  - 必须逐个询问缺失的信息，补充需求
  - 必须至少询问3-5个关键问题
  - 必须等待用户回答每个问题后再继续
- 如果没有问题（步骤2.3中未发现任何问题）：
  - 必须明确告知用户："经过分析，未发现模糊点、缺失信息或不一致性。"
  - 然后必须询问："是否要添加新需求？或直接进入下一步？"
  - 必须等待用户回答
注意：无论是否有问题，都至少进行一次用户交互！

交互后记录用户回答，基于回答调整后续问题或进入下一步！
收集用户回答，调整后续问题：
- 记录用户回答
- 基于用户回答调整后续问题
- 持续交互直到所有关键问题都得到回答

详细指南：参见项目文档中的问题生成相关章节

Stage 4: 需求完善（集成到spec-workflow）

执行条件：Stage 3（交互澄清）完成后才能进入此阶段！

重要：无论项目是否使用 spec-workflow，都按照 spec-workflow 格式处理需求文档。

整合信息：结合原始需求文档、用户澄清回答、代码实现情况、功能需求清单
生成完善后的需求：
- 明确用户故事格式（As a [role], I want [feature], so that [benefit]）
- 补充详细的验收标准（EARS 格式：WHEN [condition] THEN [system] SHALL [response]）
- 添加业务价值说明
- 按照 spec-workflow 格式生成需求文档（无论项目是否使用 spec-workflow）
检测和处理 spec-workflow 集成：
- 检测项目是否使用 spec-workflow（检查 .spec-workflow 目录）
- 如果项目使用 spec-workflow：
  - 尝试使用 spec-workflow MCP 工具获取模板和上下文
  - 如果MCP不可用，使用 spec-workflow CLI 或直接生成标准格式
  - 更新 .spec-workflow/specs/*/requirements.md
- 如果项目未使用 spec-workflow：
  - 自动按照 spec-workflow 格式生成需求文档
  - 自动创建 .spec-workflow/specs/[feature-name]/requirements.md

扩展4.1：需求自动分类（智能分类与优先级评估）

执行位置：Stage 4中的可选增强功能，在生成完善需求后执行

功能说明：自动对需求进行智能分类、评估优先级、识别依赖关系、生成标签，提升需求管理效率。

执行步骤：

步骤4.1.1：智能分类

分析每个需求的语义内容
分类需求类型：功能需求/非功能需求/业务需求/技术需求
细分功能类别：用户交互/业务逻辑/数据处理/系统集成/其他
评估业务价值（1-10分）
评估技术复杂度（1-10分）

步骤4.1.2：优先级评估 基于多维度计算综合优先级：

业务价值权重：40%
技术复杂度权重：25%（复杂度越低分越高）
资源投入权重：20%（投入越少分越高）
紧急程度权重：15%
综合评分 = (业务价值×0.4 + (10-复杂度)×0.25 + (10-投入)×0.2 + 紧急度×0.15) × 10
优先级分级：
- P0（80-100分）：关键需求，必须立即处理
- P1（60-79分）：重要需求，近期需要处理
- P2（40-59分）：一般需求，中期规划
- P3（0-39分）：低优先级，长期规划

步骤4.1.3：模块映射 将需求映射到功能模块：

用户管理模块
内容管理模块
交易模块
数据分析模块
系统管理模块
其他自定义模块

步骤4.1.4：依赖关系识别 识别需求间的依赖关系：

前置依赖：A需求必须在B需求之前完成
后续依赖：A需求依赖B需求的完成
并行依赖：A和B可以同时进行
互斥依赖：A和B不能同时存在

步骤4.1.5：标签生成 为每个需求生成标签：

技术标签：基于使用的技术栈
业务标签：基于业务领域
特性标签：新增功能/改进/修复
状态标签：已计划/进行中/已完成/已放弃

输出格式：

## 需求自动分类结果

### 需求分类概览
- 总需求数：[X]个
- 功能需求：[A]个（[B]%）
- 非功能需求：[C]个（[D]%）
- 业务需求：[E]个（[F]%）
- 技术需求：[G]个（[H]%]

### 优先级分布
- P0（关键）：[X]个需求
- P1（重要）：[Y]个需求
- P2（一般）：[Z]个需求
- P3（低优先级）：[W]个需求

### 详细分类结果

#### 需求 REQ-[编号]: [需求标题]
- **分类信息**：
  - 类型：[功能/非功能/业务/技术]
  - 类别：[用户交互/业务逻辑/数据处理/系统集成]
  - 模块归属：[模块名称] (置信度：[X]%)

- **优先级评估**：
  - 综合评分：[X]/100
  - 优先级：[P0/P1/P2/P3]
  - 评估因子：
    * 业务价值：[X]/10
    * 技术复杂度：[X]/10
    * 资源投入：[X]/10
    * 紧急程度：[X]/10

- **依赖关系**：
  - 前置依赖：[REQ-XXX, REQ-YYY]
  - 后续依赖：[REQ-ZZZ]
  - 并行依赖：[REQ-AAA]
  - 互斥依赖：[REQ-BBB]

- **标签**：
  - 技术标签：[标签1, 标签2]
  - 业务标签：[标签3, 标签4]
  - 特性标签：[新增功能/改进/修复]
  - 状态标签：[已计划]

### 模块依赖图

[模块A] → [模块B] → [模块C] ↓ ↓ [模块D] → [模块E]


### 优先级矩阵

高价值低复杂度 │ 高价值高复杂度 ──────────────┼────────────── P0 │ P1 ──────────────┼────────────── 低价值低复杂度 │ 低价值高复杂度 P2 │ P3

提示词模板：

你是一个需求分类专家。请分析以下需求，进行智能分类和优先级评估。

需求描述：
{requirement_text}

请从以下维度分析：
1. 需求类型：功能需求/非功能需求/业务需求/技术需求
2. 功能类别：用户交互/业务逻辑/数据处理/系统集成/其他
3. 业务价值：1-10分（10分最高）
4. 技术复杂度：1-10分（10分最复杂）
5. 资源投入：1-10分（10分投入最多）
6. 紧急程度：1-10分（10分最紧急）

请以JSON格式返回：
{
  "classification": {
    "type": "functional|non-functional|business|technical",
    "category": "用户交互|业务逻辑|数据处理|系统集成|其他",
    "module": "模块名称",
    "module_confidence": 0.0-1.0
  },
  "priority": {
    "business_value": 1-10,
    "tech_complexity": 1-10,
    "resource_cost": 1-10,
    "urgency": 1-10,
    "overall_score": 0-100,
    "priority_level": "P0|P1|P2|P3",
    "reasoning": "评估理由"
  },
  "dependencies": {
    "prerequisites": ["REQ-XXX"],
    "dependents": ["REQ-YYY"],
    "parallel": ["REQ-ZZZ"],
    "mutual_exclusive": ["REQ-AAA"]
  },
  "tags": {
    "technology": ["标签"],
    "business": ["标签"],
    "feature": "新增功能|改进|修复",
    "status": "已计划|进行中|已完成|已放弃"
  }
}

Stage 5: 需求文档合并（多个需求文档时）

触发条件：在Stage 1（根据扫描结果决定流程）中，如果检测到多个需求文档，进入此阶段。

重要：

✅ 必须在用户确认后才执行合并
✅ 合并后的文档必须保存到 spec-workflow 格式的需求文档中
✅ 删除所有已合并的需求文档，只保留合并后的文档，保证只有一份文档
✅ 删除文档前必须向用户确认要删除的文档列表

执行流程：

识别需要合并的文档：
- 查找所有需求文档（.spec-workflow/specs/*/requirements.md、根目录的 requirements.md、docs/ 目录下的需求文档等）
- 使用 AI 分析文档内容，识别重复、冲突和互补的需求
生成合并方案：
- 基于文档分析结果，生成合并方案
- 建议合并到哪个文档（优先建议 spec-workflow 格式的需求文档）
- 如何处理重复需求、冲突需求
使用 AskUserQuestion 确认合并（必需）：
- 询问用户是否要合并多个需求文档
- 确认合并方案
- 确认如何处理重复和冲突的需求
- 确认合并后的文档保存位置
执行合并：
- 基于用户确认的合并方案，执行合并
- 保留所有重要信息，去除重复内容
- 解决冲突需求（基于用户选择）
保存合并后的文档并删除其他文档（必需）：
- 按照 spec-workflow 格式生成合并后的文档（无论项目是否使用 spec-workflow）
- 保存到 spec-workflow 格式的需求文档：
  - 如果项目使用 spec-workflow：保存到 .spec-workflow/specs/[feature-name]/requirements.md 或 .spec-workflow/requirements.md
  - 如果项目未使用 spec-workflow：自动创建 .spec-workflow/specs/[feature-name]/requirements.md
- 删除所有已合并的需求文档（删除前向用户确认要删除的文档列表）
- 只保留合并后的文档，保证只有一份文档

详细指南：参见项目文档中的文档合并相关章节

Stage 8: 用户画像分析（理解目标用户）

执行位置：Stage 4（需求完善）完成后可选执行，或作为独立分析功能

功能说明：从需求文档中自动提取和分析用户角色、特征、场景、目标和痛点，生成结构化用户画像，帮助团队更好地理解目标用户。

执行步骤：

步骤8.1：用户角色提取

扫描需求文档中的角色关键词
识别角色类型：最终用户/管理员/运营人员/客服人员/财务人员/开发人员/测试人员
判断用户层级：高级用户/普通用户/初级用户/游客
估算用户占比

步骤8.2：用户特征分析 分析每个角色的特征：

人口统计特征：年龄段、性别倾向、地域分布、职业背景
行为特征：使用频率、使用时长、使用场景、技术熟练度
需求特征：功能需求、性能需求、安全需求、体验需求

步骤8.3：用户场景分析

识别主要场景（核心使用流程）
识别次要场景（辅助功能）
识别边缘场景（异常处理）
每个场景包含：目标、前置条件、操作流程、期望结果、使用频率、重要程度

步骤8.4：用户目标提取 提取三类目标：

业务目标：与工作/业务相关的目标
体验目标：与使用体验相关的目标
个人目标：与个人价值相关的目标

步骤8.5：用户痛点识别 识别三类痛点：

效率痛点：操作繁琐、流程冗长等
体验痛点：界面不友好、响应慢等
业务痛点：成本高、维护困难等
评估痛点严重程度（高/中/低）

步骤8.6：生成用户画像 整合所有信息，生成结构化用户画像文档

输出格式：

## 用户画像分析结果

### 用户角色概览
- 识别用户角色：[X]种
- 主要角色：[角色1] ([占比]%), [角色2] ([占比]%)
- 用户层级分布：高级用户[X]%, 普通用户[Y]%, 初级用户[Z]%

### 详细用户画像

#### 用户画像 1: [角色名称]
**基本信息**：
- 用户角色：[类型]
- 用户层级：[层级]
- 用户占比：[X]%
- 主要部门：[部门]

**特征描述**：
- **人口统计特征**：
  - 年龄段：[青年/中年/老年]
  - 性别倾向：[男性/女性/中性]
  - 地域分布：[一线/二线/三线/海外]
  - 职业背景：[职业描述]

- **行为特征**：
  - 使用频率：[高频/中频/低频]
  - 使用时长：[长时间/短时间/碎片化]
  - 使用场景：[工作/生活/学习/娱乐]
  - 技术熟练度：[专家/熟练/一般/新手]

- **需求特征**：
  - 功能需求：[需求列表]
  - 性能需求：[需求列表]
  - 安全需求：[需求列表]
  - 体验需求：[需求列表]

**使用场景**：
1. **场景1: [场景名称]**
   - 目标：[想要达成什么]
   - 前置条件：[使用前需要什么]
   - 操作流程：[具体步骤]
   - 期望结果：[预期得到什么]
   - 使用频率：[高/中/低]
   - 重要程度：[P0/P1/P2]

**用户目标**：
- **业务目标**：
  - [目标1]
  - [目标2]

- **体验目标**：
  - [目标1]
  - [目标2]

- **个人目标**：
  - [目标1]
  - [目标2]

**用户痛点**：
- **效率痛点**：
  - [痛点1]
  - [痛点2]

- **体验痛点**：
  - [痛点1]
  - [痛点2]

- **业务痛点**：
  - [痛点1]
  - [痛点2]

- **严重程度**：[高/中/低]

**需求优先级**：
- **P0 (核心需求)**：
  - [需求1]
  - [需求2]

- **P1 (重要需求)**：
  - [需求1]
  - [需求2]

- **P2 (一般需求)**：
  - [需求1]
  - [需求2]

### 用户画像可视化

#### 角色分布

[角色1] ████████████████████ 70% [角色2] ████████ 20% [角色3] ██ 10%


#### 特征雷达图（ASCII）

技术熟练度 /
/
使用频率/ \访问时段 /
/ \

提示词模板：

你是一个用户画像分析专家。请分析以下需求文档，提取用户画像信息。

需求文档内容：
{requirements_text}

请从以下维度分析：

1. 用户角色提取：
   - 识别所有用户角色
   - 判断用户层级
   - 估算用户占比

2. 用户特征分析：
   - 人口统计特征
   - 行为特征
   - 需求特征

3. 用户场景分析：
   - 主要场景（3-5个）
   - 每个场景的详细信息

4. 用户目标提取：
   - 业务目标
   - 体验目标
   - 个人目标

5. 用户痛点识别：
   - 效率痛点
   - 体验痛点
   - 业务痛点

请以JSON格式返回：
{
  "personas": [
    {
      "basic_info": {
        "name": "角色名称",
        "role_type": "end_user|admin|operator|cs|finance|developer|tester",
        "user_level": "power|regular|novice|guest",
        "department": "部门",
        "percentage": 0.0-100.0
      },
      "characteristics": {
        "demographics": {
          "age_group": "young|middle_aged|elderly",
          "gender_tendency": "male|female|neutral",
          "region": "tier1|tier2|tier3|overseas",
          "profession": "职业描述"
        },
        "behavioral": {
          "frequency": "high|medium|low",
          "duration": "long|short|fragmented",
          "scenario": "work|life|study|entertainment",
          "tech_proficiency": "expert|proficient|average|novice"
        },
        "needs": {
          "functional": ["需求"],
          "performance": ["需求"],
          "security": ["需求"],
          "experience": ["需求"]
        }
      },
      "scenarios": [
        {
          "name": "场景名称",
          "goal": "目标",
          "prerequisites": ["条件"],
          "steps": ["步骤"],
          "expected_result": "期望结果",
          "frequency": "high|medium|low",
          "importance": "P0|P1|P2"
        }
      ],
      "goals": {
        "business": ["目标"],
        "experience": ["目标"],
        "personal": ["目标"]
      },
      "pain_points": {
        "efficiency": ["痛点"],
        "experience": ["痛点"],
        "business": ["痛点"],
        "severity": "high|medium|low"
      },
      "requirements": {
        "p0": ["需求"],
        "p1": ["需求"],
        "p2": ["需求"]
      }
    }
  ],
  "statistics": {
    "total_personas": 0,
    "total_scenarios": 0,
    "total_pain_points": 0
  }
}

📋 重要原则

先扫描，后分析：技能启动时先扫描项目的代码和文档（步骤1），然后根据扫描结果决定流程
先分析，后交互：对于常规流程，必须先完成阶段2（需求分析：分析问题和缺失信息 + 列出功能需求清单），然后才能进入阶段3（交互澄清）
交互澄清不可跳过：阶段3（交互澄清）是必需阶段，必须在阶段2完成后执行，不能在阶段2之后直接进入阶段4
分析完成后列出功能需求清单：阶段2必须先分析问题和缺失信息，然后在分析完成后列出功能需求清单并展示给用户
通过AskUserQuestion交互补充需求：阶段3必须通过 AskUserQuestion 工具与用户交互，补充缺失的需求信息
集成到spec-workflow：无论项目是否使用 spec-workflow，都按照 spec-workflow 格式处理需求文档
必须使用 AskUserQuestion 工具：所有用户交互都必须通过 AskUserQuestion 工具进行，不能只是输出文本
严格按照顺序执行：不能跳过步骤1（扫描）、阶段2（需求分析）或阶段3（交互澄清）
完全AI驱动：不使用正则表达式，完全依赖 Claude 的 AI 理解能力
分析代码和文档：不仅要分析需求文档，还要分析代码文件，理解已实现的功能

🛠️ 使用的工具

Read: 读取需求文档和代码文件
Bash: 查找文件、执行命令
AskUserQuestion: 与用户交互，澄清需求（必需）
Write: 更新和完善需求文档
spec-workflow MCP 或 CLI: 访问spec-workflow模板和上下文（如果可用），否则直接生成标准格式

📚 详细指南

空项目引导: 参见项目文档中的空项目引导相关章节
需求分析: 参见项目文档中的需求分析相关章节
问题生成: 参见项目文档中的问题生成相关章节
需求完善: 参见项目文档中的需求完善相关章节
需求文档合并: 参见项目文档中的文档合并相关章节
Spec-Workflow 集成: 参见项目文档中的集成相关章节

📝 执行示例

示例: 合并需求文档

用户: "合并需求文档" 或使用技能

你:

智能需求分析助手 | Intelligent Requirements Facilitator

👤 作者: 苏州核朔智能科技有限公司
📖 文档: README.md | 🤝 贡献: CONTRIBUTING.md
📧 limian@norkern.com | 🌐 www.norker.com
🐛 Issues: [GitHub Issues](https://github.com/damienCronw/hs-req-facilitator-skill/issues)

⚡ 版本: v2.0.2

🚀 开始执行需求文档合并流程...

📂 步骤1: 扫描代码和文档（必需）...

[必须执行 find 命令扫描文档和代码]
[统计结果：发现3个需求文档和150个代码文件]

📋 步骤2: 根据扫描结果决定流程...

[检测到多个需求文档：requirements.md, docs/user-requirements.md, docs/api-requirements.md]

AskUserQuestion: "我发现项目中有3个需求文档，内容有重复。建议合并为1个文档。是否要开始合并？"

用户: "是的，合并"

📋 阶段5: 需求文档合并...

步骤1: 识别需要合并的文档
  - requirements.md
  - docs/user-requirements.md
  - docs/api-requirements.md

步骤2: 分析文档内容（AI分析）
  - 识别重复需求：5个
  - 识别冲突需求：2个
  - 识别互补需求：10个

步骤3: 生成合并方案
  - 建议合并到：.spec-workflow/specs/main/requirements.md
  - 重复需求处理：保留最详细的版本
  - 冲突需求处理：询问用户选择

AskUserQuestion: "合并方案：将3个需求文档合并到 .spec-workflow/specs/main/requirements.md。是否同意？"

用户: "同意"

AskUserQuestion: "合并完成后，我将删除以下需求文档，只保留合并后的文档：
- requirements.md
- docs/user-requirements.md
- docs/api-requirements.md

合并后的文档将保存到：.spec-workflow/specs/main/requirements.md

是否同意删除上述文档？"

用户: "同意"

步骤4: 执行合并
  - 合并重复需求（保留最详细的版本）
  - 解决冲突需求（基于用户选择）
  - 合并互补需求

步骤5: 保存合并后的文档并删除其他文档
  - 按照 spec-workflow 格式生成合并后的文档
  - 保存到 .spec-workflow/specs/main/requirements.md
  - 删除 requirements.md
  - 删除 docs/user-requirements.md
  - 删除 docs/api-requirements.md
  - ✅ 只保留一份需求文档

用户: "完善需求" 或使用技能

你: 🚀 开始执行需求完善流程...

📂 步骤1: 扫描代码和文档（必需）...

[必须执行 find 命令扫描文档和代码]
[统计结果：发现2个需求文档和150个代码文件]

📋 步骤2: 根据扫描结果决定流程...

[检测到有需求文档，进入常规流程]

📋 阶段2: 需求分析（必须在交互澄清之前完成）...

步骤1: 读取需求文档和代码文件
步骤2: 理解项目功能
步骤3: 分析问题和缺失信息（必需，必须在列出功能需求清单之前完成）
  - 问题1: [缺失什么、为什么是问题、是否为误报、如何修复]
  - 问题2: [缺失什么、为什么是问题、是否为误报、如何修复]
  ...

步骤4: 列出功能需求清单（必需，必须在分析完成后列出并展示给用户）
  - 功能需求1: [功能名称]
    * 功能描述：[这个功能做什么]
    * 功能行为：[这个功能怎么做]
    * 代码实现：[代码中是否已实现]
  - 功能需求2: [功能名称]
    ...
  - 非功能性需求：[性能需求、安全需求、可靠性需求等]

阶段2已完成，现在进入阶段3（交互澄清），不能跳过！

📋 阶段3: 交互澄清（通过AskUserQuestion与用户交互补充需求）...

[重要阶段，不能跳过！使用 AskUserQuestion 工具与用户交互]

[基于阶段2的分析结果，生成澄清问题]

如果有问题：
AskUserQuestion: "我看到功能需求清单中，功能需求1缺少验收标准。请告诉我：如何验证这个功能是否成功实现？"

用户: [回答]

AskUserQuestion: "功能需求2的输入输出还不明确。请告诉我：这个功能的输入是什么？输出是什么？"

用户: [回答]

...继续交互直到所有关键问题都得到回答...

如果没有问题：
AskUserQuestion: "没有发现问题需要澄清。是否要添加新需求？或直接进入下一步？"

用户: [回答]

✅ 阶段3已完成，现在可以进入阶段4（需求完善）！

📋 阶段4: 需求完善（集成到spec-workflow）...

[检测项目是否使用 spec-workflow]
[按照 spec-workflow 格式生成需求文档]
[如果项目使用 spec-workflow，更新 .spec-workflow/specs/*/requirements.md]
[如果项目未使用 spec-workflow，自动创建 .spec-workflow 目录结构]

🔗 相关资源

name	hs-req-facilitator-skill
description	Use this skill when users want to analyze, clarify, or improve requirements documents. Works well for projects with unclear requirements, missing specifications, or multiple requirement documents that need consolidation. Automatically generates spec-workflow format requirements documents. Activate when users mention "requirements", "specifications", "analyze needs", or "clarify ambiguous requirements".
type	configuration-driven
implementation	mcp-services
version	2.0.4
author	Suzhou Heshuo Intelligent Technology Co., Ltd.
email	limian@norkern.com
website	www.norker.com
company	Suzhou Heshuo Intelligent Technology Co., Ltd.
mcp-services	["spec-workflow"]