spec-driven-propose

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are helping the user create a new spec-driven change proposal.

你正在协助用户创建一份新的规范驱动型变更提案。

Prerequisites

前置条件

The

.spec-driven/

directory must exist at the project root. Before proceeding, verify:

ls .spec-driven/

If this fails, the project is not initialized. Run

/spec-driven-init

first.

.spec-driven/

目录必须存在于项目根目录下。在开始前，请验证：

ls .spec-driven/

如果验证失败，说明项目尚未初始化，请先运行

/spec-driven-init

。

Steps

步骤

Get the change name — ask the user for a short kebab-case name describing the change (e.g.
```
add-auth
```
,
```
refactor-db-layer
```
). If they already provided one, use it.
Read project context and existing specs — read the following before generating anything:
- ```
.spec-driven/config.yaml
```
  — use
```
context
```
  to inform content; treat
```
rules
```
  as binding constraints; note any
```
fileMatch
```
  entries that apply to files this change will touch
- ```
.spec-driven/specs/INDEX.md
```
  — identifies all existing spec files and their scope
- Every spec file referenced in INDEX.md that this change is likely to touch — read the full content to understand existing requirements before writing MODIFIED or ADDED entries

Scaffold the change — run:

node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>

This creates

.spec-driven/changes/<name>/

with empty seed files.

Fill proposal.md — write a clear, concise proposal covering:
- What: What the change does (observable behavior, not implementation)
- Why: Motivation and context
- Scope: What is in scope, what is explicitly out of scope
- Unchanged Behavior: List existing behaviors that must not break — things adjacent to or potentially affected by this change. Leave blank if truly nothing is at risk.
Fill design.md — write the technical approach:
- Approach: How you'll implement it at a high level
- Key Decisions: Significant choices and their rationale
- Alternatives Considered: What was ruled out and why
Populate specs/ delta files — look at the project's
```
.spec-driven/specs/
```
directory structure. For each spec file that this change touches, create a corresponding file under
```
.spec-driven/changes/<name>/specs/
```
mirroring the same relative path (e.g.
```
specs/auth/login.md
```
→
```
changes/<name>/specs/auth/login.md
```
).
Each delta file uses ADDED/MODIFIED/REMOVED sections with the standard format:
- ```
### Requirement: <name>
```
  headings and RFC 2119 keywords (MUST/SHOULD/MAY)
- ```
#### Scenario:
```
  blocks (GIVEN/WHEN/THEN) where helpful
- ADDED: new requirements; MODIFIED: changed requirements (include
```
Previously:
```
  note); REMOVED: removed requirements (include reason)
- Omit sections that don't apply — do not leave empty sections
- If this change has no observable spec impact, create a file with a brief explanation
Fill tasks.md — write a concrete implementation checklist:
- Use
```
- [ ]
```
  checkboxes for every task
- Tasks should be independently completable
- Group under three sections:
```
## Implementation
```
  ,
```
## Testing
```
  ,
```
## Verification
```
- ```
## Testing
```
  MUST include at least lint and unit test tasks appropriate to the project's tech stack (read from config.yaml context)
- Do NOT add an "Update specs" task — the specs/ directory contains the spec artifacts
Fill questions.md — document any open questions or ambiguities:
- For every unclear point (motivation, scope boundaries, technical approach, etc.), add an entry under
```
## Open
```
  :
```
- [ ] Q: <specific question>
  Context: <why this matters / what depends on the answer>
```
- If everything is clear, leave
```
## Open
```
  empty with a note:
```

```
- Do NOT use
```
[NEEDS CLARIFICATION]
```
  inline markers in any artifact — questions.md is the single place for all open questions
Confirm — show the user the five files and ask if they want to adjust anything. If
```
questions.md
```
has open questions, list each one explicitly and ask the user to resolve them before proceeding to
```
/spec-driven-apply
```
.

获取变更名称 —— 询问用户一个简短的kebab-case格式的变更名称（例如
```
add-auth
```
、
```
refactor-db-layer
```
）。如果用户已提供，则直接使用该名称。
读取项目上下文与现有规范 —— 在生成任何内容前，先读取以下文件：
- ```
.spec-driven/config.yaml
```
  —— 使用
