product-interview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Product Interview

产品访谈

Protocol

流程规范

Input

输入

Feature: a feature name/description or an existing
```
meta/specs/NNN-slug/
```
path.
- Match first: before writing, match the feature against existing folder slugs in
```
meta/specs/
```
  . Never mint a new NNN before this check.
- Exactly one match: use that folder; Step 5 updates its spec in place.
- Several plausible matches: list them via
```
AskUserQuestion
```
  ; never glob-and-pick.
- No match: resolve the next number plus a slug from the feature name as the new
```
NNN-slug
```
  .
- Stable home: resolve
```
NNN-slug
```
  here so a mid-interview
```
generate-mockups
```
  call has a destination.
- Lazy creation: whichever writes first creates the folder — mockups at Step 2 or spec.md at Step 5.

功能：功能名称/描述，或现有
```
meta/specs/NNN-slug/
```
路径。
- 优先匹配：在撰写前，先将该功能与
```
meta/specs/
```
  中的现有文件夹slug进行匹配。在完成此检查前，绝不要生成新的NNN编号。
- 唯一匹配：使用该文件夹；步骤5将在原地更新其规格文档。
- 多个疑似匹配：通过
```
AskUserQuestion
```
  列出所有匹配项；绝不要通过通配符选择。
- 无匹配：根据功能名称解析下一个编号和slug，生成新的
```
NNN-slug
```
  。
- 固定存储位置：在此处解析
```
NNN-slug
```
  ，以便访谈中途调用
```
generate-mockups
```
  时有明确的目标路径。
- 延迟创建：由先写入的内容创建文件夹——步骤2的mockups或步骤5的spec.md。

Resumability — check before Step 0

可恢复性——步骤0前检查

On re-entry to an existing feature, read what exists on disk first; the spec encodes where a prior session stopped — resume there rather than re-interviewing settled ground:

No folder / no
spec.md
(per the Input check) → nothing written; run Steps 0–1, start fresh.
spec.md
exists but core sections are missing or placeholder → an interrupted prior session; re-read what's there and rejoin the interview (Step 2) at the gaps — resume from the file, don't reconstruct from memory.
Spec complete but the Gate anchor greps hit (
```
Status: open
```
decisions / clarification markers) → a parked investigation, not damage; resume Step 2 at the open branches or markers only.
### Files touched
present and plan.md's
Base SHA:
is set → keep the outline frozen; handle the change in the active
```
execute-plan
```
session.
### Files touched
present and plan.md is absent or its
Base SHA:
is unset →
```
tech-design
```
already designed on this WHAT; confirm the reopen, revise any affected locked decision per the template's Revising rule, and apply Step 5's header flip.

Step 0 still runs on every re-entry — the lens loads per session.

重新进入现有功能时，先读取磁盘上已有的内容；规格文档会记录上一次会话的中断位置——从该位置继续，而非重新访谈已确定的内容：

无文件夹/无
spec.md
（根据输入检查结果）→ 无任何内容已写入；执行步骤0–1，从头开始。
spec.md
存在但核心章节缺失或为占位符→ 上一次会话中断；读取已有内容，在缺失部分重新加入访谈（步骤2）——从文件恢复，而非从记忆重构。
规格文档完整但检测到Gate锚点（
```
Status: open
```
决策/澄清标记）→ 暂停的调研，并非损坏；仅在未完成的分支或标记处恢复步骤2。
存在
### Files touched
且plan.md的
Base SHA:
已设置→ 保持大纲冻结；在活跃的
```
execute-plan
```
会话中处理变更。
存在
### Files touched
但plan.md缺失或其
Base SHA:
未设置→
```
tech-design
```
已基于此WHAT完成设计；确认重新开启，根据模板的修订规则修改任何受影响的锁定决策，并执行步骤5的标题切换。

每次重新进入时仍会执行步骤0——会话会加载对应的视角。

Step 0 — Load the job lens

步骤0——加载任务视角

Invoke the

jtbd

skill via the Skill tool. Use its lens — the job-story format and job-fit judgment — to frame every product/scope question; skip its Steps and Job-frame output.

通过Skill工具调用

jtbd

技能。使用其视角——工作故事格式和工作适配判断——来构建所有产品/范围问题；跳过其步骤和工作框架输出。

Step 1 — Read context first

步骤1——先读取上下文

Before asking anything, silently explore:

Root
```
CLAUDE.md
```
and any product or design documents it says to read for this task
Existing UX in the affected area (screens, flows, components)
Related features and any prior spec this feature builds on
Use shipped specs as decision history; verify current behavior in code
A light possibility scan: what the target surface/platform allows at all, and what data the codebase already carries — possibility only, never how-to-build, never current code as a ceiling (see the Codebase is context rule)

Don't ask what current code or the active spec already answers. Treat project conventions as constraints to follow, not decisions to re-litigate.

在提问前，先静默调研：

根目录下的
```
CLAUDE.md
```
以及其中提到的与本次任务相关的所有产品或设计文档
受影响区域的现有UX（界面、流程、组件）
相关功能以及本功能所基于的任何先前规格文档
将已发布的规格文档作为决策历史；在代码中验证当前行为
初步可能性扫描：目标界面/平台完全支持的功能，以及代码库已承载的数据——仅关注可能性，绝不涉及构建方式，绝不将当前代码视为上限（参见代码库是上下文规则）

不要询问当前代码或现有规格文档已回答的问题。将项目约定视为需遵循的约束，而非需重新讨论的决策。

Step 2 — Interview: product, then UX

步骤2——访谈：先产品，后UX

Resolve the product layer before the UX layer as the default, but treat them as one decision tree: when a UX branch blocks or would overturn a product choice, resolve that branch first (the dependency rule below governs). A UX answer that overturns an already-locked product choice follows the reversal rule below. Surface what the user is assuming, not just what they request. When the Step-1 read surfaces a load-bearing question the user didn't ask — an existing feature this overlaps, a UX pattern to reuse or deliberately diverge from — raise it, saying it came from the codebase; route technical finds to Open Questions tagged

(for tech-design)

. Draft the job-story as the product layer resolves — it anchors UX option scoring and the spec's Background. A slot you can't fill is a question to ask, not a blank to guess.

Manage the decision space as follows:

Start the tree: once you can name two or more branches, show a compact nested list and ask, "Here's what I think we need to figure out — does this match?"

