design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design a change — create a change container (if needed) and generate spec artifacts.

<decision_boundary>

Use for:

Creating a new Beat change and generating spec artifacts (proposal, gherkin, design.md)
Resuming artifact generation for an existing change that has pending spec artifacts
Choosing which spec artifacts to include (presets: Full, Standard, Minimal, Technical, Custom)

NOT for:

Breaking down tasks or creating execution plans (use
```
/beat:plan
```
)
Exploring ideas or thinking through a problem before committing (use
```
/beat:explore
```
)
Implementing code (use
```
/beat:apply
```
)
Reviewing or verifying implementation (use
```
/beat:verify
```
)

Trigger examples:

"Design a user authentication feature" / "Create a change for login" / "Generate specs for X"
Should NOT trigger: "break down the tasks" / "let me think about this" / "implement the change"

</decision_boundary>

<HARD-GATE> Before writing any artifact files: you MUST invoke superpowers:using-git-worktrees. When the artifact selection includes proposal or design, you MUST invoke superpowers:brainstorming before generating content. This applies even when scope seems obvious.

Before writing gherkin scenarios: you MUST run the four-challenge CONTEXT.md check (see step 4 below) and ensure every project-specific term used in scenarios is defined in

beat/CONTEXT.md

. Create the glossary lazily — only when the first term is added.

After writing each artifact: you MUST run the four-check spec self-review (placeholder / consistency / scope / ambiguity). Fix issues inline.

While writing

design.md

: you MUST run the three-condition ADR gate (hard-to-reverse + surprising + real trade-off — see

references/adr-format.md

) on each Key Decision. When all three hold, offer to lift the decision into a new ADR under

docs/adr/

. The user may decline.

Invoke in order: worktrees first (isolate), then brainstorming (design).

If a prerequisite skill is unavailable (not installed), continue with fallback — but NEVER skip because you judged it unnecessary. </HARD-GATE>

Prerequisites (invoke before proceeding)

Skill	When	Priority
superpowers:using-git-worktrees	Before first file write	MUST
superpowers:brainstorming	Before creating proposal or design	MUST
mattpocock-skills:grill-with-docs	When CONTEXT.md ambiguity is complex enough that a full grilling session is warranted	OPTIONAL

If a prerequisite skill is unavailable (skill not installed), skip and continue. For optional skills (grill-with-docs), offer to invoke when applicable; if the user declines or it isn't installed, proceed with the four-challenge check inline.

设计变更——创建变更容器（如有需要）并生成规格工件。

<decision_boundary>

适用场景：

创建新的Beat变更并生成规格工件（proposal、gherkin、design.md）
为已有且存在待处理规格工件的变更恢复工件生成
选择要包含的规格工件（预设：完整、标准、最小、技术、自定义）

不适用场景：

任务分解或创建执行计划（使用
```
/beat:plan
```
）
在确定方案前探索想法或梳理问题（使用
```
/beat:explore
```
）
代码实现（使用
```
/beat:apply
```
）
评审或验证实现（使用
```
/beat:verify
```
）

触发示例：

"设计用户认证功能" / "创建登录相关变更" / "为X生成规格"
不应触发："分解任务" / "让我梳理一下这个问题" / "实现该变更"

</decision_boundary>

<HARD-GATE> 在编写任何工件文件之前：你必须调用superpowers:using-git-worktrees。当工件选择包含proposal或design时，在生成内容之前你必须调用superpowers:brainstorming，即使范围看起来很明确也需执行此操作。

在编写gherkin场景之前：你必须运行四项挑战的CONTEXT.md检查（见下方步骤4），确保场景中使用的每个项目特定术语都在

beat/CONTEXT.md

中定义。仅在添加第一个术语时才延迟创建术语表。

编写完每个工件后：你必须运行四项检查的规格自我评审（占位符/一致性/范围/歧义）。直接修复问题。

编写

design.md

