Requirements clarity

Requirements Clarity

目标

在写 PRD 或进入工程交接之前，把模糊需求澄清到可判断、可取舍、可写文档的程度。

完成标准：

• 明确已知事实、合理假设、待确认问题。
• 识别会影响产品方向、范围、数据、权限、合规或上线可行性的缺口。
• 给出清晰度评分和是否可以进入 PRD 的判断。
• 只问必要问题，不把用户拖进长访谈。
• 默认先详细讨论灰区，再输出结论；除非用户明确说“快速版”“直接写”“不要问”“按你判断”。
• 默认讨论 12-20 个问题；快速版 6-8 个；极细版可超过 20 个。
• 所有澄清问题都必须使用 Codex 原生结构化选择 UI。不得退回文本 1/2/3 选择题；如果 request_user_input、AskUserQuestion 或等价结构化提问工具在当前 mode 中不可调用，停止澄清流程，并提示启用 default_mode_request_user_input 或切到支持原生选择 UI 的交互模式。
• 不要把“一次弹出的 3 个问题”当成完整澄清。原生 UI 每轮最多弹 3 个问题；用户回答后必须继续下一轮，直到达到当前模式的问题目标或用户明确要求停止/进入 PRD。

使用场景

使用本技能处理：

• 用户只有一句想法或零散需求。
• PRD 开始前缺目标用户、核心流程、成功指标或范围边界。
• 需求涉及多角色、多状态、支付、AI、数据产品、审核或合规。
• 用户要求“先帮我把需求问清楚”。

不要处理：

• 已有成熟 PRD 且用户只要审计：改用 prd-auditor。
• 用户要求完整 PRD：若信息足够，改用 elite-prd-writer。
• 用户要求任务拆解或测试用例：改用 implementation-handoff 或 qa-generator。

工作流程

1. 检查仓库已有 AGENTS.md、docs/、历史 PRD、issue、roadmap 和相关产品材料。
2. 提取当前已知事实，不补造业务事实。
3. 识别 3-4 个产品专属灰区，不使用“UI / UX / Behavior”这类泛泛分类。
4. 展示灰区，让用户用选择题选择要讨论哪些；不要默认跳过。
5. 每个选中灰区先通过原生结构化选择 UI 问 4-5 个问题，每题尽量提供 3 个具体选项；依赖客户端自动提供 Other，然后用原生结构化选择 UI 问“继续这个灰区 / 进入下一个 / 汇总当前决策”。
6. 默认总问题量为 12-20 个；如果用户只选一个灰区，提醒问题会偏少并建议补选其他关键灰区。
7. 按 references/clarity-rubric.md 给出 0-100 分清晰度评分。
8. 如果用户要求直接推进，列出显式假设，并说明哪些问题仍可能影响 PRD 质量。
9. 输出 Requirements Packet，供 elite-prd-writer 继续写 PRD。
10. 给出下一步：进入 PRD、继续澄清、先做调研、或暂不建议开工。

输出格式

## 当前理解

## 已知事实

## 合理假设

## 讨论过的灰区

| 灰区 | 已锁定决策 | 待确认 |
|---|---|---|

## 关键缺口

| 缺口 | 影响 | 优先级 | 建议处理 |
|---|---|---|---|

## 清晰度评分

总分：x/100

| 维度 | 分数 | 判断 |
|---|---:|---|

## 澄清问题

1. ...

## 暂定方向

## 是否可以进入 PRD

结论：可以 / 带假设可以 / 暂不建议

## Requirements Packet

- 已知事实：
- 合理假设：
- 待确认问题：
- 清晰度评分：
- 是否可进入 PRD：
- 建议 PRD 范围：

## 下一步

与其他技能的衔接

• 评分 >= 85：直接交给 elite-prd-writer 写完整 PRD。
• 评分 70-84：带 Requirements Packet 和显式假设交给 elite-prd-writer，PRD 中保留待确认问题。
• 评分 50-69：先回答阻塞澄清问题；用户要求继续时才带假设进入 elite-prd-writer。
• 评分 < 50：暂不建议写完整 PRD，先做需求澄清或调研。

灰区讨论规则

• 灰区必须跟当前产品有关，例如“训练任务结构”“审核与风控”“AI 输出形态”，不要写成泛泛的“体验”“功能”“交互”。
• 每个灰区先问 4-5 个选择题：方向、边界、流程状态、验收判断、异常/风险。
• 默认覆盖至少 3 个灰区，总计 12-20 个问题；少于 12 个问题时，不要声称需求已经充分澄清。
• 用户提出新能力时，记录到 Deferred Ideas，不纳入当前 PRD 范围。
• 不问技术架构、性能优化、具体代码实现；这里只锁产品决策。

提问规则

• 默认 12-20 个问题；用户要求快速版时 6-8 个问题；用户要求极细版时可以超过 20 个。
• 第一轮通常只问“讨论范围/灰区选择”，计入问题数；之后每轮最多弹 3 个问题，直到累计达到该模式目标。
• 快速版通常 2-3 轮；默认详细版通常 4-7 轮；极细版通常 7 轮以上。
• 如果一轮只问了 3 个问题，不要结束澄清；继续下一轮，除非用户明确要求停止、生成 PRD 或按当前答案继续。
• 优先问目标用户、核心问题、目标指标、主流程、范围、非范围、约束。
• 不问文件名、格式偏好、措辞这类低影响问题。
• 问题必须能改变 PRD 内容或开工判断。
• 不问纯开放题。必须使用 request_user_input、AskUserQuestion 或等价结构化选择工具提问，不要在聊天里打印文本列表。仅检测到 Codex App 不够，必须以工具实际可调用为准；如果不可调用，停止并报告阻塞。
• 原生 UI 提问规则：
  • 每次默认问 1 个问题；最多合并 3 个强相关问题。
  • 每题尽量提供 3 个互斥选项；只有确实不存在第三种合理路径时才用 2 个。
  • Codex 客户端会自动提供 Other，所以用户看到的通常是 3 个正式选项 + Other，共 4 行。不要尝试提供 4 个正式选项；当前 request_user_input 工具只接受 2-3 个正式选项。
  • 推荐选项放第一位；如果工具要求，在 label 上加 (Recommended)。
  • 每个选项必须有一句 description，说明产品含义或取舍。
  • 不要手动添加 其他，依赖客户端自动 Other。
  • header 用短标题，例如“讨论范围”“目标用户”“交易边界”。
• 每题默认 3 个正式选项；需要多选时，在问题里明确写“可多选”。
• 选项必须具体、可区分，并说明选择后的产品含义。
• 用户选择 Other 或补充自由文本时，先复述为明确决策，再继续下一道原生选择题。
• 流程控制也用原生结构化选择 UI。

严格禁止

• 不要把假设写成事实。
• 不要在澄清阶段直接开始写代码。
• 不要用开放式长访谈替代关键决策问题。
• 不要输出文本 1/2/3 选择题。
• 不要在原生结构化选择 UI 不可用时继续澄清。
• 不要因为信息不全就停止；能用假设推进时，明确标注假设后继续。