Format each node:

- [branch] — [resolved: choice] | [open] | [deferred: why] | [blocked by branch]

, followed by

[hard|ask|ours]

when applicable.

Order: list blocking branches first and resolve one branch at a time.
Maintain: update the tree inline as branches split, collapse, or resolve.
Finish: continue until every branch is resolved or explicitly deferred.
Flat interview: for one or two flat questions, skip the tree and ask directly.
Unknown branches: ask open-ended questions until you can name the branches; aim to show the tree within 2–3 rounds.
Long interview: summarize current clarity and offer to continue or proceed.

Run each branch explore → stretch → verify (in order) — name the ideal before checking what's real, so a constraint never caps a choice the user hasn't reached for yet.

Explore / stretch: for a non-trivial or ambiguous UX branch, name and score 2+ options by job-fit before locking; an obvious single-UX branch skips this. Escalate to parallel subagents (and any available design skills) only for high-stakes or high-ambiguity UX.
Sketch, then gate visual review: for every feature that changes a user-facing screen, component, interaction, or visual state, sketch each UI branch or option in ASCII, then ask once via
```
AskUserQuestion
```
before Step 2 ends: "How should we validate this UI before locking the UX?" The user chooses; recommend one option and state why:
- Keep ASCII — use the sketches without a rendered artifact. Recommend this when one obvious direction follows an established pattern and the sketches make its behavior clear.
- Preview rendered mockups — render the one preferred direction across the relevant screens or states. Recommend this when the direction is settled but a new or complex UI is easier to judge visually.
- Compare rendered directions — render 2+ viable directions for one unresolved visual choice side by side, then ask the user to pick. Recommend this when the directions have meaningful layout, hierarchy, or interaction tradeoffs.
- Run mockups: on Preview or Compare, invoke the
  generate-mockups
  skill via the Skill tool with the matching PREVIEW or COMPARE intent, the resolved
```
meta/specs/NNN-slug/mockups/
```
  path, and the design context you know. It derives High or Approximate fidelity after grounding; don't promise High fidelity in the question.
- Record the result: at Step 5, record
```
ASCII (user-approved)
```
  , or the reviewed mockup link plus the approved preview or comparison result, in the UX section.
- Skip: omit this checkpoint only when the feature changes no user-facing UI.
Verify (just-in-time):
- Trigger: when an unchecked claim could invalidate the agreed scope if false, dispatch a subagent to verify it against the source of truth (code, docs, or SDK). A claim that would only redirect the branch does not qualify.
- Scope: verify only whether the product surface can support the agreed behavior.
- Route: put implementation and capacity questions in Open Questions tagged
```
(for tech-design)
```
  .
Hit a wall? Tag it.
```
[hard]
```
= outside our control (external SDK / platform) → law; stamp its assumption (e.g. "given the SDK has no programmatic redirect") so it reopens if the dependency changes.
```
[ask]
```
= cross-team, movable by request.
```
[ours]
```
= our code, we change freely.
```
[hard]
```
is a real constraint;
```
[ask]
```
/
```
[ours]
```
are guidance — if either forces a worse UX, challenge it (or flag the ask) first, then record the user's final call and move on.
Don't lock a UI pattern whose surface feasibility is unverified — verify possibility first, or lock it "pending feasibility."

Completeness lens (verify nothing is missing — these are a lens, not a required structure):

Product / scope — the job to be done, in the jtbd job-story format (loaded at Step 0); who it's for; what's in, what's out; success criteria.
UX and behavior — happy path, error states, empty states, user flows, the surfaces/screens touched.
Acceptance criteria — observable, testable conditions for "done."
Constraints — compatibility, platform limits, dependencies, boundaries.
Clarity — resolve remaining ambiguity or contradictions.

When a load-bearing assumption surfaces, test it once ("Does this constraint actually exist?" / "What's the simplest version still worth shipping?"). Challenge the framing, not the person. If a stated requirement seems materially wrong (product value, UX harm), say so with reasoning; record the user's final call, not yours.

If a later answer or feasibility finding overturns a choice the user already locked this session, re-confirm via

AskUserQuestion

and record the overturned choice in the surviving decision's Rejected field, citing what killed it — the why must reach the record.

Record each resolved choice as a D-NNN-XX
decision block (see the Spec.md template — it defines the id format) with Status, Chosen, Rejected, Rationale. Classify anything unresolved by exactly one rule:

A framed-but-unresolved decision → a
```
D-NNN-XX
```
block with
```
Status: open
```
.
A blocking unknown inside any section → an inline
```
[NEEDS CLARIFICATION: ...]
```
marker.
Non-blocking notes → Open Questions (these do NOT block the gate).

Deferring a decision is itself a decision: propose it, the user confirms, and it lands as a locked

D-NNN-XX

whose Chosen is the deferral (alternatives marked deferred in Rejected) — a confirmed deferral never blocks the gate.

The lock gate greps exactly two forms — see Gate anchors below. Anything blocking must carry one of them, or it will not block.

默认先确定产品层面，再确定UX层面，但将二者视为一个决策树：当UX分支会阻碍或推翻产品选择时，优先解决该分支（遵循下方的依赖规则）。若UX答案推翻已锁定的产品选择，遵循下方的反转规则。明确用户的假设，而非仅关注其请求。当步骤1的调研发现用户未提及的关键问题——如存在重叠的现有功能、需复用或刻意偏离的UX模式——需提出该问题，并说明其来自代码库；将技术发现归类为标记

(for tech-design)

的未解决问题。随着产品层面的确定，撰写工作故事——它是UX选项评分和规格文档背景部分的锚点。无法填充的内容需作为问题提出，而非留空猜测。

按以下方式管理决策空间：

启动决策树：一旦能列出两个或更多分支，展示紧凑的嵌套列表并询问：“这是我认为我们需要明确的内容——是否符合预期？”

每个节点的格式：

- [分支] — [已确定: 选择] | [未确定] | [延迟: 原因] | [被分支阻碍]

，必要时附加

[hard|ask|ours]

。

顺序：先列出阻碍性分支，一次解决一个分支。
维护：随着分支拆分、合并或确定，实时更新决策树。
完成：持续进行，直到所有分支都已确定或明确延迟。
扁平化访谈：仅需一两个简单问题时，跳过决策树直接提问。
未知分支：提出开放式问题，直到能明确分支；目标是在2–3轮内展示决策树。
长时访谈：总结当前已明确的内容，询问用户是否继续或推进。

