clarify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

User Input

用户输入

text

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

text

$ARGUMENTS

你必须先考虑用户输入（如果不为空），再继续操作。

Outline

大纲

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking the bb-plan skill. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

Locate the current feature directory and verify the feature spec exists. Parse minimal payload fields:
- ```
FEATURE_DIR
```
- ```
FEATURE_SPEC
```
- (Optionally capture
```
IMPL_PLAN
```
  ,
```
TASKS
```
  for future chained flows.)
- If the feature directory or spec cannot be found, abort and instruct user to run the bb-specify skill first or verify feature branch environment.
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

Functional Scope & Behavior:
- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles / personas differentiation
Domain & Data Model:
- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions
- Data volume / scale assumptions
Interaction & UX Flow:
- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes
Non-Functional Quality Attributes:
- Performance (latency, throughput targets)
- Scalability (horizontal/vertical, limits)
- Reliability & availability (uptime, recovery expectations)
- Observability (logging, metrics, tracing signals)
- Security & privacy (authN/Z, data protection, threat assumptions)
- Compliance / regulatory constraints (if any)
Integration & External Dependencies:
- External services/APIs and failure modes
- Data import/export formats
- Protocol/versioning assumptions
Edge Cases & Failure Handling:
- Negative scenarios
- Rate limiting / throttling
- Conflict resolution (e.g., concurrent edits)
Constraints & Tradeoffs:
- Technical constraints (language, storage, hosting)
- Explicit tradeoffs or rejected alternatives
Terminology & Consistency:
- Canonical glossary terms
- Avoided synonyms / deprecated terms
Completion Signals:
- Acceptance criteria testability
- Measurable Definition of Done style indicators
Misc / Placeholders:
- TODO markers / unresolved decisions
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
For each category with Partial or Missing status, add a candidate question opportunity unless:
- Clarification would not materially change implementation or validation strategy
- Information is better deferred to planning phase (note internally)
Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
- Maximum of 10 total questions across the whole session.
- Each question must be answerable with EITHER:
  - A short multiple-choice selection (2-5 distinct, mutually exclusive options), OR
  - A one-word / short-phrase answer (explicitly constrain: "Answer in <=5 words").
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

Sequential questioning loop (interactive):

Present EXACTLY ONE question at a time.

For multiple-choice questions:

Analyze all options and determine the most suitable option based on:
- Best practices for the project type
- Common patterns in similar implementations
- Risk reduction (security, performance, maintainability)
- Alignment with any explicit project goals or constraints visible in the spec
Present your recommended option prominently at the top with clear reasoning (1-2 sentences explaining why this is the best choice).

Format as:

**Recommended:** Option [X] - <reasoning>

Then render all options as a Markdown table:

Option	Description
A	<Option A description>
B	<Option B description>
C	<Option C description> (add D/E as needed up to 5)
Short	Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate)

After the table, add:

You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

For short-answer style (no meaningful discrete options):

Provide your suggested answer based on best practices and context.

Format as:

**Suggested:** <your proposed answer> - <brief reasoning>

Then output:

Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

After the user answers:
- If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
- Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
- If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
- Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
Stop asking further questions when:
- All critical ambiguities resolved early (remaining queued items become unnecessary), OR
- User signals completion ("done", "good", "no more"), OR
- You reach 5 asked questions.
Never reveal future queued questions in advance.
If no valid questions exist at start, immediately report no critical ambiguities.

Integration after EACH accepted answer (incremental update approach):
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
- For the first integrated answer in this session:
  - Ensure a
```
## Clarifications
```
    section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
  - Under it, create (if not present) a
```
### Session YYYY-MM-DD
```
    subheading for today.
- Append a bullet line immediately after acceptance:
```
- Q: <question> -> A: <final answer>
```
  .
- Then immediately apply the clarification to the most appropriate section(s):
  - Functional ambiguity -> Update or add a bullet in Functional Requirements.
  - User interaction / actor distinction -> Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
  - Data shape / entities -> Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
  - Non-functional constraint -> Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
  - Edge case / negative flow -> Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
  - Terminology conflict -> Normalize term across spec; retain original only if necessary by adding
```
(formerly referred to as "X")
```
    once.
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
- Keep each inserted clarification minimal and testable (avoid narrative drift).
Validation (performed after EACH write plus final pass):
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
- Total asked (accepted) questions <= 5.
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
- Markdown structure valid; only allowed new headings:
```
## Clarifications
```
  ,
```
### Session YYYY-MM-DD
```
  .
- Terminology consistency: same canonical term used across all updated sections.
Write the updated spec back to
```
FEATURE_SPEC
```
.
Report completion (after questioning loop ends or early termination):
- Number of questions asked & answered.
- Path to updated spec.
- Sections touched (list names).
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
- If any Outstanding or Deferred remain, recommend whether to proceed to the bb-plan skill or run the bb-clarify skill again later post-plan.
- Suggested next step.

Behavior rules:

