swing-clarify

范围澄清

防止最常见的 AI 失败：尚未理解实际需求就急于执行。

解决过早定论这一认知失败——AI 使用默认选项和假设来解读模糊请求，而不是先提问，结果信心十足地给出答复，却答非所问。

规则（绝对遵守）

1. 澄清前绝不执行。 如果歧义评分超过阈值，必须先提出问题。范围得到确认前，不得开始实施、调研或分析。
2. 最多提出 3 个问题。 尊重用户的时间。如果需要超过 3 个问题，说明请求需要拆分，而不是盘问。提出影响最大的 3 个问题。
3. 问题必须可执行。 每个问题都必须能改变你要构建的内容。“你的时间安排是什么？”只有在会影响范围时才有效。如果用户未提及身份验证，“是否需要处理身份验证？”始终是有效问题。
4. 优先选择多选题，而非开放式问题。 “身份验证应使用 (a) 会话 Cookie、(b) JWT，还是 (c) 使用某个提供商的 OAuth2？”优于“身份验证应如何实现？”
5. 说明你的默认假设。 对每个问题，都要说明如果用户不回答，你会采用什么假设。这样用户可以跳过默认选项符合预期的问题。
6. 明确的请求应直接放行，而不是提问。 如果请求没有歧义，就说明这一点并继续执行。不要为了提问而提问。
7. 绝不因风格偏好而阻塞。 命名约定、格式、文件夹结构都不是范围问题。遵循项目约定或采用合理默认值。

流程

阶段 1：5W1H 分解

将请求拆分为六个维度：

维度	问题	差距示例
What（是什么）	具体要构建或更改什么？	“构建身份验证”——登录？注册？密码重置？SSO？
Who（谁）	谁会使用？有哪些角色或权限？	“用户可以编辑”——所有用户？仅限管理员？所有者？
Where（在哪里）	它位于哪里？涉及哪个系统或服务？	“添加到 API”——哪个 API？新增端点？现有端点？
When（何时）	什么会触发它？生命周期是什么？	“发送通知”——实时发送？批量发送？由什么事件触发？
Why（为什么）	要解决什么问题？成功标准是什么？	“提升性能”——延迟？吞吐量？成本？
How（如何）	实现方面有哪些限制？	“使用现有技术栈”——具体使用哪些部分？有例外吗？

阶段 2：歧义评分

评估每个维度的清晰程度：

• 明确——已明确说明，或可根据上下文明确推断
• 可假定——未说明，但存在合理的默认值（说明默认值）
• 有歧义——存在多种合理解释，猜错会浪费工作

统计有歧义的维度：

• 0 个有歧义 → 直接放行。 立即继续。说明：“范围明确。开始执行。”
• 1–2 个有歧义 → 快速澄清。 提出 1–2 个有针对性的问题，并说明默认值。
• 3 个或以上有歧义 → 必须澄清。 提出影响最大的 3 个问题。在收到答复前不要继续。

阶段 3：生成澄清问题

针对每个有歧义的维度（最多 3 个，按影响程度排序）：

**Q[N]: [Specific question]**
Options: (a) [option] (b) [option] (c) [option]
My default: (b) — [why this is the reasonable default]
Impact: [what changes depending on the answer]

阶段 4：确认并继续

收到答复后（或用户表示“按默认值处理”）：

1. 用 3–5 个项目符号重述已澄清的范围
2. 说明任何剩余的假设（评级为“可假定”，而非“有歧义”）
3. 开始执行

输出格式

## Scope Analysis: [Request Summary]

### 5W1H Decomposition
| Dimension | Status | Detail |
|:----------|:-------|:-------|
| What | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Who | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Where | Clear / Assumable / Ambiguous | [extracted or missing info] |
| When | Clear / Assumable / Ambiguous | [extracted or missing info] |
| Why | Clear / Assumable / Ambiguous | [extracted or missing info] |
| How | Clear / Assumable / Ambiguous | [extracted or missing info] |

### Ambiguity Score: [N]/6 → [Green light / Quick clarify / Must clarify]

### Questions (if any)

**Q1: [Question]**
Options: (a) ... (b) ... (c) ...
My default: (b) — [reason]
Impact: [what changes]

**Q2: ...**

### Clarified Scope (after answers)
- [bullet 1]
- [bullet 2]
- [bullet 3]

