Back to Details

spec-product-clarify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

spec-product-clarify（R1：澄清 + 方案决策）

spec-product-clarify (R1: Clarification + Solution Decision)

概览

Overview

将 
{FEATURE_DIR}/requirements/raw.md
的原始输入，先通过多轮持续澄清收敛到“无未确认关键点”，再产出可评审的决策文档 
{FEATURE_DIR}/requirements/solution.md
；澄清过程必须可追溯（回写到 
raw.md/## 澄清记录
）。
开始时宣布：「我正在使用 spec-product-clarify 技能澄清需求并产出 solution.md。」
硬规则：澄清未完成时，禁止创建/更新 
solution.md
。
Take the original input from 
{FEATURE_DIR}/requirements/raw.md
, first converge to "no unconfirmed key points" through multiple rounds of continuous clarification, then produce a reviewable decision document 
{FEATURE_DIR}/requirements/solution.md
; the clarification process must be traceable (written back to 
raw.md/## Clarification Records
).
Announce at the start: "I am using the spec-product-clarify skill to clarify requirements and produce solution.md."
Hard Rule: Prohibit creating/updating 
solution.md
until clarification is completed.

门禁 / 停止（严格执行）

Gates / Stop (Strictly Enforced)

REQUIRED SUB-SKILL：先执行 
spec-context
并在对话中回显 
FEATURE_DIR=...
。
立刻停止（满足其一即可）：
  • 未得到 
    FEATURE_DIR
  • {FEATURE_DIR}/requirements/raw.md
    不存在或为空
  • 路径/分支不确定、指令互相冲突、或不理解某条指令（禁止猜测/编造）
  • 用户明确要求停止本次任务（不再继续澄清/不再产出任何文档）
  • 用户声明已更新/改写 
    raw.md
    或关键约束变更，但无法读取/确认最新 
    raw.md
    （禁止仅凭口头转述继续写）
读取/写入约定：
  • 读：
    {FEATURE_DIR}/requirements/raw.md
    （必读）；
    project/memory/glossary.md
    （如存在且需要术语口径）
  • 写：
    {FEATURE_DIR}/requirements/raw.md
    仅追加/更新 
    ## 澄清记录
    ；
    {FEATURE_DIR}/requirements/solution.md
    为唯一决策入口（仅在澄清完成后创建/更新）
违反门禁=违反精神：即使“时间紧/老板催/用户不想跑脚本”，也禁止在未知上下文里读写文件。
REQUIRED SUB-SKILL: First execute 
spec-context
and echo 
FEATURE_DIR=...
in the conversation.
Stop immediately (if any of the following is met):
  • FEATURE_DIR
    not obtained
  • {FEATURE_DIR}/requirements/raw.md
    does not exist or is empty
  • Path/branch is uncertain, instructions conflict with each other, or an instruction is not understood (prohibit guessing/making up content)
  • User explicitly requests to stop this task (no further clarification/no more documents to produce)
  • User states that 
    raw.md
    has been updated/revised or key constraints have changed, but the latest 
    raw.md
    cannot be read/confirmed (proceeding based solely on verbal statements is prohibited)
Reading/Writing Conventions:
  • Read: 
    {FEATURE_DIR}/requirements/raw.md
    (mandatory); 
    project/memory/glossary.md
    (if exists and terminology alignment is needed)
  • Write: Only append/update 
    ## Clarification Records
    in 
    {FEATURE_DIR}/requirements/raw.md
    ; 
    {FEATURE_DIR}/requirements/solution.md
    is the only decision entry (create/update only after clarification is completed)
Violating the gates = violating the core principle: Even if "time is tight/boss is urging/user doesn't want to run the script", prohibit reading/writing files in unknown contexts.

常见借口（出现即按门禁执行）

Common Excuses (Execute Gates Immediately If Present)

  • “时间紧/马上评审/老板催”：仍必须先得到 
    FEATURE_DIR
    并读取 
    raw.md
    ；否则停止
  • “路径你自己看着写”：禁止猜测路径；必须由 
    spec-context
    给出 
    FEATURE_DIR
  • “我只能回复一次/你一次问完”：仍只问 1 个最高杠杆问题；其余未知进入验证清单
  • “别回头看 raw”：如输入变更/新增约束，必须以 
    raw.md
    为准并重新读取；做不到则停止
  • “别再问了，直接出 solution/prd”：澄清未完成时禁止产出；改为继续问 1 个最高杠杆选择题，并解释“缺此答案无法形成可评审决策”
  • “你给我选：继续澄清 / 进 R2 / 快速通道”：禁止提供分岔选项；若仍有未澄清点，默认继续澄清直到清零
  • "Time is tight/review is imminent/boss is urging": Still must first obtain 
    FEATURE_DIR
    and read 
    raw.md
    ; stop otherwise
  • "You decide the path yourself": Prohibit guessing the path; 
    FEATURE_DIR
    must be provided by 
    spec-context
  • "I can only reply once/ask all questions at once": Still only ask 1 highest-leverage question; other unknowns are added to the verification list
  • "Don't look back at raw": If input changes/new constraints are added, must rely on 
    raw.md
    and re-read it; stop if this cannot be done
  • "Stop asking, directly produce solution/prd": Prohibit producing output until clarification is completed; instead, continue to ask 1 highest-leverage multiple-choice question and explain "this answer is missing and cannot form a reviewable decision"
  • "Choose for me: Continue clarification / Enter R2 / Fast track": Prohibit providing branching options; if there are still unclarified points, default to continuing clarification until all are resolved