时：你必须针对每个关键决策运行三项条件的ADR检查（难以逆转 + 出人意料 + 真实权衡——见

references/adr-format.md

）。当三项条件都满足时，提议将该决策提升至

docs/adr/

下的新ADR中。用户可以拒绝。

调用顺序：先调用worktrees（隔离），再调用brainstorming（设计）。

如果某个必备技能不可用（未安装），请使用回退方案继续——但绝不能因为你认为不必要而跳过。 </HARD-GATE>

前置条件（执行前调用）

技能	调用时机	优先级
superpowers:using-git-worktrees	首次写入文件前	必须
superpowers:brainstorming	创建proposal或design前	必须
mattpocock-skills:grill-with-docs	当CONTEXT.md的歧义复杂到需要完整的审查会话时	可选

如果某个必备技能不可用（未安装），请跳过并继续。对于可选技能（grill-with-docs），在适用时提议调用；如果用户拒绝或未安装该技能，则直接执行四项挑战检查。

Rationalization Prevention

避免合理化借口

Thought	Reality
"I don't need a worktree for just writing specs"	Without a worktree, artifacts live in the main workspace and won't carry into apply. Isolate from the start.
"brainstorming isn't needed, the user already described what they want"	A description is not a design. brainstorming surfaces assumptions, alternatives, and edge cases.
"The user wants speed, invoking superpowers will slow us down"	Skipping prerequisites produces lower-quality artifacts that cause rework during apply and verify.
"This change is simple enough to skip brainstorming"	Simple changes finish brainstorming quickly. Complex changes need it most. There is no middle ground where skipping helps.
"The domain terms are obvious, no need to update CONTEXT.md"	Obvious to you, not to future-you or anyone else reading the feature in six months. Glossary entries are two lines. Add them inline.
"Spec self-review is overkill, the artifact is short"	Self-review catches placeholders, contradictions, and ambiguities that compound through plan and apply. The four checks take 30 seconds.
"This decision is just for this change, no ADR needed"	Run the three-condition gate. If it's hard-to-reverse, surprising, and a real trade-off, future changes will trip over it — that's the ADR's job. Decisions that are change-specific don't pass the gate; let the gate decide, not your gut.
"We'll lift this into an ADR later"	"Later" rarely arrives. The decision is fresh now; the ADR is 1-3 sentences. Write it inline.

想法	实际情况
"我只是写规格，不需要worktree"	没有worktree的话，工件会存放在主工作区，无法同步到apply环节。从一开始就隔离变更。
"用户已经描述了需求，不需要brainstorming"	描述不等于设计。brainstorming会挖掘假设、替代方案和边缘情况。
"用户想要速度，调用超能力会拖慢进度"	跳过前置条件会生成低质量工件，导致apply和verify环节需要返工。
"这个变更很简单，可以跳过brainstorming"	简单变更的brainstorming很快完成，复杂变更最需要它。没有任何场景下跳过是有益的。
"领域术语很明显，不需要更新CONTEXT.md"	对你来说明显，但对六个月后查看该功能的未来的你或其他人来说并非如此。术语表条目只需两行，直接添加即可。
"规格自我评审是多余的，工件很短"	自我评审会发现占位符、矛盾和歧义，这些问题会在plan和apply环节不断扩大。四项检查只需30秒。
"这个决策只针对本次变更，不需要ADR"	运行三项条件检查。如果它难以逆转、出人意料且是真实权衡的结果，未来的变更会因此受阻——这正是ADR的作用范围。仅针对本次变更的决策不会通过检查；让检查来决定，而非你的直觉。
"我们之后再把它提升为ADR"	"之后"通常不会到来。现在决策还很清晰，ADR只需1-3句话。直接写入即可。

Red Flags — STOP if you catch yourself:

危险信号——如果发现以下情况请立即停止：