每个分支按探索→拓展→验证的顺序执行——先明确理想状态，再检查实际情况，确保约束不会限制用户尚未触及的选择。

探索/拓展：对于非 trivial 或模糊的UX分支，在锁定前按工作适配度命名并评分2个及以上选项；若UX分支明显唯一，则跳过此步骤。仅针对高风险或高模糊性的UX，才升级至并行子代理（及任何可用的设计技能）。
先草图，再进行视觉评审：对于所有会改变用户界面、组件、交互或视觉状态的功能，用ASCII绘制每个UI分支或选项，然后在步骤2结束前通过
```
AskUserQuestion
```
询问一次：“在锁定UX前，我们应如何验证该UI？”由用户选择；推荐一个选项并说明理由：
- 保留ASCII草图——直接使用草图，无需渲染产物。当存在明确的既定模式且草图能清晰展示行为时，推荐此选项。
- 预览渲染原型——在相关界面或状态下渲染首选方案。当方向已确定，但新的或复杂的UI更易通过视觉判断时，推荐此选项。
- 对比渲染方案——将2个及以上可行方案并排渲染，然后让用户选择。当方案在布局、层级或交互上存在显著权衡时，推荐此选项。
- 生成原型：若选择预览或对比，通过Skill工具调用
  generate-mockups
  技能，传入匹配的PREVIEW或COMPARE意图、已确定的
```
meta/specs/NNN-slug/mockups/
```
  路径，以及已知的设计上下文。它会基于实际情况生成高保真或近似保真的原型；不要在问题中承诺高保真。
- 记录结果：在步骤5中，在UX部分记录
```
ASCII (user-approved)
```
  ，或已评审的原型链接以及已通过的预览/对比结果。
- 跳过：仅当功能不改变任何用户界面时，省略此检查点。
验证（即时）：
- 触发条件：若未验证的声明可能使已达成的范围无效，则派遣子代理对照真实来源（代码、文档或SDK）进行验证。仅会重定向分支的声明不符合此条件。
- 范围：仅验证产品界面是否支持已达成的行为。
- 归类：将实现和容量问题放入标记
```
(for tech-design)
```
  的未解决问题中。
遇到阻碍？标记它。
```
[hard]
```
= 超出我们控制（外部SDK/平台）→ 既定规则；标记其假设（例如“假设SDK无程序化重定向”），以便当依赖项变更时重新开启。
```
[ask]
```
= 跨团队，可通过请求调整。
```
[ours]
```
= 我们的代码，可自由修改。
```
[hard]
```
是真实约束；
```
[ask]
```
/
```
[ours]
```
是指导——若二者导致更差的UX，先提出质疑（或标记需请求），再记录用户的最终决定并继续。
不要锁定未验证可行性的UI模式——先验证可行性，或标记为“待可行性验证”后锁定。

完整性视角（验证无遗漏——这是视角，而非必填结构）：

产品/范围——需完成的工作，采用步骤0加载的jtbd工作故事格式；目标用户；包含/排除内容；成功标准。
UX与行为——正常流程、错误状态、空状态、用户流程、涉及的界面/屏幕。
验收标准——可观察、可测试的“完成”条件。
约束——兼容性、平台限制、依赖项、边界。
清晰度——解决剩余的模糊性或矛盾。

当发现关键假设时，测试一次（“该约束是否真的存在？”/“仍值得发布的最简版本是什么？”）。质疑框架，而非个人。若既定要求存在重大错误（产品价值、UX损害），需说明理由；记录用户的最终决定，而非你的判断。

若后续答案或可行性发现推翻了用户本次会话已锁定的选择，需通过

AskUserQuestion

重新确认，并在保留的决策的“Rejected”字段中记录被推翻的选择，说明原因——必须记录缘由。

将每个已确定的选择记录为**

D-NNN-XX

决策块**（参见Spec.md模板——它定义了ID格式），包含Status、Chosen、Rejected、Rationale。按以下规则对未解决的内容进行分类：

已明确但未解决的决策→ 标记
```
Status: open
```
的
```
D-NNN-XX
```
块。
任何章节中的阻碍性未知内容→ 内联标记
```
[NEEDS CLARIFICATION: ...]
```
。
非阻碍性笔记→ 未解决问题（这些不会阻碍Gate）。

延迟决策本身也是一项决策：提出建议，用户确认后，将其记录为锁定的

D-NNN-XX

块，其中Chosen为延迟决定（Rejected中标记deferred的替代方案）——已确认的延迟绝不会阻碍Gate。

锁定Gate仅检测两种形式——参见下方的Gate锚点。任何阻碍性内容必须携带其中一种标记，否则不会被视为阻碍。

Step 3 — Pre-confirm verification gate

步骤3——预确认验证Gate

Once Step 2's branches are resolved or deferred, and before the Step-4 summary, run this required gate over the resolved UX elements that are load-bearing (an AC, another decision, or user-facing behavior rests on them) — two passes, two grains. The gate always runs; on a trivial feature it may be near-empty (nothing load-bearing beyond the Existing-patterns check) — record that and move on.

Pass 1 — per element. For each load-bearing element:

States — error / empty / edge: what happens when data is missing, the call fails, or a value hits a boundary?
Expectation-Fidelity — does what the element implies (its label, control, default, or placement) match what actually happens? Flag every mismatch.
Surface-Obligations — any obligation the surface itself imposes (e.g. accessibility/compliance on a regulated surface), where it demands it.

Pass 2 — the assembled whole. Do the cleared elements coexist and work together on the real surface(s)? Check combination-possibility + cross-element interference, and re-verify the load-bearing facts the interview leaned on. Surface/platform possibility is validated here — launch subagents in parallel, one per applicable area below (Existing-patterns always runs), each carrying the flows it must validate:

Area	When relevant	Verify
UI components	Feature uses specific components/libraries	Component exists, supports the interaction, composition constraints
External data/APIs	UX depends on external data	Data is available, fields exist
Platform constraints	Feature rides a platform (Shopify, extension, etc.)	The UX is permitted by the platform
Existing patterns	Always	The affected area's existing UX patterns and conventions

