Back to Details

swing-clarify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scope Clarifier

范围澄清器

Prevents the most common AI failure: rushing to execute before understanding what's actually needed.
Addresses the cognitive failure of Premature Closure — AI interprets ambiguous requests using defaults and assumptions instead of asking, producing confident output that answers the wrong question.
避免最常见的AI失败案例：在理解实际需求前就急于执行任务。
解决Premature Closure这一认知缺陷——AI会用默认设置和假设解读模糊请求，而非主动询问，最终产出自信满满的输出，却答非所问。

Rules (Absolute)

绝对规则

  1. Never execute before clarifying. If ambiguity score is above threshold, generate questions FIRST. Do not start implementation, research, or analysis until scope is confirmed.
  2. Maximum 3 questions. Respect the user's time. If more than 3 questions are needed, the request needs decomposition, not interrogation. Ask the 3 highest-impact questions.
  3. Questions must be actionable. Every question must change what you build. "What's your timeline?" is only valid if it affects scope. "Should this handle authentication?" is always valid if auth wasn't mentioned.
  4. Prefer multiple choice over open-ended. "Should auth use (a) session cookies, (b) JWT, or (c) OAuth2 with a provider?" beats "How should auth work?"
  5. State your default assumption. For each question, state what you WOULD assume if the user doesn't answer. This lets them skip questions where the default is fine.
  6. Clear requests get a green light, not questions. If the request is unambiguous, say so and proceed. Do not ask questions for the sake of asking.
  7. Never block on style preferences. Naming conventions, formatting, folder structure — these are not scope questions. Use project conventions or sensible defaults.
  1. 绝对不要在澄清前执行任务。如果模糊度评分超过阈值，先生成问题。在范围确认前，不要开始实现、研究或分析工作。
  2. 最多提出3个问题。尊重用户的时间。如果需要超过3个问题，说明请求需要拆解，而非逐一询问。选择影响最大的3个问题提出。
  3. 问题必须具有可操作性。每个问题都要能改变最终的实现内容。“你的时间线是什么？”只有在它会影响范围时才有效。“是否需要处理身份验证？”只要原文未提及身份验证，这个问题就始终有效。
  4. 优先使用选择题而非开放式问题。“身份验证应使用(a)会话Cookie、(b)JWT，还是(c)带服务商的OAuth2？”比“身份验证应该如何实现？”更好。
  5. 说明你的默认假设。针对每个问题，说明如果用户不回答你会采用的默认方案。这样用户可以直接跳过默认方案符合需求的问题。
  6. 清晰的请求直接放行，无需提问。如果请求没有歧义，直接说明并开始执行。不要为了提问而提问。
  7. 永远不要因风格偏好停滞。命名规范、格式、文件夹结构——这些不属于范围问题。遵循项目规范或合理的默认设置即可。

Process

流程

Stage 1: 5W1H Decomposition

阶段1：5W1H分解

Break the request into six dimensions:
DimensionQuestionExample Gap
WhatWhat exactly is being built/changed?"Build auth" — login? signup? password reset? SSO?
WhoWho uses this? What roles/permissions?"Users can edit" — all users? admins only? owners?
WhereWhere does this live? What system/service?"Add to the API" — which API? new endpoint? existing?
WhenWhat triggers this? What's the lifecycle?"Send notifications" — real-time? batched? on what event?
WhyWhat problem does this solve? What's the success criteria?"Improve performance" — latency? throughput? cost?
HowAre there constraints on implementation?"Use the existing stack" — which parts? any exceptions?
将请求拆解为六个维度：
维度问题示例缺口
What（内容）具体要构建/修改什么？“构建身份验证系统”——仅登录？包含注册？密码重置？单点登录(SSO)？
Who（对象）谁会使用它？有哪些角色/权限？“用户可编辑”——所有用户？仅管理员？仅所有者？
Where（场景）部署在何处？对应哪个系统/服务？“添加到API中”——哪个API？新端点？现有端点？
When（时机）触发条件是什么？生命周期是怎样的？“发送通知”——实时发送？批量发送？基于什么事件触发？
Why（目的）要解决什么问题？成功标准是什么？“提升性能”——降低延迟？提高吞吐量？减少成本？
How（方式）实现上有哪些约束？“使用现有技术栈”——具体使用哪些部分？是否有例外？

Stage 2: Ambiguity Scoring

阶段2：模糊度评分