If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
If spec file missing, instruct user to run the bb-specify skill first (do not create a new spec here).
Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
Avoid speculative tech stack questions unless the absence blocks functional clarity.
Respect user early termination signals ("stop", "done", "proceed").
If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: {ARGS}

目标：检测并减少当前功能规格说明书（feature spec）中的模糊点或缺失的决策点，并将澄清内容直接记录到规格文件中。

注意：此澄清工作流需在调用bb-plan skill之前运行并完成。如果用户明确表示要跳过澄清环节（例如探索性研究），你可以继续操作，但必须警告后续返工风险会增加。

执行步骤：

定位当前功能目录并验证功能规格文件是否存在。解析最小有效载荷字段：
- ```
FEATURE_DIR
```
- ```
FEATURE_SPEC
```
- （可选捕获
```
IMPL_PLAN
```
  、
```
TASKS
```
  用于后续链式流程。）
- 如果无法找到功能目录或规格文件，终止操作并指导用户先运行bb-specify skill，或验证功能分支环境。
- 对于参数中的单引号（如"I'm Groot"），使用转义语法：例如'I'\''m Groot'（或尽可能使用双引号："I'm Groot"）。
加载当前规格文件。使用以下分类法进行结构化的模糊性与覆盖范围扫描。针对每个类别标记状态：清晰/部分缺失/完全缺失。生成用于优先级排序的内部覆盖映射（除非不会提出任何问题，否则不要输出原始映射）。

功能范围与行为：
- 核心用户目标与成功标准
- 明确的范围外声明
- 用户角色/人物区分
领域与数据模型：
- 实体、属性、关系
- 标识与唯一性规则
- 生命周期/状态转换
- 数据量/规模假设
交互与用户体验流程：
- 关键用户旅程/序列
- 错误/空数据/加载状态
- 可访问性或本地化说明
非功能性质量属性：
- 性能（延迟、吞吐量目标）
- 可扩展性（水平/垂直扩展、限制）
- 可靠性与可用性（正常运行时间、恢复预期）
- 可观测性（日志、指标、追踪信号）
- 安全性与隐私（身份认证/授权、数据保护、威胁假设）
- 合规性/监管约束（如有）
集成与外部依赖：
- 外部服务/API及其故障模式
- 数据导入/导出格式
- 协议/版本假设
边缘案例与故障处理：
- 负面场景
- 速率限制/流量控制
- 冲突解决（例如并发编辑）
约束与权衡：
- 技术约束（语言、存储、托管）
- 明确的权衡或被否决的替代方案
术语与一致性：
- 标准术语表术语
- 禁用的同义词/已弃用术语
完成信号：
- 验收标准的可测试性
- 可衡量的完成定义（Definition of Done）式指标
其他/占位符：
- TODO标记/未解决的决策
- 缺乏量化的模糊形容词（如"健壮的"、"直观的"）
对于每个状态为部分缺失或完全缺失的类别，添加候选问题机会，除非：
- 澄清不会实质性改变实现或验证策略
- 信息最好推迟到规划阶段（内部记录）
（内部）生成优先级排序的候选澄清问题队列（最多5个）。不要一次性输出所有问题。应用以下约束：
- 整个会话中最多10个问题。
- 每个问题必须可以通过以下方式之一回答：
  - 简短的多项选择（2-5个不同、互斥的选项），或者
  - 单个单词/短语回答（明确限制："回答不超过5个单词"）。
- 仅包含那些答案会对架构、数据建模、任务分解、测试设计、用户体验行为、运营就绪性或合规验证产生实质性影响的问题。
- 确保类别覆盖平衡：优先覆盖影响最高的未解决类别；当存在单个高影响领域（如安全态势）未解决时，避免提出两个低影响问题。
- 排除已回答的问题、琐碎的风格偏好或计划层面的执行细节（除非会阻碍正确性）。
- 优先选择能减少后续返工风险或防止验收测试不一致的澄清问题。
- 如果有超过5个类别未解决，根据（影响×不确定性）启发式算法选择前5个。
顺序提问循环（交互式）：
- 每次只呈现一个问题。
- 对于多项选择问题：
  - 分析所有选项并根据以下因素确定最合适的选项：
    - 项目类型的最佳实践
    - 类似实现中的常见模式
    - 风险降低（安全、性能、可维护性）
    - 与规格中可见的任何明确项目目标或约束的一致性
  - 将你的推荐选项突出显示在顶部，并附上清晰的理由（1-2句话解释为什么这是最佳选择）。
  - 格式为：
```
**推荐选项：** 选项[X] - <理由>
```
  - 然后将所有选项渲染为Markdown表格：
  选项描述
  A <选项A描述>
  B <选项B描述>
  C <选项C描述>（必要时添加D/E，最多5个）
  自定义提供不同的简短回答（≤5个单词）（仅在适合自由格式替代时包含）
  - 在表格后添加：
```
你可以回复选项字母（例如"A"），通过说"yes"或"recommended"接受推荐，或提供自己的简短回答。
```
- 对于简短回答类型（无有意义的离散选项）：
  - 根据最佳实践和上下文提供你的建议答案。
  - 格式为：