Scope: possibility, not capacity. Constraint depth — rate limits, quotas, throughput, batch caps — is

tech-design

's constraint recon (its Step 2B); don't duplicate it here.

Handle verification results in order:

Receive: each subagent returns
```
exists
```
(yes/no), capabilities, gotchas, and blocks: <the decision or flow it invalidates> | none
.
```
none
```
is valid.
Record: put each load-bearing possibility verdict in the relevant
```
D-NNN-XX
```
Rationale or the Constraints section, not only in conversation.
Resolve: feed every Pass-1 miss or Pass-2
```
blocks
```
hit back into the tree. Re-explore it with the user; never narrow the UX silently.
After one follow-up round: proceed with each resolved finding. Classify each remaining finding by Step 2's rule as an open decision, clarification marker, or Open Question, then move on.

步骤2的分支已确定或延迟后，在步骤4总结前，对关键的已确定UX元素（验收标准、其他决策或用户行为依赖于这些元素）运行此必填Gate——两轮检查，两个粒度。Gate始终运行；对于trivial功能，可能几乎为空（除了现有模式检查外无关键元素）——记录此情况并继续。

第一轮——逐个元素检查。针对每个关键元素：

状态——错误/空/边缘情况：当数据缺失、调用失败或值达到边界时会发生什么？
预期与保真度——元素所暗示的内容（标签、控件、默认值或位置）是否与实际行为匹配？标记所有不匹配项。
界面义务——界面本身施加的任何义务（例如受监管界面的可访问性/合规性），以及要求的场景。

第二轮——整体检查。已通过检查的元素在真实界面上能否共存并协同工作？检查组合可能性+跨元素干扰，并重新验证访谈所依赖的关键事实。在此验证界面/平台可能性——并行派遣子代理，每个代理负责以下适用领域（始终运行现有模式检查），并携带需验证的流程：

领域	适用场景	验证内容
UI components	功能使用特定组件/库	组件存在、支持交互、组合约束
External data/APIs	UX依赖外部数据	数据可用、字段存在
Platform constraints	功能基于特定平台（Shopify、扩展等）	UX符合平台规则
Existing patterns	始终适用	受影响区域的现有UX模式和约定

范围：仅关注可能性，不关注容量。约束深度——速率限制、配额、吞吐量、批量上限——属于

tech-design

的约束调研（其步骤2B）；不要重复此工作。

按以下顺序处理验证结果：

接收结果：每个子代理返回
```
exists
```
（是/否）、功能、注意事项，以及**
```
blocks: <它使无效的决策或流程> | none
```
**。
```
none
```
为有效结果。
记录结果：将每个关键可能性结论放入相关的
```
D-NNN-XX
```
的Rationale或Constraints部分，而非仅在对话中记录。
解决问题：将第一轮的所有遗漏或第二轮的
```
blocks
```
结果反馈回决策树。与用户重新探索；绝不要私下缩小UX范围。
一轮跟进后：根据每个已解决的发现继续。按步骤2的规则将每个剩余发现分类为未解决决策、澄清标记或未解决问题，然后继续。

Step 4 — Pre-write summary

步骤4——预撰写总结

Before writing, summarize the contract in chat in this exact shape — enough to spot a wrong turn without reproducing every AC:

**Contract summary (pre-write):**
- Scope: [one line]
- Decisions: D-NNN-XX [title] → [Chosen]        (one line per decision)
- Visual review: [not applicable — no UI change | ASCII (user-approved) | mockups: path — review outcome]
- Constraints: [one line each]
- ACs: [n] ([x] code-gated, [y] human-gated)
- Step-3 gate: [clean | each finding and how it resolved]

**Assumptions I'm carrying (never discussed):**
- [assumption] — [what rests on it]

(Write

None — everything load-bearing was discussed

when the assumptions list is empty.) Then use

AskUserQuestion

to collect the choice: "Write the draft" / "Adjust first" / "Find gaps first". Recommended: write the draft. The full verbatim contract — the numbered AC list with gating tags and every

D-NNN-XX

block — belongs in the file, not chat: Step 5 writes it as

Status: Draft

for the user to review. Reviewers verify diffs against that AC text, so it must be exact in the file.

On Find gaps first — opt-in, at most once, for a complex feature or when you lack the domain depth to spot missing cases — invoke the

find-gaps