Writing any file before invoking using-git-worktrees
Generating proposal sections without having invoked brainstorming
Creating design.md without invoking brainstorming first
Writing gherkin scenarios that contain internal method names, numeric thresholds, or implementation constants
Writing gherkin scenarios that use project-specific domain terms not defined in
```
beat/CONTEXT.md
```
Modifying an existing feature in
```
beat/features/
```
without creating a
```
.orig
```
backup first
Writing tasks.md or
```
- [ ]
```
checkboxes — tasks belong in
```
/beat:plan
```
Skipping the spec self-review because the artifact "looks fine"
Writing a Key Decision in
```
design.md
```
that meets all three ADR conditions without offering an ADR
Thinking "this prerequisite isn't needed for this particular change"

在调用using-git-worktrees之前编写任何文件
未调用brainstorming就生成proposal部分
未先调用brainstorming就创建design.md
编写包含内部方法名、数值阈值或实现常量的gherkin场景
编写使用未在
```
beat/CONTEXT.md
```
中定义的项目特定领域术语的gherkin场景
在未创建
```
.orig
```
备份的情况下修改
```
beat/features/
```
中的现有功能
编写tasks.md或
```
- [ ]
```
复选框——任务属于
```
/beat:plan
```
的范畴
因为工件“看起来没问题”而跳过规格自我评审
在design.md中写入满足所有三项ADR条件的关键决策却未提议创建ADR
认为“这个前置条件对本次变更来说不需要”

Process Flow

流程

dot

digraph design {
    "Select or create change" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "Ask artifact preset" [shape=box];
    "Includes proposal?" [shape=diamond];
    "Invoke brainstorming" [shape=box, style=bold];
    "Create proposal" [shape=box];
    "Self-review proposal" [shape=box, style=bold];
    "Includes gherkin?" [shape=diamond];
    "CONTEXT.md\nfour-challenge check" [shape=box, style=bold];
    "Existing scenarios\nto modify?" [shape=diamond];
    "Backup .orig +\ncopy to changes/" [shape=box];
    "Create gherkin\n(new features only)" [shape=box];
    "Self-review gherkin" [shape=box, style=bold];
    "Includes design?" [shape=diamond];
    "Create design" [shape=box];
    "ADR gate\n(per Key Decision)" [shape=box, style=bold];
    "Self-review design" [shape=box, style=bold];
    "Commit artifacts" [shape=box];
    "Show summary" [shape=doublecircle];

    "Select or create change" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "Ask artifact preset";
    "Ask artifact preset" -> "Includes proposal?";
    "Includes proposal?" -> "Invoke brainstorming" [label="yes"];
    "Includes proposal?" -> "Includes gherkin?" [label="no"];
    "Invoke brainstorming" -> "Create proposal";
    "Create proposal" -> "Self-review proposal";
    "Self-review proposal" -> "Includes gherkin?";
    "Includes gherkin?" -> "CONTEXT.md\nfour-challenge check" [label="yes"];
    "Includes gherkin?" -> "Includes design?" [label="no"];
    "CONTEXT.md\nfour-challenge check" -> "Existing scenarios\nto modify?";
    "Existing scenarios\nto modify?" -> "Backup .orig +\ncopy to changes/" [label="yes"];
    "Existing scenarios\nto modify?" -> "Create gherkin\n(new features only)" [label="no"];
    "Backup .orig +\ncopy to changes/" -> "Create gherkin\n(new features only)";
    "Create gherkin\n(new features only)" -> "Self-review gherkin";
    "Self-review gherkin" -> "Includes design?";
    "Includes design?" -> "Invoke brainstorming" [label="yes, only if\nnot yet invoked"];
    "Includes design?" -> "Commit artifacts" [label="no"];
    "Invoke brainstorming" -> "Create design" [label="for design"];
    "Create design" -> "ADR gate\n(per Key Decision)" [style=bold];
    "ADR gate\n(per Key Decision)" -> "Self-review design";
    "Self-review design" -> "Commit artifacts";
    "Commit artifacts" -> "Show summary";
}