For each dimension, rate clarity:
  • Clear — explicitly stated or unambiguously implied by context
  • Assumable — not stated, but a reasonable default exists (state the default)
  • Ambiguous — multiple valid interpretations, wrong guess = wasted work
Count the Ambiguous dimensions:
  • 0 Ambiguous → Green light. Proceed immediately. State: "Scope is clear. Proceeding."
  • 1-2 Ambiguous → Quick clarify. Ask 1-2 targeted questions with defaults.
  • 3+ Ambiguous → Must clarify. Ask up to 3 highest-impact questions. Do not proceed until answered.
针对每个维度，评估清晰度：
  • 清晰——明确说明，或通过上下文可无歧义推断
  • 可假设——未说明，但存在合理的默认方案（需说明默认内容）
  • 模糊——存在多种合理解读，错误猜测会导致工作白费
统计模糊维度的数量：
  • 0个模糊维度 → 直接放行。立即开始执行。说明：“范围清晰，开始执行。”
  • 1-2个模糊维度 → 快速澄清。提出1-2个针对性问题并附上默认方案。
  • 3个及以上模糊维度 → 必须澄清。提出最多3个影响最大的问题。未得到答复前不要开始执行。

Stage 3: Generate Clarifying Questions

阶段3：生成澄清问题

For each Ambiguous dimension (up to 3, prioritized by impact):
**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]
针对每个模糊维度（最多3个，按影响优先级排序）：
**Q[N]: [具体问题]**
选项：(a) [选项] (b) [选项] (c) [选项]
我的默认方案：(b) — [说明该默认方案合理的原因]
影响：[答案不同会带来哪些变化]

Stage 4: Confirm and Proceed

阶段4：确认并执行

After receiving answers (or user says "go with defaults"):
  1. Restate the clarified scope in 3-5 bullet points
  2. Note any remaining assumptions (rated as Assumable, not Ambiguous)
  3. Proceed with execution
收到答复后（或用户表示“使用默认方案”）：
  1. 用3-5个要点重述已澄清的范围
  2. 列出所有剩余的假设（归类为“可假设”，而非“模糊”）
  3. 开始执行

Output Format

输出格式

markdown
undefined
markdown
undefined

Scope Analysis: [Request Summary]

Scope Analysis: [Request Summary]

5W1H Decomposition

5W1H Decomposition

DimensionStatusDetail
WhatClear / Assumable / Ambiguous[extracted or missing info]
WhoClear / Assumable / Ambiguous[extracted or missing info]
WhereClear / Assumable / Ambiguous[extracted or missing info]
WhenClear / Assumable / Ambiguous[extracted or missing info]
WhyClear / Assumable / Ambiguous[extracted or missing info]
HowClear / Assumable / Ambiguous[extracted or missing info]
DimensionStatusDetail
WhatClear / Assumable / Ambiguous[extracted or missing info]
WhoClear / Assumable / Ambiguous[extracted or missing info]
WhereClear / Assumable / Ambiguous[extracted or missing info]
WhenClear / Assumable / Ambiguous[extracted or missing info]
WhyClear / Assumable / Ambiguous[extracted or missing info]
HowClear / Assumable / Ambiguous[extracted or missing info]

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

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

Questions (if any)

Questions (if any)

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

Clarified Scope (after answers)

Clarified Scope (after answers)

  • [bullet 1]
  • [bullet 2]
  • [bullet 3]
  • [bullet 1]
  • [bullet 2]
  • [bullet 3]

Remaining Assumptions

Remaining Assumptions

  • [assumption 1] — rated Assumable because [reason]
undefined
  • [assumption 1] — rated Assumable because [reason]
undefined

Quality Calibration

质量校准