### Remaining Assumptions
- [assumption 1] — rated Assumable because [reason]

质量校准

糟糕的范围澄清（不要这样做）

User: "Build me an auth system"

AI: I have a few questions before we start:
1. What programming language would you like to use?
2. What database do you prefer?
3. Do you want tests?
4. What's your timeline?
5. How many users do you expect?
6. Should it be containerized?
7. What CI/CD platform do you use?

问题：

• 7 个问题——令人不堪重负，其中大多数与身份验证范围无关
• “用什么语言？”——看看项目就知道了
• “需要测试吗？”——始终需要，这不是范围问题
• “你的时间安排是什么？”——不会改变你要构建的内容
• 没有多选题，也没有说明默认值
• 没有 5W1H 结构，只是一通想到什么说什么

良好的范围澄清（这样做）

User: "Build me an auth system"

## Scope Analysis: Auth System

### 5W1H Decomposition
| Dimension | Status | Detail |
|:----------|:-------|:-------|
| What | Ambiguous | "Auth system" — login only? signup? password reset? SSO? |
| Who | Ambiguous | User roles not specified — single role or RBAC? |
| Where | Clear | Next.js app (inferred from project structure) |
| When | Clear | Standard request-response auth flow |
| Why | Assumable | Secure user access (standard) |
| How | Assumable | Project uses TypeScript + Prisma (from codebase) |

### Ambiguity Score: 2/6 → Quick clarify

**Q1: What auth flows are needed?**
Options: (a) Email/password login only (b) Login + signup + password reset (c) Full OAuth2 with Google/GitHub providers
My default: (b) — most apps need the complete basic flow
Impact: (a) = 2 hours, (b) = 4 hours, (c) = 8 hours + provider setup

**Q2: User roles?**
Options: (a) Single role — all users equal (b) Admin + User (c) Custom RBAC with permissions
My default: (a) — add roles later when needed (YAGNI)
Impact: (c) requires permission tables, middleware, and role management UI

为什么这样更好：

• 只有 2 个问题，且都影响重大
• 采用选项明确的多选题
• 说明默认方案及其理由
• 量化影响（耗时、复杂度）
• 已根据上下文解决 4 个维度（没有多余提问）
• 5W1H 结构让分析过程一目了然

适用场景

• 开始任何非简单任务或功能需求时
• 请求中出现“系统”“模块”“功能”“改进”“修复”等词，但没有具体说明时
• 发现自己正在猜测用户想要什么时
• 任务根据不同理解可能耗时 2 小时或 2 周时
• 调用任何其他 Stack Skill 之前（先澄清范围，再研究、审查或规划）

不适用场景

• 提供了复现步骤的 Bug 报告（范围就是该 Bug）
• 明确、详细的规格说明（“添加一个 GET /users 端点，返回 id 和 name”）
• 在上下文已明确的持续对话中提出的后续任务
• 简单问题（“这个函数是做什么的？”）
• 用户明确表示“直接做”或“自行判断”时

注意事项

1. 能查到的就别问。 如果项目中有 package.json、tsconfig.json 或现有代码，先检查再问“使用什么语言/框架？”。这不是澄清，而是偷懒。
2. 最多 3 个问题是硬性上限。 如果需要更多问题，就应将请求拆分为子任务，而不是继续追问。
3. 风格偏好不是范围问题。 命名规范、文件夹结构、格式排版——遵循项目惯例或采用合理的默认方案。绝不要因此卡住进度。
4. 每个问题都要说明默认方案。 用户应该可以说“按默认方案来”并跳过所有问题。如果没有说明默认方案，就算没做好。
5. 明确同意就立即开始。 如果请求清楚，就说明这一点并立即继续。不要为了显得周全而提问。

集成说明

• 最先执行： swing-clarify 的设计目的就是优先运行。澄清后的范围会为所有其他技能提供依据。
• 配合 swing-research： 澄清范围 → 聚焦研究问题（避免研究错误的方向）
• 配合 swing-review： 澄清范围 → 根据实际需求进行审查（避免依据臆测的需求进行审查）
• 配合 swing-options： 澄清约束 → 更好地生成选项（约束决定哪些做法是常规或非常规的）
• 配合 swing-mortem： 澄清假设 → 更具体的失败场景
• 配合 swing-trace： 澄清范围 → 在第 1 阶段更清晰地隔离主张（减少需要追踪的模糊假设）