Input: Change name (kebab-case) OR a description of what to build. Can also be an existing change name to fast-forward remaining artifacts.

Steps

If no clear input provided, ask what they want to build

Use AskUserQuestion tool to ask what they want to build. Derive kebab-case name from description.
Create or select change
Determine the change name. Before creating any files, invoke
```
using-git-worktrees
```
to isolate this change.
- If
```
beat/changes/<name>/
```
  doesn't exist: create it (directory + status.yaml + features/.gitkeep)
- If it exists: use it, read
```
status.yaml
```
  (schema:
```
references/status-schema.md
```
  ) to find remaining artifacts
Ask which spec artifacts to include
Read
```
status.yaml
```
. For artifacts still
```
pending
```
, ask user once upfront:
Use AskUserQuestion tool:
"Which spec artifacts do you want? (Tasks are handled separately by
```
/beat:plan
```
)"
1. Full: Proposal + Gherkin + Design (recommended for large features)
2. Standard: Proposal + Gherkin (recommended for medium features)
3. Minimal: Gherkin only (recommended for small bug fixes)
4. Technical: Proposal only, no Gherkin (for tooling/infra/refactor changes with no behavior change)
5. Custom: Let me choose each one
Mark skipped artifacts as
```
skipped
```
in
```
status.yaml
```
. Tasks are always set to
```
pending
```
— task breakdown happens in
```
/beat:plan
```
. Update
```
phase
```
to match the latest completed spec artifact after each creation.
Create artifacts in pipeline order
Read
```
beat/config.yaml
```
if it exists (schema:
```
references/config-schema.md
```
). Use
```
language
```
for artifact output language, inject
```
context
```
, and apply matching
```
rules
```
per artifact type throughout creation.
For each artifact to create (pipeline order: proposal -> gherkin -> design):
- Read all completed artifacts for context
- Invoke prerequisites per the table above (brainstorming before proposal/design — invoke once before the first artifact that needs it; skip for subsequent artifacts if already invoked)
- Gherkin only — before writing scenarios: run the CONTEXT.md four-challenge check (see sub-step below)
- Create the artifact following the patterns below
- After writing: run the spec self-review (see sub-step below); fix issues inline
- Update
```
status.yaml
```
- Show brief progress: "Created <artifact>"
- If context is critically unclear, pause and ask
CONTEXT.md four-challenge check (before writing gherkin):
Read
```
beat/CONTEXT.md
```
if it exists (schema:
```
references/context-format.md
```
). Create it lazily when the first term is added — never preemptively.
Walk through the brainstorming output and any draft scenario text. For each project-specific term, run these checks and update
```
beat/CONTEXT.md
```
inline as findings emerge (never batch):
1. Against the glossary — the term conflicts with an existing entry? Call it out, resolve, update.
2. Sharpen fuzzy — the term is vague or overloaded (e.g. "account" meaning Customer and User both)? Pick the canonical word, list the others as
```
_Avoid_
```
  .
3. Stress-test — invent edge-case scenarios that probe term boundaries; force the boundary to be named.
4. Cross-reference code — the user states behaviour that the code contradicts? Surface, decide source of truth, update the loser.
Optional grilling: If
```
mattpocock-skills:grill-with-docs
```
is installed and the ambiguity is complex enough to warrant a full grilling session, offer to invoke it once: "Want to drop into grill-with-docs for a deeper pass on this?" If the user declines, or the skill isn't installed, continue inline with the four challenges. Beat never hard-requires grill-with-docs.
Every project-specific term used in scenarios MUST exist in
```
beat/CONTEXT.md
```
before the scenario is written. Bolded terms in scenarios are the canonical form.
Spec self-review (after writing each artifact):

Re-read the artifact with fresh eyes and check:
1. Placeholder scan — any
```
TBD
```
  ,
```
TODO
```
  , incomplete sections, vague requirements?
