@culeo/specx 0.1.0

package/skills/specx-clarify/SKILL.md

@@ -0,0 +1,581 @@
+---
+name: specx-clarify
+description: specx 流程第二步 — 需求澄清 & 规格输出。通过迭代式提问，逐步完善需求文档并输出规格说明书。
+category: software-development
+tags: [specx, requirements, clarify, spec]
+---
+
+# specx-clarify：需求澄清 & 规格输出
+
+## 触发条件
+
+当有一个已拆解的子需求 `00-子需求.md`，需要生成 `01-clarify.md` 和 `02-spec.md` 时使用。
+
+**输入：** `00-子需求.md`
+**输出：** `01-clarify.md` + `02-spec.md`
+
+## 前置：了解项目背景（可选）
+
+如果对需求背景、领域概念等有疑问，可查阅 `docs/specx/wiki/` 中的已有知识沉淀。
+
+---
+
+## 核心思想
+
+### 两个文件，两个角色
+
+| 文件 | 回答的问题 | 何时产出 |
+|------|-----------|---------|
+| **01-clarify.md** | 这个功能「要做什么」| 快速扫盲后立即输出初始版 |
+| **02-spec.md** | 怎么算「做好了」| 深度挖掘，逐步完善 |
+
+### 迭代式澄清
+
+```
+读 00-子需求.md（快速扫盲）
+    ↓
+输出 01-clarify.md（初始版）
+    ↓
+尝试写 02-spec.md（深度挖掘）
+    ↓
+遇到模糊点 → 问问题 → 更新 01-clarify.md
+    ↓
+继续写 spec
+    ↓
+重复，直到 spec 完成
+```
+
+---
+
+## 核心方法论
+
+### 1. 5W1H（快速扫盲用）
+
+> 用于 Step 1 快速扫盲时建立需求初步认知
+
+| 问题 | 含义 | 在 clarify 中的用途 |
+|------|------|------------------|
+| **What** | 是什么 | 需求概述 |
+| **Who** | 谁用 | 用户场景 |
+| **When** | 什么时候 | 边界情况/触发时机 |
+| **Why** | 为什么做 | ❌ 不深究需求价值评估，那是上游的职责 |
+| **Where** | 在哪 | ❌ 大部分情况上下文已带出，无需再问 |
+| **How** | 怎么做 | 在 spec 里写 |
+
+**注意：clarify 质疑的是「是否清晰」，不质疑「是否应该做」。**
+
+### 2. Given-When-Then（写 spec 验收标准用）
+
+> 用于描述可测试的行为标准，写入 `02-spec.md` 的验收标准章节
+
+```
+GIVEN {前置条件}
+WHEN {触发动作}
+THEN {预期结果}
+```
+
+**参考模板：见 Step 3 spec 模板中的「验收标准」章节**
+
+### 3. SRS Quality Attributes（clarify 完成后的质量检查）
+
+> 用于 Step 6 完成前的质量自检，基于 IEEE 830 SRS 标准
+
+| 属性 | 含义 | 检查问题 |
+|------|------|---------|
+| **Complete** | 完整 | 所有必要细节都覆盖了？用户场景、边界情况都写了？ |
+| **Consistent** | 一致 | 内部无矛盾？与其他子需求无冲突？ |
+| **Clear** | 清晰 | 描述无歧义？只有一种理解？没用模糊词汇？ |
+| **Testable** | 可测试 | 能导出 Given-When-Then 验收标准？标准是否明确可验证？ |
+| **Traceable** | 可追溯 | 能追溯到 00-子需求 的原始需求？ |
+
+**参考：见「质量检查清单」章节**
+
+---
+
+## 流程（Step-by-Step）
+
+### Step 0️⃣ 检查现有文件（恢复模式）
+
+> ⚠️ 如果之前中断或未完成，从这里开始
+
+**动作：**
+1. 检查是否存在 `01-clarify.md` 和 `02-spec.md`
+2. 如果存在，读取并分析中断点
+
+**判断逻辑：**
+
+```
+读取 01-clarify.md：
+  ├── 有「回答：-」的 Q → 继续这个 Q（不要重复问）
+  ├── 「待确认」有未勾选 → 继续问
+  └── 都是 ✅ → 检查 spec 完成度
+
+读取 02-spec.md：
+  ├── 有空章节 → 补全
+  └── 都写完 → 检查「待确认」是否清空
+      ├── 已清空 → 标记完成，结束
+      └── 未清空 → 继续问
+```
+
+**中断点判断：**
+
+```markdown
+// 01-clarify.md 中断信号
+**状态：** 🔄 进行中     ← 进行中 = 未完成
+**clarify 结束时间：** -  ← 空 = 未完成
+
+// Q&A 中断信号
+### Q2: ...
+**回答：** -              ← 空 = 未回答，继续追问
+**确认时间：** -           ← 空 = 未确认
+```
+
+**不存在 → 从 Step 1 开始。存在但不完整 → 从中断点继续。**
+
+---
+
+### Step 1️⃣ 快速扫盲
+
+**动作：** 读 `00-子需求.md`，理解这个子需求要做什么
+
+**原则：不要逐字逐句分析，不要深挖细节，先快速建立整体认知**
+
+---
+
+### Step 2️⃣ 输出初始 clarify-prd
+
+**动作：** 基于快速扫盲，立即输出 `01-clarify.md` 初始版本
+
+**01-clarify.md 内容结构：**
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# {子需求名称}
+
+**所属原始需求：** {需求名称}
+**子需求目录：** T-{序号}-{名称}
+
+---
+
+## 需求概述
+
+{用一段话描述这个功能要做什么}
+
+## 用户场景
+
+- 场景 1：{描述}
+- 场景 2：{描述}
+
+## 功能要点
+
+- {要点1}
+- {要点2}
+- {要点3}
+
+## 边界情况
+
+- {情况1}
+- {情况2}
+
+## Q&A 记录
+
+{clarify 过程中逐步添加}
+
+## 待确认 / 需要澄清的点
+
+- [ ] {问题1}
+- [ ] {问题2}
+
+---
+
+## 更新记录
+
+| 时间 | 更新内容 |
+|------|---------|
+| {YYYY-MM-DD} | 初始版本 |
+```
+
+**这个版本可能不完整，但先写出来再说。**
+
+---
+
+### Step 2.5️⃣ 框架对齐（跳过已定义的）
+
+> ⚠️ 如果 `docs/specx/rule/` 下已有规范，只clarify 框架未定义的部分
+
+**动作：**
+1. 扫描 `docs/specx/rule/` 目录下的规范文件
+2. 在 clarify-prd 中标注哪些是框架定义的（直接引用，不重复问）
+3. 只对「框架未定义」的部分提问
+
+**扫描范围：**
+```
+docs/specx/rule/          → 项目框架规范（由项目自己组织子目录结构）
+```
+
+**标注示例：**
+```markdown
+## 交互行为
+
+- 加载状态：骨架屏 ← 框架定义（rule/ui/loading.md）
+- 空数据：「暂无数据」← 框架定义（rule/ui/empty.md）
+- 网络错误：重试按钮 ← 框架定义（rule/error/retry.md）
+- [ ] 分页加载：每次加载多少条？← 需要澄清
+```
+
+**好处：**
+- 不重复问已有答案 → 省时间
+- 不污染上下文 → AI 不会被无用信息干扰
+- 保持一致性 → 大家都用同一套规范
+
+---
+
+### Step 3️⃣ 尝试写 spec
+
+**动作：** 基于当前的 `01-clarify.md`，尝试写 `02-spec.md`（参考「框架已定义」的部分，不重复问）
+
+**02-spec.md 内容结构：**
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# {子需求名称} — 规格说明书
+
+**所属子需求：** T-{序号}-{名称}
+
+---
+
+## 验收标准
+
+> 使用 Given-When-Then 格式，描述行为而非实现
+
+```markdown
+验收标准：
+
+GIVEN {前置条件}
+WHEN {触发动作}
+THEN {预期结果}
+
+GIVEN 用户打开页面
+WHEN 数据加载完成
+THEN 显示股票名称、当前价格、涨跌幅
+AND 显示更新时间
+
+GIVEN 用户下拉刷新
+WHEN 网络请求成功
+THEN 更新数据并显示新时间戳
+AND 显示「刷新成功」提示
+```
+
+**Given-When-Then 格式说明：**
+```
+GIVEN  → 前置条件（状态/数据/用户角色）
+WHEN   → 触发动作（用户操作/系统事件）
+THEN   → 预期结果（可见变化/返回值）
+AND    → 附加结果（可叠加多个）
+```
+
+> ⚠️ 一个 When 对应一个 Then，不要在一个 When 下写多个独立行为
+
+## 功能描述
+
+{详细描述功能行为}
+
+## 数据要求
+
+- 数据来源：{描述}
+- 数据格式：{描述}
+- 边界数据：{描述}
+
+## 交互行为
+
+- 正常流程：{描述}
+- 异常流程：{描述} ← 引用框架定义（rule/error/*.md）
+- 加载状态：{描述} ← 引用框架定义（rule/ui/*.md）
+- 错误状态：{描述} ← 引用框架定义（rule/error/*.md）
+
+## UI 要求（如有）
+
+{尺寸、布局、字体等}
+
+## 技术约束
+
+{性能要求、兼容性要求等}
+```
+
+> ⚠️ spec 中引用框架已定义的部分时，标注来源（如 `← 框架定义 rule/ui/loading.md`），不用重复描述细节。
+
+---
+
+### Step 4️⃣ 迭代澄清
+
+**触发条件：** 写 spec 时遇到以下情况
+
+- 某个点「不知道」「不确定」「原文没写」
+- 边界情况没定义
+- 数据格式没明确
+- 交互逻辑有歧义
+
+**动作：**
+1. **停下来**，不要猜
+2. **问一个问题**（一次只问一个）
+3. 等回答
+4. 记录到 `01-clarify.md` 的「Q&A 记录」和「待确认」
+5. 基于新信息继续写 spec
+
+**提问后处理答案：**
+```
+用户回答 → 判断类型：
+  ├── 选择 A/B/C → 直接采用，更新文档
+  ├── 提出新方案 → 评估后采纳或再确认
+  └── 开放式回答 → 整理成明确结论，更新文档
+```
+
+**分节确认（可选）：**
+clarify 完成后，spec 可以分节呈现给用户确认：
+
+```
+"02-spec.md 的「验收标准」已写完，
+ 你看一下这部分 OK 吗？"
+
+→ OK 后继续写下一节（功能描述）
+→ ...直到 spec 完成
+```
+
+> 如果用户懒得分节确认，可以直接写完再一起过一遍。
+
+**提问原则：**
+- 一次只问一个问题
+- 等回答后再问下一个
+- 描述模糊的地方要具体化
+
+**提问策略（借鉴 brainstorming）：**
+
+1. **多选优先** — 不只问「怎么做」，而是给选项：
+
+```
+❌ 开放式提问（用户难回答）
+   "数据加载失败怎么显示？"
+
+✅ 多选提问（用户轻松选）
+   "数据加载失败怎么显示？
+   A. 显示「加载失败」+ 重试按钮
+   B. 显示「加载失败」+ 自动重试3次
+   C. 显示「加载失败」+ 进入离线缓存模式
+   
+   选哪个？"
+```
+
+2. **提出方案（涉及设计决策时）** — 不只问偏好，而是给出方案 + 分析：
+
+```
+"对于这个功能，我建议 3 种方案：
+
+ A. 方案A（描述）
+    优点：...
+    缺点：...
+
+ B. 方案B（描述）
+    优点：...
+    缺点：...
+
+ C. 方案C（描述）
+    优点：...
+    缺点：...
+
+ 推荐 A，因为..."
+
+你觉得哪个合适？"
+```
+
+3. **开放式（无标准答案时用）** — 多选无法覆盖时：
+
+```
+"这个功能的用户是谁？"
+```
+
+**记录格式：**
+```markdown
+### Q{n}: {问题}
+**回答：** {答案}
+**确认时间：** {YYYY-MM-DD}
+```
+
+**更新待确认：**
+```markdown
+- [x] {问题} ✅
+```
+
+---
+
+### Step 5️⃣ 更新文档
+
+**每次澄清后，同步更新：**
+- `01-clarify.md`：补充 Q&A 记录，更新「待确认」清单，追加更新记录
+- `02-spec.md`：基于新信息完善 spec
+
+---
+
+### Step 6️⃣ 完成
+
+**停止条件：**
+```
+02-spec.md 的所有章节都填写完整
+所有「待确认」都已清除或有明确结论
+```
+
+**完成标记：**
+```markdown
+// 01-clarify.md 顶部，将 status 改为 review
+---
+status: review
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+  - "v2: clarify 完成"
+---
+
+// 更新记录追加
+| {YYYY-MM-DD} | clarify 完成 |
+```
+
+---
+
+## 示例迭代过程
+
+```
+第 1 次迭代：
+  → 读 00-子需求.md
+  → 写 01-clarify.md（初始版）
+  → 尝试写 02-spec.md
+  → 发现：数据来源不清楚
+  → 问：数据从哪个接口获取？
+
+第 2 次迭代：
+  → 回答：XX 接口
+  → 更新 01-clarify.md（Q&A + 待确认打勾）
+  → 继续写 02-spec.md
+  → 发现：空数据怎么显示？
+  → 问：空数据展示什么？
+
+第 3 次迭代：
+  → 回答：显示「暂无数据」
+  → 更新 01-clarify.md
+  → 继续写 02-spec.md
+  → ...（继续直到完成）
+```
+
+---
+
+## 中断恢复示例
+
+```
+场景：clarify 进行到一半，AI 关闭了
+
+恢复时：
+  Step 0 → 读取 01-clarify.md
+  → 发现：
+    - Q2 的「回答：-」→ 继续追问 Q2
+    - 待确认有 2 项未勾选 → 继续问
+  → 继续 Step 4
+
+而不是：
+  → 重新从 Step 1 开始
+  → 重复问 Q1、Q2（用户崩溃）
+```
+
+---
+
+## 重要提示
+
+- **不要在扫盲阶段深挖** — 快速建立认知，先写出来
+- **一次只问一个问题** — 问完等回答，不要堆一堆问题
+- **遇到不确定就问** — 不要猜，不要假设，不要「应该」
+- **两个文件同步更新** — clarify-prd 和 spec 是一体的
+- **clarify 迭代次数不限** — 可能是 1 次，可能是 10 次，都正常
+- **文档状态** — 新建时 `draft`，完成时 `review`
+- **框架已定义的不重复问** — 先扫描 `docs/specx/rule/`，直接引用，只clarify 未定义的部分
+- **避免污染上下文** — 框架规范在 rule/ 目录维护，不进clarify过程
+
+---
+
+## 质量检查清单
+
+完成 clarify 后，确认：
+
+### SRS Quality Attributes 质量检查（clarify-prd）
+
+```
+SRS Quality Attributes 检查
+━━━━━━━━━━━━━━━━━━━━━━
+☐ Complete（完整）？
+   → 所有必要细节都覆盖了？用户场景、边界情况都写了？
+
+☐ Consistent（一致）？
+   → 内部无矛盾？与其他子需求无冲突？
+
+☐ Clear（清晰）？
+   → 描述无歧义？只有一种理解？没用模糊词汇？
+
+☐ Testable（可测试）？
+   → 能导出 Given-When-Then 验收标准？标准是否明确可验证？
+
+☐ Traceable（可追溯）？
+   → 能追溯到 00-子需求 的原始需求？
+```
+
+### Given-When-Then 检查（spec 验收标准）
+
+```
+GWT 检查
+━━━━━━━━━━━━━━━━━━━━━━
+[ ] 每个验收标准都有 GIVEN-WHEN-THEN
+[ ] GIVEN 描述的是前置条件，不是实现细节
+[ ] WHEN 描述的是用户动作或系统事件
+[ ] THEN 描述的是可见结果
+[ ] 一个 WHEN 对应一个 THEN（不多对一）
+[ ] 验收标准可测试、可验证
+```
+
+---
+
+### 综合自检（SRS Quality Attributes）
+
+```
+clarify 质量自检（SRS Quality Attributes）
+━━━━━━━━━━━━━━━━━━━━━━
+☐ Complete（完整）？
+[ ] 01-clarify.md 的「需求概述」能回答「这个功能做什么」
+[ ] 01-clarify.md 有「用户场景」描述
+[ ] 01-clarify.md 的「边界情况」已列出
+
+☐ Consistent（一致）？
+[ ] 01-clarify.md 的「待确认」都已清除或有结论
+[ ] 与其他子需求无冲突
+
+☐ Clear（清晰）？
+[ ] 02-spec.md 的「功能描述」无歧义
+[ ] 没用模糊词汇（如「可能」「也许」「大概」）
+
+☐ Testable（可测试）？
+[ ] 02-spec.md 的「验收标准」使用 Given-When-Then 格式
+[ ] 02-spec.md 的「异常流程」有定义
+
+☐ Traceable（可追溯）？
+[ ] 01-clarify.md 的需求能追溯到 00-子需求 的原始需求
+
+[ ] 01-clarify.md 状态为「✅ 已完成」
+[ ] 01-clarify.md 有 clarify 结束时间
+[ ] 02-spec.md 的所有章节都填写完整
+```