Back to Details

sdd-clarify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SDD Clarify — ask well, build once

SDD Clarify — 精准提问，一次构建到位

The cheapest token is the one you don't spend re-doing work. A vague request implemented blind burns iterations (implement → wrong → re-implement → re-review). This skill front-loads the ambiguity: a short, sharp clarification pass turns a fuzzy ask into a well-scoped SDD change, so the implement/review loop runs once. Modeled on GitHub Spec-Kit's 
/speckit.clarify
and Matt Pocock's 
grill-me
skill (interview until shared understanding, resolving each branch of the decision tree, with a recommended answer per question) — adapted to be token-frugal.
返工是最不必要的成本投入。模糊的需求会导致反复迭代（开发→不符合预期→重新开发→重新评审）。本技能将歧义消除前置：通过简短、精准的澄清环节，把模糊的需求转化为范围明确的SDD变更，让开发/评审流程只需运行一次。本技能参考GitHub Spec-Kit的
/speckit.clarify
以及Matt Pocock的
grill-me
技能（通过沟通达成共识，梳理决策树的每个分支，每个问题提供推荐答案）进行适配，以降低Token消耗。

When to use

适用场景

On any feature/bug request, BEFORE proposing a spec or touching code. It is the step that feeds 
/opsx:propose
(or the workflow's spec phase) a goal that's actually pinned down.
适用于所有功能/Bug修复请求，在提出规格文档或编写代码之前使用。本环节为
/opsx:propose
（或工作流的规格阶段）提供明确的目标。

The clarify pass

澄清流程

  1. Gather context cheaply first. Read only what's needed to know what's ALREADY decided by the code/specs — existing modules, related specs, conventions. Never ask the user something the repo already answers. (Use a cheap read/locate, not a deep dive.)
  2. Scan for ambiguity across these dimensions (Spec-Kit's set) — keep only the ones that are genuinely unresolved AND change what you'd build:
    • Functional scope & boundaries (what's in / explicitly out)
    • Data model / entities / persistence
    • Integration & dependencies (which services/events/contracts it touches)
    • Edge cases & failure behavior (fail-open? errors? empty/limits?)
    • Non-functional (latency budget, security/authz, idempotency)
    • Terminology / domain (disambiguate overloaded terms — e.g. bill vs invoice)
  3. Ask the questions — decision-tree aware (grill-me), but token-frugal. Order them by the decision tree: scope decisions first, they gate the rest. Batch the INDEPENDENT questions into ONE 
    AskUserQuestion
    call (2–4 selectable options each, the RECOMMENDED option first and labeled, so answering is a click, not an essay) — that saves round-trips. When an answer opens a genuinely NEW dependent branch (a follow-up that only makes sense given that answer), do ONE more short round for it — resolve each branch, don't guess across it. Never batch two questions that depend on each other; never ask what the code already decides or what has an obvious default (state the default and move on). If the request is unambiguous, ask nothing and go straight to step 5. Cap the whole pass at ~2 rounds — grilling forever is its own waste.
  4. Fold the answers into the proposal. Every answer becomes an explicit line in the OpenSpec proposal/spec (scope, decisions, edge cases) — the spec, not chat, is the record.
  5. Route to SDD:
    • Small / single-file / bugfix → 
      /opsx:propose
      then 
      /opsx:apply
      .
    • Large / cross-cutting / chat-surface → launch the sdd-feature-flow workflow with the clarified goal (it can't ask the user mid-run, so the clarity must come from HERE).
  6. Review at PR time is not this skill's job — it's the pre-pr-greptile skill: when the change is implemented and you go to open the PR, that runs 
    greptile review
    , verifies the diff match, triages, and gates the PR. Clarify → spec → implement → greptile review → PR.
  1. 先低成本收集上下文。只读取必要信息，了解代码/规格文档中已确定的内容——现有模块、相关规格、约定。绝不要询问代码库中已有答案的问题。（使用低成本的读取/定位方式，而非深度调研。）
  2. 从以下维度排查歧义（参考Spec-Kit的维度）——只保留真正未解决且会影响开发方案的歧义点：
    • 功能范围与边界（包含/明确排除的内容）
    • 数据模型/实体/持久化方案
    • 集成与依赖（涉及哪些服务/事件/契约）
    • 边缘情况与故障处理（故障开放？错误处理？空值/限制场景？）
    • 非功能需求（延迟预算、安全/授权、幂等性）
    • 术语/领域概念（消除重载术语的歧义——例如“账单”与“发票”）
  3. 提出问题——结合决策树思维（grill-me），但兼顾Token成本。按照决策树顺序排序问题：先确定范围，因为范围决定后续所有事项。将独立问题整合到一次
    AskUserQuestion
    调用中（每个问题提供2-4个可选选项，推荐选项放在首位并标注，方便用户一键选择，无需长篇作答）——这样可以减少沟通往返次数。如果某个答案引出了全新的依赖分支（只有基于该答案才需要跟进的问题），则进行一轮简短的后续提问——梳理每个分支，不要跨分支猜测。绝不要将相互依赖的问题放在同一批次；绝不要询问代码已明确的内容或有明显默认值的问题（直接说明默认值并继续即可）。如果请求本身明确无误，则无需提问，直接进入第5步。整个澄清环节最多进行约2轮沟通——过度追问本身就是一种浪费。
  4. 将答案整合到提案中。每个答案都要成为OpenSpec提案/规格文档中的明确条目（范围、决策、边缘情况）——规格文档而非聊天记录才是正式记录。
  5. 路由至SDD流程：
    • 小型/单文件/Bug修复需求 → 先通过
      /opsx:propose
      ，再执行
      /opsx:apply
      。
    • 大型/跨模块/涉及交互界面的需求 → 以澄清后的目标启动sdd-feature-flow工作流（该工作流运行过程中无法向用户提问，因此所有清晰度必须在此环节达成）。
  6. PR阶段的评审不属于本技能的职责——这是pre-pr-greptile技能的工作：当变更开发完成准备提交PR时，运行
    greptile review
    ，验证代码差异是否符合要求，进行分类筛选，并作为PR提交的前置检查。流程为：澄清→规格编写→开发→greptile评审→提交PR。

Guardrails

约束规则

  • Don't over-ask. Over-questioning is its own waste (of the user's time AND tokens). 3–4 sharp questions max; zero if the ask is clear. Recommended-first options so the user can one-click the default.
  • Never invent facts to fill a gap — if something is unknown and load-bearing, ask; if it's unknown and minor, pick a sensible default and state it in the spec.
  • Ambiguity resolved here MUST be written into the OpenSpec artifacts, not left in chat.
  • Respect the SDD gate: production-source edits still require the active change this produces.
  • 避免过度提问。过度追问本身就是一种浪费（浪费用户时间和Token）。最多提出3-4个精准问题；如果需求明确，则无需提问。提供推荐选项优先的选择项，让用户可以一键选择默认方案。
  • 绝不编造信息填补空白——如果某个信息未知且影响开发方向，则提问；如果信息未知但影响较小，则选择合理的默认值并在规格文档中说明。
  • 在此环节解决的歧义必须写入OpenSpec文档，不能仅留在聊天记录中。
  • 遵守SDD流程：生产代码的修改仍需基于本环节生成的有效变更请求。