2. Internal consistency — do sections contradict each other? Does the design match the gherkin scenarios?
3. Scope check — is this focused enough for a single implementation plan, or does it need decomposition?
4. Ambiguity check — could any requirement be read two different ways? If so, pick one and make it explicit.
Fix issues inline. No need to re-review the fix — just fix and move on.

Artifact patterns:
- Proposal: Sections:
```
## Why
```
  ,
```
## What Changes
```
  ,
```
## Impact
```
- Gherkin:
  - Read
```
references/feature-writing.md
```
    for conventions on description blocks, scenario organization, and review checklist
  - Before writing, scan
```
beat/features/**/*.feature
```
    and
```
beat/changes/*/features/*.feature
```
    (excluding current change) — read
```
Feature:
```
    and
```
Scenario:
```
    lines to map existing coverage, deep-read only overlapping features, avoid duplication and align style
  - SpecFlow style, tags
```
@happy-path
```
    /
```
@error-handling
```
    /
```
@edge-case
```
  - Feature description carries PRD essence (must include: As a / I want / So that)
  - Every scenario MUST have a testing layer tag:
```
@e2e
```
    (user journeys needing a running app) or
```
@behavior
```
    (business logic testable without a full app; default
```
@behavior
```
    )
  - Write at behavior level — describe what the system does ("Monthly billing adjusts for short months"), not how a function works ("calculateNextTransactionDate clamps to last day")
  - Use business language — no concrete numeric thresholds, code method names, or internal constants (API contract constants are OK as shared vocabulary)
  - Repeated Given steps use
```
Background:
```
  - Tags must serve a filtering purpose — no decorative tags
  - BDD focuses on high-level acceptance; boundary values and algorithm details belong in unit tests
  - If option 4 (Technical) was chosen, skip gherkin entirely
  Modifying existing features (see
```
references/testing-conventions.md
```
  for full mechanism):
  When the scan reveals scenarios in
```
beat/features/
```
  that need modification:
  1. Conflict check: scan
```
beat/features/**/*.feature.orig
```
    — if a
```
.orig
```
    exists for the same file, another change is modifying it. Warn and stop.
  2. Backup: rename the original in
```
beat/features/
```
    to
```
.feature.orig
```
    (hides it from BDD runners)
  3. Copy: copy the original content to
```
beat/changes/<name>/features/<file>.feature
```
  4. Modify: edit the scenario(s) in the
```
changes/
```
    copy (add/change/remove steps, add new scenarios)
  5. Record: add the original path to
```
status.yaml
```
```
gherkin.modified
```
    array
  New features that don't modify existing scenarios go directly to
```
changes/<name>/features/
```
  as before.
- Design:
  - Sections:
```
## Approach
```
    ,
```
## Key Decisions
```
    ,
```
## Components
```
  - ADR gate — for each Key Decision, run the three-condition check from
```
references/adr-format.md
```
    :
    1. Hard to reverse? (cost of changing your mind is meaningful)
    2. Surprising without context? (future reader will wonder "why on earth this way?")
    3. Result of a real trade-off? (genuine alternatives existed) If all three hold, use AskUserQuestion tool: "This decision meets the ADR gate. Lift it into
      docs/adr/
      ?" On Yes, write a 1-3 sentence ADR using the template in
      references/adr-format.md
      , increment the highest existing number in
      docs/adr/
      by one, and add a cross-reference from
      design.md
      (
      See docs/adr/NNNN-slug.md
      ). On No, continue. Create
      docs/adr/
      lazily — only on first ADR.

Commit artifacts and show final status

Commit all change artifacts:

git add beat/changes/<name>/ && git commit

Update phase to the latest completed spec artifact in

status.yaml

## Design Complete: <change-name>