最小循环（把问题问小，把结论写进去）

Minimum Loop (Narrow Down Questions, Document Conclusions)

重复执行以下闭环，直到停止：
  1. 从 
    raw.md
    选 1 个最高杠杆未知（能最大减少方案分歧）
  2. 问 1 个可裁决选择题：2–4 选项 + 你的推荐项 + “其他/不确定”兜底
  3. 得到回答后 立刻回写 
    raw.md/## 澄清记录
  4. 基于用户回答 重新评估是否仍有未澄清点（包含“新出现的约束/范围/目标/风险”），并把“当前未澄清点（<=3 条）/是否澄清完成”写进本轮回写
当用户只能回复一次：只保留第 1 个最高杠杆问题；其余未知直接进入验证清单。
澄清循环的退出/转场：
  • 若本轮回写中 本轮是否澄清完成=是：结束澄清循环，开始创建/更新 
    solution.md
  • 否则：直接进入下一轮（继续问 1 个选择题；禁止给出分岔选项）
Repeat the following loop until stopped:
  1. Select 1 highest-leverage unknown from 
    raw.md
    (the one that can most reduce solution disagreements)
  2. Ask 1 adjudicatable multiple-choice question: 2–4 options + your recommended option + "Other/Uncertain" as fallback
  3. Immediately write back to 
    raw.md/## Clarification Records
    after receiving the answer
  4. Re-evaluate whether there are still unclarified points based on the user's answer (including "newly emerged constraints/scope/goals/risks"), and write "current unclarified points (<=3 items)/whether clarification is completed" into this round's write-back
When the user can only reply once: Keep only the first highest-leverage question; add other unknowns directly to the verification list.
Exit/Transition of Clarification Loop:
  • If Is clarification completed this round? = Yes in this round's write-back: End the clarification loop and start creating/updating 
    solution.md
  • Otherwise: Proceed directly to the next round (continue to ask 1 multiple-choice question; prohibit providing branching options)

何时算“澄清完成”（必须满足）

When Is "Clarification Completed" (Must Meet All Conditions)

同时满足以下条件，才算澄清完成：
  • 当前未澄清点=无（本轮回写中明确写“无”）
  • 用户明确确认“无遗漏/可以进入方案决策”（用选择题问到这一点也算）