BAD Scope Clarification (Don't Do This)

错误的范围澄清（请勿效仿）

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?
Problems:
  • 7 questions — overwhelming, most don't affect auth scope
  • "What language?" — look at the project, it's obvious
  • "Do you want tests?" — always yes, not a scope question
  • "What's your timeline?" — doesn't change what you build
  • No multiple choice, no defaults stated
  • No 5W1H structure, just a brain dump
用户：“给我构建一个身份验证系统”

AI：开始前我有几个问题：
1. 你想用什么编程语言？
2. 你偏好什么数据库？
3. 你需要测试吗？
4. 你的时间线是什么？
5. 你预计有多少用户？
6. 要不要容器化？
7. 你用什么CI/CD平台？
问题：
  • 7个问题——数量过多，多数不影响身份验证的范围
  • “用什么语言？”——查看项目即可得知，显而易见
  • “需要测试吗？”——答案永远是肯定的，不属于范围问题
  • “时间线是什么？”——不会改变要构建的内容
  • 没有选择题，未说明默认方案
  • 没有采用5W1H结构，只是随意罗列问题

GOOD Scope Clarification (Do This)

正确的范围澄清（请效仿）

User: "Build me an auth system"
用户：“给我构建一个身份验证系统”

Scope Analysis: Auth System

Scope Analysis: Auth System

5W1H Decomposition

5W1H Decomposition

DimensionStatusDetail
WhatAmbiguous"Auth system" — login only? signup? password reset? SSO?
WhoAmbiguousUser roles not specified — single role or RBAC?
WhereClearNext.js app (inferred from project structure)
WhenClearStandard request-response auth flow
WhyAssumableSecure user access (standard)
HowAssumableProject uses TypeScript + Prisma (from codebase)
DimensionStatusDetail
WhatAmbiguous"Auth system" — login only? signup? password reset? SSO?
WhoAmbiguousUser roles not specified — single role or RBAC?
WhereClearNext.js app (inferred from project structure)
WhenClearStandard request-response auth flow
WhyAssumableSecure user access (standard)
HowAssumableProject uses TypeScript + Prisma (from codebase)

Ambiguity Score: 2/6 → Quick clarify

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

Why this is better:
- Only 2 questions, both high-impact
- Multiple choice with clear options
- Defaults stated with reasoning
- Impact quantified (hours, complexity)
- 4 dimensions already resolved from context (no wasted questions)
- 5W1H structure makes the analysis transparent
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结构让分析过程透明化

When to Use

使用场景

  • Start of any non-trivial task or feature request
  • When a request contains words like "system", "module", "feature", "improve", "fix" without specifics
  • When you catch yourself making assumptions about what the user wants
  • When a task could take 2 hours or 2 weeks depending on interpretation
  • Before invoking any other Stack Skill (clarify scope first, then research/review/plan)
  • 任何非琐碎任务或功能请求的启动阶段
  • 当请求包含“系统”、“模块”、“功能”、“优化”、“修复”等词汇但未说明细节时
  • 当你发现自己在假设用户需求时
  • 当任务的执行时间可能因解读不同从2小时变成2周时
  • 在调用任何其他Stack Skill之前（先澄清范围，再进行研究/评审/规划）

When NOT to Use

禁用场景

  • Bug reports with reproduction steps (scope is the bug)
  • Explicit, detailed specifications ("Add a GET /users endpoint returning id and name")
  • Follow-up tasks in an ongoing conversation where context is established
  • Quick questions ("What does this function do?")
  • When the user explicitly says "just do it" or "use your judgment"
  • 带有复现步骤的Bug报告（范围就是Bug本身）
  • 明确、详细的规格说明（例如“添加一个返回id和name的GET /users端点”）
  • 持续对话中的后续任务（上下文已明确）
  • 简单问题（例如“这个函数的作用是什么？”）
  • 当用户明确表示“直接做”或“自行判断”时

Integration Notes

集成说明

  • Before everything: swing-clarify is designed to run FIRST. Clarified scope feeds into all other skills.
  • With swing-research: Clarified scope → focused research questions (prevents researching the wrong thing)
  • With swing-review: Clarified scope → review against actual requirements (prevents reviewing against assumed requirements)
  • With swing-options: Clarified constraints → better option generation (constraints define what's conventional vs unconventional)
  • With swing-mortem: Clarified assumptions → more specific failure scenarios
  • With swing-trace: Clarified scope → clearer claim isolation in Stage 1 (fewer ambiguous assumptions to trace)
  • 优先执行：swing-clarify的设计定位是首先运行。已澄清的范围会为所有其他技能提供输入。
  • 与swing-research集成：已澄清的范围→聚焦的研究问题（避免研究错误内容）
  • 与swing-review集成：已澄清的范围→对照实际需求进行评审（避免基于假设的需求进行评审）
  • 与swing-options集成：已澄清的约束→更优的方案生成（约束定义了常规方案与非常规方案的边界）
  • 与swing-mortem集成：已澄清的假设→更具体的失败场景
  • 与swing-trace集成：已澄清的范围→在阶段1中更清晰地隔离需求（减少需要追踪的模糊假设）