Created:
- proposal.md (or skipped)
- features/*.feature (or skipped if Technical option)
- design.md (or skipped)

Tasks: pending (run `/beat:plan` to create execution plan)

Spec artifacts ready! Review them, then run `/beat:plan` for task breakdown.

Guardrails

Gherkin is mandatory by default -- only skip for purely technical changes (option 4: Technical)
Ask upfront which artifacts to include (don't ask per artifact)
If change already exists with some artifacts done, only create remaining
If context is critically unclear, ask -- but prefer reasonable defaults to keep momentum
Verify each artifact file exists after writing before proceeding
Tasks are NOT created in this skill — they are handled by
```
/beat:plan
```

dot

digraph design {
    "Select or create change" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "Ask artifact preset" [shape=box];
    "Includes proposal?" [shape=diamond];
    "Invoke brainstorming" [shape=box, style=bold];
    "Create proposal" [shape=box];
    "Self-review proposal" [shape=box, style=bold];
    "Includes gherkin?" [shape=diamond];
    "CONTEXT.md\nfour-challenge check" [shape=box, style=bold];
    "Existing scenarios\nto modify?" [shape=diamond];
    "Backup .orig +\ncopy to changes/" [shape=box];
    "Create gherkin\n(new features only)" [shape=box];
    "Self-review gherkin" [shape=box, style=bold];
    "Includes design?" [shape=diamond];
    "Create design" [shape=box];
    "ADR gate\n(per Key Decision)" [shape=box, style=bold];
    "Self-review design" [shape=box, style=bold];
    "Commit artifacts" [shape=box];
    "Show summary" [shape=doublecircle];

    "Select or create change" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "Ask artifact preset";
    "Ask artifact preset" -> "Includes proposal?";
    "Includes proposal?" -> "Invoke brainstorming" [label="yes"];
    "Includes proposal?" -> "Includes gherkin?" [label="no"];
    "Invoke brainstorming" -> "Create proposal";
    "Create proposal" -> "Self-review proposal";
    "Self-review proposal" -> "Includes gherkin?";
    "Includes gherkin?" -> "CONTEXT.md\nfour-challenge check" [label="yes"];
    "Includes gherkin?" -> "Includes design?" [label="no"];
    "CONTEXT.md\nfour-challenge check" -> "Existing scenarios\nto modify?";
    "Existing scenarios\nto modify?" -> "Backup .orig +\ncopy to changes/" [label="yes"];
    "Existing scenarios\nto modify?" -> "Create gherkin\n(new features only)" [label="no"];
    "Backup .orig +\ncopy to changes/" -> "Create gherkin\n(new features only)";
    "Create gherkin\n(new features only)" -> "Self-review gherkin";
    "Self-review gherkin" -> "Includes design?";
    "Includes design?" -> "Invoke brainstorming" [label="yes, only if\nnot yet invoked"];
    "Includes design?" -> "Commit artifacts" [label="no"];
    "Invoke brainstorming" -> "Create design" [label="for design"];
    "Create design" -> "ADR gate\n(per Key Decision)" [style=bold];
    "ADR gate\n(per Key Decision)" -> "Self-review design";
    "Self-review design" -> "Commit artifacts";
    "Commit artifacts" -> "Show summary";
}

输入：变更名称（短横线分隔格式）或要构建内容的描述。也可以是已有变更名称，用于快速生成剩余工件。

步骤

如果未提供明确输入，询问用户要构建的内容

使用AskUserQuestion工具询问用户要构建的内容。从描述中推导短横线分隔格式的名称。
创建或选择变更
确定变更名称。在创建任何文件之前，调用
```
using-git-worktrees
```
来隔离此变更。
- 如果
```
beat/changes/<name>/
```
  不存在：创建该目录（包含目录 + status.yaml + features/.gitkeep）
- 如果已存在：使用该目录，读取
```
status.yaml
```
  （schema：
```
references/status-schema.md
```
  ）以找出待完成的工件
询问要包含的规格工件
读取
```
status.yaml
```
。对于仍处于
```
pending
```
状态的工件，提前一次性询问用户：
使用AskUserQuestion工具：
"你需要哪些规格工件？（任务由
```
/beat:plan
```
单独处理）"
1. 完整：Proposal + Gherkin + Design（推荐用于大型功能）
2. 标准：Proposal + Gherkin（推荐用于中型功能）
3. 最小：仅Gherkin（推荐用于小型bug修复）
4. 技术：仅Proposal，无Gherkin（适用于无行为变更的工具/基建/重构变更）
5. 自定义：让我逐个选择
在
```
status.yaml
```
中将跳过的工件标记为
```
skipped
```
。任务始终设置为
```
pending
```
——任务分解在
```
/beat:plan
```
中进行。每次创建工件后，更新
```
phase
```
以匹配最新完成的规格工件。
按流水线顺序创建工件
如果
```
beat/config.yaml
```
存在则读取该文件（schema：
```
references/config-schema.md
```
）。使用
```
language
```
指定工件输出语言，注入
```
context
```
，并在创建过程中为每种工件类型应用匹配的
```
rules
```
。
对于每个要创建的工件（流水线顺序：proposal -> gherkin -> design）：
- 读取所有已完成的工件以获取上下文
- 调用上表中的前置条件（proposal/design前调用brainstorming——在第一个需要该技能的工件前调用一次；如果已调用，则后续工件跳过）
- 仅Gherkin——编写场景前：运行CONTEXT.md四项挑战检查（见下方子步骤）
- 按照以下模式创建工件
- 编写后：运行规格自我评审（见下方子步骤）；直接修复问题
- 更新
```
status.yaml
```
- 显示简要进度："已创建<artifact>"
- 如果上下文严重不明确，暂停并询问
CONTEXT.md四项挑战检查（编写gherkin前）：
如果
```
beat/CONTEXT.md
```
存在则读取该文件（schema：
```
references/context-format.md
```
）。仅在添加第一个术语时才延迟创建该文件——绝不提前创建。
梳理brainstorming输出和任何场景草稿文本。对于每个项目特定术语，运行以下检查并实时更新
```
beat/CONTEXT.md
```
（绝不批量处理）：
1. 术语表冲突检查——该术语与现有条目冲突？指出问题、解决并更新。
2. 模糊术语明确化——该术语模糊或含义过载（例如"account"同时指客户和用户）？选择标准术语，将其他术语列为
```
_Avoid_
```
  。
3. 边界压力测试——发明边缘场景来测试术语的边界；明确命名边界。
4. 代码交叉验证——用户描述的行为与代码矛盾？指出问题、确定事实来源、更新错误方。
可选审查：如果
```
mattpocock-skills:grill-with-docs
```
已安装且歧义复杂到需要完整审查会话，提议调用一次：*"是否要启动grill-with-docs进行更深入的审查？"*如果用户拒绝或未安装该技能，则继续执行四项挑战检查。Beat绝不强制要求使用grill-with-docs。
场景中使用的每个项目特定术语必须在编写场景前已存在于
```
beat/CONTEXT.md
```
中。场景中的加粗术语为标准形式。
规格自我评审（每个工件编写后）：

以全新视角重新阅读工件并检查：
1. 占位符扫描——是否存在
```
TBD
```
  、
```
TODO
```
  、不完整章节、模糊需求？
2. 内部一致性——章节之间是否存在矛盾？设计是否与gherkin场景匹配？
3. 范围检查——内容是否足够聚焦以适配单个实现计划，还是需要分解？
4. 歧义检查——是否有需求可以被两种不同方式解读？如果有，选择一种并明确说明。
直接修复问题。无需重新审查修复内容——修复后继续即可。

工件模式：
- Proposal：章节：
```
## 原因
```
  、
```
## 变更内容
```
  、
```
## 影响
```
- Gherkin:
  - 阅读
```
references/feature-writing.md
```
    了解描述块、场景组织和评审清单的约定
  - 编写前，扫描
```
beat/features/**/*.feature
```
    和
```
beat/changes/*/features/*.feature
```
    （排除当前变更）——读取
```
Feature:
```
    和
```
Scenario:
```
    行以梳理现有覆盖范围，仅深入阅读重叠功能，避免重复并对齐风格
  - SpecFlow风格，标签
```
@happy-path
```
    /
```
@error-handling
```
    /
```
@edge-case
```
  - Feature描述需包含PRD核心内容（必须包含：作为一名 / 我想要 / 以便）
  - 每个场景必须包含测试层标签：
```
@e2e
```
    （需要运行应用的用户旅程）或
```
@behavior
```
    （无需完整应用即可测试的业务逻辑；默认
```
@behavior
```
    ）
  - 从行为层面编写——描述系统做了什么（"月度账单会针对短月份调整"），而非函数如何工作（"calculateNextTransactionDate限制为当月最后一天"）
  - 使用业务语言——不使用具体数值阈值、代码方法名或内部常量（API契约常量作为共享词汇是允许的）
  - 重复的Given步骤使用
```
Background:
```
  - 标签必须用于过滤——无装饰性标签
  - BDD聚焦于高层验收；边界值和算法细节属于单元测试范畴
  - 如果选择了选项4（技术），完全跳过gherkin
  修改现有功能（完整机制见
```
references/testing-conventions.md
```
  ）：
  当扫描发现
```
beat/features/
```
  中的场景需要修改时：
  1. 冲突检查：扫描
```
beat/features/**/*.feature.orig
```
    ——如果同一文件存在
```
.orig
```
    ，说明另一个变更正在修改它。发出警告并停止。
  2. 备份：将
```
beat/features/
```
    中的原始文件重命名为
```
.feature.orig
```
    （使其对BDD运行器不可见）
  3. 复制：将原始内容复制到
```
beat/changes/<name>/features/<file>.feature
```
  4. 修改：在
```
changes/
```
    的副本中编辑场景（添加/修改/删除步骤、添加新场景）
  5. 记录：将原始路径添加到
```
status.yaml
```
    的
```
gherkin.modified
```
    数组中
  不修改现有场景的新功能直接存入
```
changes/<name>/features/
```
  ，与之前一致。
- Design:
  - 章节：
```
## 方案
```
    、
```
## 关键决策
```
    、
```
## 组件
```
  - ADR检查——针对每个关键决策，运行
```
references/adr-format.md
```
    中的三项条件检查：
    1. 是否难以逆转？（改变主意的成本很高）
    2. 无上下文时是否出人意料？（未来读者会疑惑"为什么要这么做？"）
    3. 是否是真实权衡的结果？（存在真正的替代方案）如果三项都满足，使用AskUserQuestion工具：*"该决策符合ADR检查标准。是否要将其提升至
      docs/adr/
      ？"*如果用户同意，使用
      references/adr-format.md
      中的模板编写1-3句话的ADR，将
      docs/adr/
      中最高编号加1，并在
      design.md
      中添加交叉引用（
      See docs/adr/NNNN-slug.md
      ）。如果用户拒绝，继续执行。仅在首次创建ADR时才延迟创建
      docs/adr/
      目录。

提交工件并显示最终状态

提交所有变更工件：

git add beat/changes/<name>/ && git commit

在

status.yaml

中将phase更新为最新完成的规格工件。

## 设计完成：<change-name>

已创建：
- proposal.md（或已跳过）
- features/*.feature（如果选择技术选项则已跳过）
- design.md（或已跳过）

任务：待处理（运行`/beat:plan`创建执行计划）

规格工件已准备就绪！请评审后运行`/beat:plan`进行任务分解。

约束规则

默认情况下Gherkin是强制要求的——仅针对纯技术变更（选项4：技术）才跳过
提前询问要包含的工件（不要逐个询问）
如果变更已存在且部分工件已完成，仅创建剩余工件
如果上下文严重不明确，询问用户——但优先使用合理默认值以保持进度
编写后验证每个工件文件是否存在，再继续下一步
本技能不创建任务——任务由
```
/beat:plan
```
处理