```
**建议答案：** <你的提议答案> - <简要理由>
```
  - 然后输出：
```
格式：简短回答（≤5个单词）。你可以通过说"yes"或"suggested"接受建议，或提供自己的答案。
```
- 用户回答后：
  - 如果用户回复"yes"、"recommended"或"suggested"，则使用你之前陈述的推荐/建议作为答案。
  - 否则，验证答案是否对应某个选项或符合≤5个单词的约束。
  - 如果答案模糊，请求快速澄清（此重试不计入新问题）。
  - 一旦答案令人满意，将其记录到工作内存中（暂不写入磁盘），然后进入下一个队列中的问题。
- 在以下情况停止提问：
  - 所有关键模糊点已提前解决（剩余队列项变得不必要），或者
  - 用户表示完成（"done"、"good"、"no more"），或者
  - 已提出5个问题。
- 切勿提前透露未来队列中的问题。
- 如果一开始就没有有效问题，立即报告未检测到关键模糊点。
每次接受答案后的整合（增量更新方式）：
- 维护规格说明书的内存表示（在开始时加载一次）以及原始文件内容。
- 对于本次会话中的第一个整合答案：
  - 确保存在
```
## Clarifications
```
    章节（如果缺失，根据规格模板在最高级别的上下文/概述章节之后创建）。
  - 在其下创建（如果不存在）
```
### Session YYYY-MM-DD
```
    子标题（YYYY-MM-DD为当天日期）。
- 接受答案后立即添加一个项目符号行：
```
- Q: <问题> -> A: <最终答案>
```
  。
- 然后立即将澄清内容应用到最合适的章节：
  - 功能模糊点 -> 更新或添加功能需求中的项目符号。
  - 用户交互/角色区分 -> 更新用户故事或角色小节（如果存在），添加澄清后的角色、约束或场景。
  - 数据结构/实体 -> 更新数据模型（添加字段、类型、关系），保留顺序；简洁记录添加的约束。
  - 非功能性约束 -> 在非功能性/质量属性章节中添加/修改可衡量的标准（将模糊形容词转换为指标或明确目标）。
  - 边缘案例/负面流程 -> 在边缘案例/错误处理下添加新项目符号（如果模板提供占位符，则创建此小节）。
  - 术语冲突 -> 在整个规格中统一术语；仅在必要时保留原始术语，添加
```
(原称为"X")
```
    一次。
- 如果澄清内容使之前的模糊陈述无效，则替换该陈述而非重复；不要留下过时的矛盾文本。
- 每次整合后保存规格文件，以最小化上下文丢失的风险（原子覆盖）。
- 保留格式：不要重新排序无关章节；保持标题层级不变。
- 保持每个插入的澄清内容简洁且可测试（避免偏离主题）。
验证（每次写入后以及最终检查时执行）：
- 澄清会话包含每个已接受答案对应的一个项目符号（无重复）。
- 已提出（已接受）的问题总数≤5。
- 更新后的章节中没有新答案本应解决的遗留模糊占位符。
- 不存在矛盾的早期陈述（扫描并删除现在无效的替代选项）。
- Markdown结构有效；仅允许新增标题：
```
## Clarifications
```
  、
```
### Session YYYY-MM-DD
```
  。
- 术语一致性：所有更新章节中使用相同的标准术语。
将更新后的规格写回
```
FEATURE_SPEC
```
。
报告完成（提问循环结束或提前终止后）：
- 已提出并回答的问题数量。
- 更新后的规格文件路径。
- 涉及的章节（列出名称）。
- 覆盖范围汇总表，列出每个分类法类别及其状态：已解决（原为部分缺失/完全缺失且已处理）、推迟（超出问题配额或更适合规划阶段）、清晰（已足够）、未解决（仍为部分缺失/完全缺失但影响较低）。
- 如果存在任何未解决或推迟的类别，建议是继续调用bb-plan skill还是在规划后再次运行bb-clarify skill。
- 建议的下一步操作。

选项	描述
A	<选项A描述>
B	<选项B描述>
C	<选项C描述>（必要时添加D/E，最多5个）
自定义	提供不同的简短回答（≤5个单词）（仅在适合自由格式替代时包含）

行为规则：

如果未发现有意义的模糊点（或所有潜在问题影响较低），回复："未检测到值得正式澄清的关键模糊点。"并建议继续操作。
如果规格文件缺失，指导用户先运行bb-specify skill（不要在此创建新规格）。
已提出的问题总数切勿超过5个（单个问题的澄清重试不计入新问题）。
避免推测性技术栈问题，除非其缺失会阻碍功能清晰度。
尊重用户的提前终止信号（"stop"、"done"、"proceed"）。
如果因覆盖范围完整而未提出任何问题，输出简洁的覆盖范围汇总（所有类别为清晰），然后建议推进。
如果已达到问题配额但仍有高影响类别未解决，明确在推迟类别下标记它们并附上理由。

优先级上下文：{ARGS}