澄清完成后，才允许创建/更新 
solution.md
并进入 R1 的“方案决策与验证清单”。
Clarification is considered completed only when all of the following are met:
  • Current unclarified points = None (clearly write "None" in this round's write-back)
  • User explicitly confirms "no omissions/proceed to solution decision" (this can also be confirmed via a multiple-choice question)
Only after clarification is completed is creating/updating 
solution.md
allowed, and then proceed to R1's "Solution Decision and Verification List".

产物不变量（必须满足）

Product Invariants (Must Meet)

solution.md
：
  • 必须 1 个推荐方案：写清关键取舍；每个关键点能指向证据（
    raw.md
    点位）或验证条目
  • 必须 2–3 个差异明显的备选方案：各自写清“何时会选 / 不选原因”（1–2 条关键差异）
  • 必须有“决策依据（证据入口）”：明确引用 
    raw.md
    ；缺证据的一律转验证清单
  • 必须有“验证清单”且可执行：每条包含 假设/风险 → 方法 → 成功/失败信号 → Owner → 截止 → 触发动作（编号 
    V-xxx
    ）；禁止 
    TBD/待定/待指定
    等占位符，Owner/截止至少写到“角色/负责人 + 相对期限”
  • 正文 禁止出现 “待确认问题/待确认清单/To confirm” 之类列表（不确定性只能进验证清单）
  • 迭代记录必须追加：每轮追加 3–5 条“改了什么 + 为什么改”
raw.md
：
  • 每次回答后，必须在 
    ## 澄清记录
    留下可追溯记录（禁止占位符）
solution.md
:
  • Must include 1 recommended solution: Clearly state key trade-offs; each key point must point to evidence (location in 
    raw.md
    ) or a verification item
  • Must include 2–3 distinct alternative solutions: For each, clearly state "when to choose / reasons not to choose" (1–2 key differences)
  • Must have "Decision Basis (Evidence Entry)": Explicitly reference 
    raw.md
    ; any content lacking evidence must be transferred to the verification list
  • Must have an executable "Verification List": Each entry includes Assumption/Risk → Method → Success/Failure Signal → Owner → Deadline → Trigger Action (numbered V-xxx); placeholders like "TBD/to be determined/to be assigned" are prohibited, Owner/Deadline must at least specify "role/responsible person + relative time frame"
  • The main body must not contain lists such as "pending confirmation questions/pending confirmation list/To confirm" (uncertainties can only be included in the verification list)
  • Iteration records must be appended: Each round appends 3–5 entries of "what was changed + why it was changed"
raw.md
:
  • After each answer, a traceable record must be left in 
    ## Clarification Records
    (prohibit placeholders)

澄清回写格式（写入 
raw.md/## 澄清记录
）

Clarification Write-Back Format (Write to 
raw.md/## Clarification Records
)

每轮追加一条：
  • 问题：
  • 推荐选项（含理由）：
  • 用户回答：
  • 一句话结论：
  • 遗留歧义（如有，写成“假设/风险”，并给验证编号 V-xxx）：
  • 当前未澄清点（<=3 条；无则写“无”）：
  • 本轮是否澄清完成：是 / 否
回写必须发生在“拿到用户回答”之后；不要在 
raw.md
里写“待用户填写/占位符”。回写内容只包含以上字段（保持简洁可追溯），不要额外追加解释性段落/模板/空标题。
Append one entry per round:
  • Question:
  • Recommended Option (with reasoning):
  • User's Answer:
  • One-sentence Conclusion:
  • Remaining Ambiguities (if any, written as "Assumption/Risk" with verification number V-xxx):
  • Current Unclarified Points (<=3 items; write "None" if none):
  • Is Clarification Completed This Round: Yes / No
Write-back must occur after receiving the user's answer; do not write "to be filled by user/placeholder" in 
raw.md
. The write-back content only includes the above fields (keep concise and traceable), do not add additional explanatory paragraphs/templates/empty headings.

solution.md
结构

solution.md
Structure

以模板为准：
skills/spec-product-clarify/solution-template.md
（只借结构，不把未知当已知）。
Follow the template: 
skills/spec-product-clarify/solution-template.md
(borrow only the structure, do not treat unknowns as knowns).

澄清完成后的分流（可选）

Diversion After Clarification Completion (Optional)

仅在澄清完成后才允许讨论以下分流；澄清未完成时禁止提出“进 R2/快速通道”的选项。
若用户明确跳过 R2（单独 PRD），在 
solution.md
追加 Mini-PRD：
  • MVP 范围（精确到行为/规则）
  • AC（3–10 条，可测试、可验证）
  • 交互变化结论（无 / 有但简单；否则不应跳过）
  • 影响面（页面/入口/接口/权限点的可定位入口）
Discussing the following diversions is only allowed after clarification is completed; proposing options like "enter R2/fast track" is prohibited until clarification is completed.
If the user explicitly skips R2 (separate PRD), append a Mini-PRD to 
solution.md
:
  • MVP scope (precise to behavior/rules)
  • AC (3–10 items, testable, verifiable)
  • Interaction change conclusion (None / Yes but simple; otherwise, skipping is not recommended)
  • Impact scope (locatable entries for pages/entries/interfaces/permission points)

极简例子（单轮澄清 + 回写）

Minimal Example (Single Round of Clarification + Write-Back)

对用户的一次一问（选择题）：
  • 问题：导出任务采用哪种执行方式？
    • A. 同步（小数据量）
    • B. 异步 + 导出中心（大数据量）
    • C. 先同步后异步（分迭代）
    • D. 不确定 → 请给最大导出行数/期望完成时间
    • 我的推荐：B（可追溯、可恢复）
回写到 
raw.md/## 澄清记录
：
  • 问题：导出任务采用哪种执行方式？（同上）
  • 推荐选项（含理由）：B（大数据量更稳；便于追溯与失败恢复）
  • 用户回答：C
  • 一句话结论：MVP 先同步并设上限；随后迭代异步导出与导出中心
  • 遗留歧义：V-001 导出上限与性能目标未定（方法=压测；信号=耗时/失败率；Owner=DEV；截止=评审后 3 天；动作=超阈值则切换异步方案）
  • 当前未澄清点（<=3 条）：导出上限（行数）与性能目标（耗时/资源）口径
  • 本轮是否澄清完成：否
A single multiple-choice question to the user:
  • Question: Which execution method should be used for export tasks?
    • A. Synchronous (small data volume)
    • B. Asynchronous + Export Center (large data volume)
    • C. First synchronous then asynchronous (phased iteration)
    • D. Uncertain → Please provide the maximum number of rows to export/expected completion time
    • My Recommendation: B (traceable, recoverable)
Write-back to 
raw.md/## Clarification Records
:
  • Question: Which execution method should be used for export tasks? (same as above)
  • Recommended Option (with reasoning): B (more stable for large data volumes; easy to trace and recover from failures)
  • User's Answer: C
  • One-sentence Conclusion: MVP uses synchronous execution with an upper limit first; then iterate to asynchronous export and Export Center
  • Remaining Ambiguities: V-001 Export upper limit and performance target not determined (Method = pressure test; Signal = time consumption/failure rate; Owner = DEV; Deadline = 3 days after review; Action = switch to asynchronous scheme if threshold is exceeded)
  • Current Unclarified Points (<=3 items): Export upper limit (number of rows) and performance target (time consumption/resources) specifications
  • Is Clarification Completed This Round: No