skill over the assembled contract. Absence-hunting only: its lens is what the contract never mentions — missing scope, AC-coverage holes; never re-check verdicts the Step-3 gate settled (checkers verify what's written; find-gaps hunts what's not). Product/UX gaps only — not a technical-gap hunt (

tech-design

's job); fence every lens to the WHAT layer and send technical gaps to Open Questions tagged

(for tech-design)

. Applied gaps re-enter Step 2; a new flow on an external surface re-runs the Step-3 gate on the delta. Then re-summarize and re-ask without the Find-gaps option — it runs at most once.

撰写前，以以下固定格式在聊天中总结协议——无需重现每个验收标准，只需足以发现错误方向：

**协议总结（预撰写）：**
- 范围：[一行描述]
- 决策：D-NNN-XX [标题] → [选择]        （每个决策一行）
- 视觉评审：[不适用——无UI变更 | ASCII (user-approved) | 原型: 路径 — 评审结果]
- 约束：[每行一个]
- 验收标准：[n]（[x] 代码校验，[y] 人工校验）
- 步骤3 Gate：[无问题 | 每个发现及解决方式]

**我当前的假设（未讨论）：**
- [假设] — [依赖此假设的内容]

（若假设列表为空，填写

None — 所有关键内容均已讨论

。）然后通过

AskUserQuestion

让用户选择：“撰写草稿”/“先调整”/“先查找缺口”。推荐选择：撰写草稿。完整的协议——带标记的编号验收标准列表和每个

D-NNN-XX

块——应写入文件，而非聊天中；步骤5会将其写入为

Status: Draft

供用户评审。评审人员会对照验收标准文本检查差异，因此文件中的内容必须准确。

若选择先查找缺口——仅针对复杂功能或你缺乏领域深度无法发现遗漏场景时可选，最多执行一次——对已整理的协议调用

find-gaps

技能。仅查找缺失内容：其视角是协议从未提及的内容——缺失的范围、验收标准覆盖漏洞；绝不重新检查步骤3 Gate已确定的结论（检查器验证已写入的内容；find-gaps查找未写入的内容）。仅关注产品/UX缺口——不涉及技术缺口（

tech-design

的工作）；将所有视角限定在WHAT层面，将技术缺口放入标记

(for tech-design)

的未解决问题中。发现的缺口重新进入步骤2；若外部界面有新流程，需对增量重新运行步骤3 Gate。然后重新总结并再次询问，不再提供“查找缺口”选项——此操作最多执行一次。

Step 5 — Write / update the spec

步骤5——撰写/更新规格文档

Write the spec in this order:

Path: use
```
meta/specs/NNN-<topic-slug>/spec.md
```
with the
```
NNN-slug
```
resolved at Input. Create the folder unless a Step-2 mockup already created it.
Existing spec: if Input resolved an existing spec, update it in place. Append or modify sections and revise decisions per the template's Revising rule.
Counters: continue both counters. The next
```
D-NNN-XX
```
uses the highest existing
```
XX
```
across product and technical decisions plus 1; new ACs continue their counter likewise.
Reopen: before plan.md's
```
Base SHA:
```
is set, a decision or AC edit on a spec with
```
### Files touched
```
resets the header to
```
Status: Draft
```
. The existing outline was verified against the old WHAT, and the Draft header routes
```
tech-design
```
through a scoped redesign.
Handoff: tell the user the path and ask them to review the file. The spec remains
```
Status: Draft
```
and uncommitted; Step 6 owns revisions and commit.

This skill writes the WHAT sections;

tech-design

later appends technical Decisions + the Structure Outline (and appends to Constraints / Accepted risks what its recon proves);

execute-plan

appends the Completion record at ship. For the full file shape, see the Spec.md template at the end of this file.

按以下顺序撰写规格文档：

路径：使用
```
meta/specs/NNN-<topic-slug>/spec.md
```
，其中
```
NNN-slug
```
在输入阶段已确定。除非步骤2的原型已创建文件夹，否则创建该文件夹。
现有规格文档：若输入阶段确定了现有规格文档，原地更新。根据模板的修订规则添加或修改章节，修订决策。
计数器：延续两个计数器。下一个
```
D-NNN-XX
```
使用产品和技术决策中最高的现有
```
XX
```
编号加1；新的验收标准同样延续其计数器。
重新开启：在plan.md的
```
Base SHA:
```
设置前，对包含
```
### Files touched
```
的规格文档进行决策或验收标准编辑时，需将标题重置为
```
Status: Draft
```
。现有大纲已针对旧的WHAT进行验证，Draft标题会引导
```
tech-design
```
进行范围化重新设计。
交接：告知用户文件路径并请求评审。规格文档保持
```
Status: Draft
```
且未提交；步骤6负责修订和提交。

本技能负责撰写WHAT部分；

tech-design

稍后会添加技术决策+结构大纲（并在Constraints/Accepted risks中添加其调研确认的关键数据）；

execute-plan

会在发布时添加完成记录。完整的文件格式，请参见本文末尾的Spec.md模板。

Step 6 — Review, commit, route

步骤6——评审、提交、路由

Stop here once every product/UX branch is resolved or deferred and the spec is written. Step 5 sent the user to read the file — this step turns that review into approval, then handles commit and routing as two tightly-coupled

AskUserQuestion

rounds.

Q1 — Draft look right? If so, commit?

Ask: offer "Commit now" (recommended) / "Skip commit for now" / "Adjust the draft first".
Approve: either Commit or Skip approves the draft; proceed to Q2.
Adjust: edit the Draft in place and re-ask Q1. If the edit overturns a locked decision or changes an AC on a spec with a populated outline, apply Step 5's header-flip rule.
Commit: stage only spec.md; the commit is the durable trace of approval:

git add meta/specs/NNN-slug/spec.md && git commit -m "spec(NNN-slug): discovery — product/UX decisions + ACs"

Folder guard: use the slug resolved at Input. If
```
git status --porcelain meta/specs/NNN-slug/
```
shows another changed file, leave it unstaged and tell the user.
Skip commit: leave spec.md uncommitted and say so.
```
tech-design
```
Step 6 will stage it; re-offer the commit at every session boundary before then.

Q2 — Where next?

tech-design
— default: the WHAT is locked and the feature needs implementation decisions before sequencing.
grill-me
— if
```
Status: open
```
decisions or clarification markers remain, or a load-bearing assumption wasn't pressure-tested.
write-plan
directly — only for a trivial change with one obvious implementation.

The WHAT must be locked (both Gate anchor greps clean) before

tech-design

will proceed.

当所有产品/UX分支已确定或延迟，且规格文档已撰写完成时，停止此处。步骤5已引导用户查看文件——此步骤将评审转化为批准，然后通过两轮紧密关联的

AskUserQuestion

处理提交和路由。

问题1——草稿是否正确？若正确，是否提交？

提问：提供“立即提交”（推荐）/“暂时跳过提交”/“先调整草稿”选项。
批准：选择提交或跳过均表示批准草稿；进入问题2。
调整：原地编辑草稿并重新询问问题1。若编辑推翻了锁定的决策或修改了包含已填充大纲的规格文档的验收标准，需执行步骤5的标题切换规则。
提交：仅暂存spec.md；提交是批准的持久记录：

git add meta/specs/NNN-slug/spec.md && git commit -m "spec(NNN-slug): discovery — product/UX decisions + ACs"

文件夹防护：使用输入阶段确定的slug。若
```
git status --porcelain meta/specs/NNN-slug/
```
显示其他已更改文件，请勿暂存并告知用户。
跳过提交：保留spec.md未提交并告知用户。
```
tech-design
```
步骤6会暂存它；在此之前的每个会话边界都会重新提供提交选项。

问题2——下一步？

tech-design
——默认选项：WHAT已锁定，功能需要先确定实现决策再排序。
grill-me
——若存在
```
Status: open
```
决策或澄清标记，或关键假设未经过压力测试。
直接
write-plan
——仅适用于变更微不足道且实现方案明显唯一的情况。

在

tech-design

继续前，WHAT必须已锁定（两个Gate锚点检测均无问题）。

Rules

规则

One question per round. Tightly coupled follow-ups are fine; shotgunning unrelated questions is not. Presenting/updating the tree counts as part of the round.
Always use
AskUserQuestion
for questions with distinct choices — with your recommendation and why. Plain text only for genuinely open-ended questions.
Product + UX only. Technical approach, data shapes, and file layout are
```
tech-design
```
's job — route them to Open Questions tagged
```
(for tech-design)
```
and move on — tech-design reads them at its discovery step.
Codebase is context, not constraint. Existing code shows what IS, not what MUST BE; the user may intentionally diverge. A wall is law only when it's outside our control (external SDK / platform) — tag
```
[hard]
```
, stamp its assumption; anything we or a teammate can change (
```
[ours]
```
our code,
```
[ask]
```
cross-team) is guidance — challenge it before it narrows the vision.
Proportional effort — load-bearing only. Spend a subagent, verification, or UX-exploration round only where a decision rests on the answer; skip passing mentions and obvious single-UX branches. Match effort to stakes.
Anchor questions in what you read. When a source raises a question, name its actual file or symbol and the claim that needs confirmation.
Play back concrete scenarios, not abstract questions. Confirm behavior by walking one specific case in the shape
```
[trigger]: [what happens] — right?
```
("Save fails offline: the draft stays and a retry shows — right?") — a wrong detail draws the correction an abstract question won't.
Keep project conventions out of the spec. Loaded project instructions own them; record a
```
D-NNN-XX
```
only for a feature-specific choice that is costly to reverse.
The spec is the feature's build contract + record — it settles at ship; post-ship product/UX evolution belongs to future specs and durable docs, not retroactive edits here.
Only spec.md and plan.md mint ids. spec.md mints
```
D-NNN-XX
```
/
```
AC-NNN-XX
```
; plan.md mints
```
F-NNN-XX
```
(execute-plan's job; format in write-plan's Plan anchors). All other artifacts — interview notes, triage/backlog files, research — cite existing ids and never mint their own.

每轮一个问题。紧密关联的跟进问题是允许的；同时提出无关问题则不允许。展示/更新决策树视为本轮的一部分。
对于有明确选项的问题，始终使用
AskUserQuestion
——提供你的推荐及理由。真正的开放式问题可使用纯文本提问。
仅处理产品+UX。技术方案、数据结构和文件布局属于
```
tech-design
```
的工作——将其归类为标记
```
(for tech-design)
```
的未解决问题并继续——tech-design会在其调研步骤中读取这些问题。
代码库是上下文，而非约束。现有代码展示的是当前状态，而非必须状态；用户可能有意偏离。只有当阻碍超出我们控制（外部SDK/平台）时，才视为既定规则——标记
```
[hard]
```
，标记其假设；任何我们或团队成员可修改的内容（
```
[ours]
```
我们的代码，
```
[ask]
```
跨团队）均为指导——在它限制愿景前提出质疑。
按比例投入精力——仅针对关键内容。仅在决策依赖答案时，才投入子代理、验证或UX探索；跳过无关提及和明显唯一的UX分支。根据风险匹配精力投入。
基于已读取的内容提出问题。当某个来源引发问题时，明确指出具体文件或符号以及需要确认的声明。
回放具体场景，而非抽象问题。通过具体案例确认行为，格式为
```
[触发条件]: [发生的情况] — 对吗？
```
（“离线时保存失败：草稿保留并显示重试选项——对吗？”）——抽象问题无法发现的细节错误，具体案例可引出修正。
不要在规格文档中记录项目约定。项目的加载指令负责管理这些约定；仅记录功能特定的、反转成本高的选择为
```
D-NNN-XX
```
块。
规格文档是功能的构建协议+记录——发布时确定；发布后的产品/UX演进属于未来的规格文档和持久文档，而非在此处进行追溯编辑。
仅spec.md和plan.md生成ID。spec.md生成
```
D-NNN-XX
```
/
```
AC-NNN-XX
```
；plan.md生成
```
F-NNN-XX
```
（execute-plan的工作；格式在write-plan的Plan锚点中定义）。所有其他工件——访谈笔记、分类/待办文件、调研——均引用现有ID，绝不生成自己的ID。

Spec.md template

Spec.md模板

Other skills inline only their own sections and point here:

markdown

undefined

其他技能仅内联自己的部分并指向此处：

markdown

undefined

SPEC-NNN: [Feature name]

SPEC-NNN: [功能名称]

Status: Draft
Created: [YYYY-MM-DD]
Source: [origin — roadmap item, request, prior spec it builds on]

Status: Draft
Created: [YYYY-MM-DD]
Source: [来源——路线图项、请求、所基于的先前规格文档]

Background

[Who needs this and why. The one-line job, in the jtbd job-story format (loaded at Step 0). The layer/scope boundary in a sentence. One short paragraph.]

[谁需要此功能及原因。一行描述工作，采用步骤0加载的jtbd工作故事格式。一句话说明层级/范围边界。简短段落。]

Requirements

[The WHAT, as observable rules — the densest, most load-bearing content. Enumerate edge cases per rule. No IDs: nothing downstream cites requirements — ACs are the citable contract.]

[the rule] — edge cases: [list]
[the rule] — edge cases: [list]

[WHAT，即可观察规则——最核心、最关键的内容。为每个规则列举边缘情况。无ID：下游不会引用需求——验收标准是可引用的协议。]

[规则] — 边缘情况：[列表]
[规则] — 边缘情况：[列表]

UX

[Flows and states: happy path, error, empty. Surfaces/screens touched. Low fidelity is fine — ASCII mocks or bullet flows. Record the visual/structural options explored, not just the chosen one — keep each rejected layout/flow (mock or one line) with why it lost. When

generate-mockups

produced a page, link it (

mockups/…

) with any notes and stamp it directional, not final; the design system /

meta/DESIGN.md

wins if they disagree. Backend-only features: the externally observable contract — which fields/behavior a consumer sees; field types, nullability, and shapes belong to tech-design's outline, which takes precedence.]

[流程和状态：正常流程、错误、空状态。涉及的界面/屏幕。低保真即可——ASCII原型或项目符号流程。记录探索过的视觉/结构选项，而非仅记录选择的选项——保留每个被拒绝的布局/流程（原型或一行描述）及原因。当

generate-mockups

生成页面时，链接它（

mockups/…

）并附加说明，标记为方向性，非最终；若与设计系统/

meta/DESIGN.md

冲突，以设计系统为准。仅后端功能：外部可观察的协议——消费者可见的字段/行为；字段类型、可空性和结构属于tech-design的大纲，优先级更高。]

Out of scope

[Only Out-of-scope — don't restate In-scope (that duplicates Requirements). Annotate coupling.]

[excluded item] — [coupling note]

[仅记录排除范围——不要重复记录包含范围（会与需求重复）。标注耦合关系。]

[排除项] — [耦合说明]

Acceptance Criteria

[Observable, testable "done" conditions — the contract an independent reviewer checks the diff against; the implementer never self-certifies. Numbering & rigor: ids are

AC-NNN-XX

—

NNN

= this spec's folder number,

XX

= a zero-padded two-digit counter starting 01; plan tasks and tests cite the ids; scale rigor to scope. Gating tag (MANDATORY): every AC carries exactly one — code-gated (machine-checkable against the diff) or human-gated with the concrete how (routed to Post-ship verification at ship). Tags are provisional at discovery; tech-design confirms or flips each once the approach is chosen — a tag-only edit, exempt from the supersession protocol. Revising: ACs are the live contract — revise in place. While plan.md is absent or its Base SHA unset: a plain edit to final shape, no marker (if plan.md exists, the Revising rule's stale-plan route applies). Once Base SHA is set: add a trailing (revised per D-NNN-XX) marker — its presence always means changed mid-build; the why lives in the superseding decision. One physical line per AC: ID, behavior, gating tag, and any (revised per D-NNN-XX) marker all on that line; the gates select by line.]

AC-NNN-01: [observable behavior] — [code-gated]
AC-NNN-02: [observable behavior] — [human-gated: how to verify, concretely]

[可观察、可测试的“完成”条件——独立评审人员对照差异检查的协议；实现者不得自我认证。 编号与严谨性： ID为

AC-NNN-XX

——

NNN

= 本规格文档的文件夹编号，

XX

= 从01开始的两位零填充计数器；计划任务和测试引用该ID；根据范围调整严谨性。 标记（必填）： 每个验收标准必须携带一个标记——code-gated（可通过机器对照差异检查）或human-gated并附带具体验证方式（发布时路由至发布后验证）。标记在调研阶段为临时；tech-design确定方案后会确认或修改每个标记——仅修改标记的编辑，豁免于替代协议。 修订： 验收标准是实时协议——原地修订。当plan.md缺失或其Base SHA未设置时：直接编辑为最终形式，无需标记（若plan.md存在，适用修订规则的过期计划路径）。一旦Base SHA设置（构建开始）：添加尾部*(revised per D-NNN-XX)标记——该标记的存在始终表示构建中途变更；原因记录在替代决策中。 每个验收标准占一行： ID、行为、标记、任何(revised per D-NNN-XX)*标记均在同一行；Gate按行选择。]

AC-NNN-01: [可观察行为] — [code-gated]
AC-NNN-02: [可观察行为] — [human-gated: 具体验证方式]

Decisions

[Inline, atomic

D-NNN-XX

blocks — the durable why. Id format:

NNN

= this spec's folder number;

XX

= a zero-padded two-digit counter starting 01 — ONE counter per spec, shared by product (this skill) and tech (tech-design) decisions. Ids are unique across the repo (the folder number guarantees it) and never renumbered. Type marker: each heading carries

[product]

[tech]

after the colon — advisory for readers and routing, no gate greps it. Citing: cite the full id (

per D-NNN-07

), never a line number. Revising: while plan.md is absent or its

Base SHA:

is unset (planning stage — anchor form in Plan anchors,

skills/write-plan/SKILL.md

), edit blocks in place to their final shape — fold an overturned Chosen into Rejected with what killed it, so the why survives in the one block; if plan.md already exists, tell the user the plan may be stale and route through write-plan's existing-plan guard. Once Base SHA is set (build started), supersede, never edit the body. Another spec's block is always superseded, never edited, at any stage.]

[内联、原子化的

D-NNN-XX

块——持久化的原因。 ID格式：

NNN

= 本规格文档的文件夹编号；

XX

= 从01开始的两位零填充计数器——每个规格文档一个计数器，产品（本技能）和技术（tech-design）决策共享。ID在仓库中唯一（文件夹编号保证），绝不重新编号。 类型标记： 每个标题后携带

[product]

或

[tech]

——供读者参考和路由，Gate不检测此标记。 引用： 引用完整ID（

per D-NNN-07

），绝不引用行号。 修订： 当plan.md缺失或其

Base SHA:

未设置（规划阶段——锚点格式在Plan锚点、

skills/write-plan/SKILL.md

中），原地编辑块为最终形式——将被推翻的Chosen归入Rejected并说明原因，使原因保留在一个块中；若plan.md已存在，告知用户计划可能过期并路由至write-plan的现有计划防护。一旦Base SHA设置（构建开始），使用替代块，绝不编辑原块内容。任何阶段，其他规格文档的块始终被替代，绝不编辑。]

D-NNN-01: [product] [decision title]

D-NNN-01: [product] [决策标题]

Status: locked
Chosen: [the choice]
Rejected: [alt — why it lost]; [alt — deferred, not rejected forever — why]
Rationale: [the constraint that drove it; cite a verified fact if load-bearing]
Supersedes: —
Superseded-by: —

Status: locked
Chosen: [选择]
Rejected: [替代方案 — 被拒绝原因]; [替代方案 — deferred，并非永久拒绝 — 延迟原因]
Rationale: [驱动决策的约束；若关键，引用已验证的事实]
Supersedes: —
Superseded-by: —

Structure Outline

Constraints

[Fixed boundaries: compatibility, performance, platform limits, dependencies. Append-by-both: discovery seeds it; tech-design appends the load-bearing numbers its recon proves. Tag each wall

[hard]

(outside our control — stamp the assumption) ·

[ask]

(cross-team, movable) ·

[ours]

(our code) — advisory annotations, no gate greps them.]

[constraint] —
```
[hard|ask|ours]
```

[固定边界：兼容性、性能、平台限制、依赖项。双方均可添加：调研阶段初始化；tech-design添加其调研确认的关键数据。为每个阻碍标记

[hard]

（超出我们控制——标记假设）·

[ask]

（跨团队，可调整）·

[ours]

（我们的代码）——仅供参考的注释，Gate不检测。]

[约束] —
```
[hard|ask|ours]
```

Accepted risks (knowingly carried)

[Append-by-both: discovery seeds it; tech-design appends the risks the user accepts.]

[risk we choose to live with] — [why acceptable]

[双方均可添加：调研阶段初始化；tech-design添加用户接受的风险。]

[我们选择承担的风险] — [可接受的原因]

Open Questions

[NON-BLOCKING notes only — this section does not block the lock gate; blockers must be open-status decisions or inline clarification markers (see Gate anchors). Implementation questions for tech-design land here, tagged

(for tech-design)

. Omit this section entirely when empty.]

[non-blocking question] — [why it can wait]

[仅记录非阻碍性笔记——此部分不会阻碍锁定Gate；阻碍性内容必须是未解决状态的决策或内联澄清标记（参见Gate锚点）。tech-design的实现问题放入此处，标记

(for tech-design)

。为空时省略此部分。]

[非阻碍性问题] — [可延迟的原因]

Completion record

Shipped: [date] · Status: Complete | Partial

Shipped: [日期] · Status: Complete | Partial

Criteria results

AC	Result
AC-NNN-01	PASS / PARTIAL / FAIL — [1-line evidence]

AC	Result
AC-NNN-01	PASS / PARTIAL / FAIL — [1行证据]

Post-ship verification

[steps] → [expected result]
AC-NNN-XX: [steps] → [expected result]

[步骤] → [预期结果]
AC-NNN-XX: [步骤] → [预期结果]

Deferred / what this does NOT close

[deferred debt or known limitation, with severity] — or "None"

[延迟的债务或已知限制，及严重程度] — 或"None"

Review filter stats

[N dropped by pre-gate, M demoted, across all waves] — or "None"

undefined

[N个被Gate前遗漏，M个被降级，所有轮次] — 或"None"

undefined

Gate anchors (load-bearing — exact forms matter)

Gate anchors (关键——精确格式很重要)

These live OUTSIDE the template so they are never copied into a spec instance. Downstream gates (tech-design Step 1, write-plan Step 1) block on:

grep -nE '^[[:space:]]*-[[:space:]]*\*\*Status:\*\*[[:space:]]*open' spec.md   # any hit ⇒ blocked
grep -n '\[NEEDS CLARIFICATION:' spec.md                                       # any hit ⇒ blocked
grep -n '^### Files touched' spec.md                                           # write-plan Step 1 only: no hit ⇒ outline missing
grep -nE '^[[:space:]]*-[[:space:]]*\*\*Status:\*\*[[:space:]]*Draft' spec.md  # write-plan Step 1 only: + outline present ⇒ stale outline (reopened)

Rules that keep these greps sound — breaking any of them silently breaks the pipeline:

POSIX ERE only (
```
[[:space:]]
```
, never
```
\s
```
) — gates run through varying grep builds.
Case split is load-bearing: header Status values are Capitalized (
```
Draft/Locked/Shipped
```
); decision Status values are lowercase (
```
open/locked/superseded
```
). That asymmetry is what keeps the header line out of the decision-gate regex. Never normalize one to the other.
Clarification markers are always written with the colon (
```
[NEEDS CLARIFICATION: ...]
```
). The ban is by location, not intent: the colon form must NEVER appear in the canonical template body, or any text destined for a spec instance, where the gate would catch it; an illustrative
```
: ...
```
placeholder in this rules block or interview prose, as here, is fine — the gate reads spec.md, never SKILL.md.
Each AC is ONE physical line —
```
- **AC-NNN-XX:** behavior — [tag]
```
, keeping any
```
*(revised per D-NNN-XX)*
```
marker on that same line (a long AC stays on one line; the gates care about line count, not length). Both AC selections (execute-plan Step 4 / Seat A code-gated, Step 5.3 human-gated) grep the AC line, then filter for the tag — a tag wrapped onto a continuation line silently drops the AC from review or post-ship verification.
plan.md-side anchors (typed log tags, promotion marker, deferred tags) are defined beside the canonical plan template in
```
skills/write-plan/SKILL.md
```
.

这些内容位于模板外部，因此不会被复制到规格文档实例中。下游Gate（tech-design步骤1、write-plan步骤1）会阻碍以下情况：

grep -nE '^[[:space:]]*-[[:space:]]*\*\*Status:\*\*[[:space:]]*open' spec.md   # 任何匹配结果 ⇒ 阻碍
grep -n '\[NEEDS CLARIFICATION:' spec.md                                       # 任何匹配结果 ⇒ 阻碍
grep -n '^### Files touched' spec.md                                           # 仅write-plan步骤1：无匹配结果 ⇒ 大纲缺失
grep -nE '^[[:space:]]*-[[:space:]]*\*\*Status:\*\*[[:space:]]*Draft' spec.md  # 仅write-plan步骤1：+ 大纲存在 ⇒ 过期大纲（重新开启）

确保这些检测有效的规则——违反任何规则都会静默破坏流程：

仅使用POSIX ERE（
```
[[:space:]]
```
，绝不使用
```
\s
```
）——Gate通过不同的grep版本运行。
大小写区分关键：标题的Status值首字母大写（
```
Draft/Locked/Shipped
```
）；决策的Status值小写（
```
open/locked/superseded
```
）。这种不对称性确保标题行不会被决策Gate的正则表达式匹配。绝不要统一大小写。
澄清标记必须始终带冒号（
```
[NEEDS CLARIFICATION: ...]
```
）。禁止在规范模板正文或任何将写入规格文档实例的文本中出现该格式，否则Gate会检测到；本规则块或访谈文本中的示例
```
: ...
```
占位符是允许的——Gate仅读取spec.md，绝不读取SKILL.md。
每个验收标准占一行——
```
- **AC-NNN-XX:** behavior — [tag]
```
，任何
```
*(revised per D-NNN-XX)*
```
标记必须在同一行（长验收标准保持一行；Gate关注行数，而非长度）。验收标准的选择（execute-plan步骤4 / Seat A code-gated，步骤5.3 human-gated）会检测验收标准行，然后过滤标记——若标记换行，会导致验收标准被静默排除在评审或发布后验证之外。
plan.md侧的锚点（类型化日志标记、升级标记、延迟标记）在
```
skills/write-plan/SKILL.md
```
中的规范计划模板旁定义。