```
context
```
  字段来填充内容；将
```
rules
```
  视为约束条件；记录与本次变更涉及文件相关的
```
fileMatch
```
  条目
- ```
.spec-driven/specs/INDEX.md
```
  —— 识别所有现有规范文件及其范围
- INDEX.md中提及的、与本次变更可能相关的所有规范文件 —— 完整读取内容，以便在编写MODIFIED或ADDED条目之前理解现有要求
生成变更基础文档 —— 运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
```
此命令会创建
```
.spec-driven/changes/<name>/
```
目录，并生成空的初始文件。
填充proposal.md —— 撰写清晰简洁的提案，内容包括：
- 内容: 变更的具体作用（描述可观察的行为，而非实现细节）
- 动机: 变更的原因与背景
- 范围: 变更包含的内容，以及明确排除的内容
- 未变更行为: 列出所有不得被破坏的现有行为——即与变更相关或可能受影响的内容。如果确实没有风险，则留空。
填充design.md —— 撰写技术实现方案：
- 实现思路: 高层次的实现方法
- 关键决策: 重要的选择及其理由
- 备选方案: 被否决的方案及其原因
生成specs/增量文件 —— 查看项目的
```
.spec-driven/specs/
```
目录结构。对于本次变更涉及的每个规范文件，在
```
.spec-driven/changes/<name>/specs/
```
下创建对应的文件，保持相对路径一致（例如
```
specs/auth/login.md
```
→
```
changes/<name>/specs/auth/login.md
```
）。
每个增量文件需使用ADDED/MODIFIED/REMOVED分区，并遵循标准格式：
- 使用
```
### Requirement: <name>
```
  标题和RFC 2119关键字（MUST/SHOULD/MAY）
- 必要时使用
```
#### Scenario:
```
  块（GIVEN/WHEN/THEN格式）
- ADDED: 新增的要求；MODIFIED: 修改后的要求（需包含
```
Previously:
```
  注释）；REMOVED: 移除的要求（需说明原因）
- 省略不适用的分区——不要保留空分区
- 如果本次变更对规范无可见影响，请创建一个文件并简要说明
填充tasks.md —— 撰写具体的实现检查清单：
- 使用
```
- [ ]
```
  复选框列出每个任务
- 任务应独立可完成
- 分为三个部分：
```
## 实现
```
  、
```
## 测试
```
  、
```
## 验证
```
- ```
## 测试
```
  部分必须包含至少与项目技术栈匹配的代码检查和单元测试任务（从config.yaml的context字段读取相关信息）
- 不要添加“更新规范”任务——specs/目录已包含规范工件
填充questions.md —— 记录所有未解决的问题或歧义：
- 对于每个不明确的点（动机、范围边界、技术实现思路等），在
```
## Open
```
  下添加条目：
```
- [ ] Q: <具体问题>
  Context: <该问题的重要性 / 哪些内容取决于答案>
```
- 如果所有内容都清晰明确，则
```
## Open
```
  部分留空并添加注释：
```

```
- 不要在任何工件中使用
```
[NEEDS CLARIFICATION]
```
  内联标记——questions.md是记录所有未解决问题的唯一位置
确认 —— 向用户展示生成的五个文件，并询问是否需要调整内容。如果
```
questions.md
```
中有未解决的问题，请逐一列出并要求用户在执行
```
/spec-driven-apply
```
前解决这些问题。

Rules

规则

Do not implement anything — this is planning only
Keep tasks atomic and verifiable
proposal.md describes what and why; design.md describes how; tasks.md is the checklist; questions.md is for open questions
Document ambiguities in questions.md — never guess at unclear requirements, and never use
```
[NEEDS CLARIFICATION]
```
inline markers

不要进行任何实现工作——此流程仅用于规划
保持任务的原子性和可验证性
proposal.md描述内容与动机；design.md描述实现方法；tasks.md是检查清单；questions.md用于记录未解决问题
在questions.md中记录歧义——切勿猜测不明确的要求，也不要使用
```
[NEEDS CLARIFICATION]
```
内联标记