openspec-proposal-creation-cn

Spec Proposal Creation

Follow the spec-driven development approach to generate a complete change proposal.

Quick Start

Creating a spec proposal includes three types of output:

1. proposal.md - Why, what, and impact summary
2. tasks.json - Numbered implementation checklist
3. spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)

Basic Process: Generate change ID → scaffold directory → draft proposal → write spec deltas → validate structure

Workflow

Copy this checklist and track progress:

规划进度:
- [ ] 第 1 步：审阅现有规范
- [ ] 第 2 步：生成唯一的变更 ID
- [ ] 第 3 步：生成目录结构
- [ ] 第 4 步：起草 proposal.md（为什么、做什么、影响摘要）
- [ ] 第 5 步：创建 tasks.json 实施清单
- [ ] 第 6 步：编写 spec-delta.md 规范差异（ADDED/MODIFIED/REMOVED）
- [ ] 第 7 步：验证提案结构
- [ ] 第 8 步：向用户展示并请求审批

Step 1: Review Existing Specs

Before creating a proposal, understand the current state:

# 列出所有现有规范
find spec/specs -name "spec.md" -type f

# 列出进行中的变更以避免冲突
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

# 搜索相关需求
grep -r "### Requirement:" spec/specs/

Step 2: Generate a Unique Change ID

Choose a descriptive, URL-safe identifier:

Format：add-<feature>、fix-<issue>、update-<component>、remove-<feature>

Example：

• add-user-authentication
• fix-payment-validation
• update-api-rate-limits
• remove-legacy-endpoints

Validation: Check for conflicts:

ls spec/changes/ | grep -i "<proposed-id>"

Step 3: Generate the Directory Structure

Create the change directory according to the standard structure:

# 将 {change-id} 替换为实际 ID
mkdir -p spec/changes/{change-id}/specs/{capability-name}

Example：

mkdir -p spec/changes/add-user-auth/specs/authentication

Step 4: Draft proposal.md

Start with templates/proposal.md .

Required Sections：

• Why: The problem or opportunity driving the change
• What Changes: List of modifications
• Impact: Affected specs, code, APIs, users

Tone: Clear, concise, decision-oriented. Avoid unnecessary background.

Step 5: Create the tasks.json Implementation Checklist

Break the implementation into concrete, testable tasks. Use the templates/tasks.json。

Format：

# 实施任务
```json
[
  {
    "number": 1,
    "category": "阶段 1：基础设施",
    "task": "环境搭建任务 - 数据库架构、依赖等",
    "steps": [
      { "step": "初始化 Git 仓库并配置 .gitignore", "completed": false },
      { "step": "创建并激活 Python 虚拟环境", "completed": false },
      { "step": "创建 requirements.txt 或 pyproject.toml 并安装依赖 (FastAPI, SQLAlchemy, Pydantic, Alembic 等)", "completed": false },
      { "step": "设计初始数据库 ER 图", "completed": false },
      { "step": "配置数据库连接字符串和环境变量 (.env)", "completed": false },
      { "step": "初始化 Alembic 迁移环境", "completed": false }
    ],
    "passes": false
  }
]


**最佳实践**：
- 每个任务可独立完成
- 为每个主要组件添加测试任务
- 为每个主要组件添加测试任务
- 包含测试与验证任务
- 按依赖排序（数据库先于 API 等）
- 通常 5-15 个任务；更多时应拆分
- 每次仅处理1个step

Step 6: Write Spec Deltas in EARS Format

This is the most critical step. Spec deltas use the EARS format(Easy Approach to Requirements Syntax).

Full EARS GuideSee reference/EARS_FORMAT.md

Delta Operations：

• ## ADDED Requirements - New capability
• ## MODIFIED Requirements - Behavior change (including the full updated text)
• ## REMOVED Requirements - Deprecated feature

Basic Requirement Structure：

## ADDED Requirements

### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。

#### Scenario: 登录成功
GIVEN 用户邮箱为 "user@example.com" 且密码为 "correct123"
WHEN 用户提交登录表单
THEN 系统创建已认证会话
AND 重定向至仪表盘

Patterns for ValidationSee reference/VALIDATION_PATTERNS.md

Step 7: Validate the Proposal Structure

Run the following checks before presenting to the user:

结构清单：
- [ ] 目录存在：`spec/changes/{change-id}/`
- [ ] proposal.md 包含 Why/What/Impact
- [ ] tasks.json 含编号任务列表（5-15 项）
- [ ] 规范差异包含操作标题（ADDED/MODIFIED/REMOVED）
- [ ] 需求遵循 `### Requirement: <name>` 格式
- [ ] 场景使用 `#### Scenario:` 格式（四个井号）

Automated Checks：

# 统计差异操作（应 > 0）
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

# 验证场景格式（显示行号）
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

# 检查需求标题
grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

Step 8: Submit for User Review

Clearly summarize the proposal:

## Proposal Summary

**Change ID**：{change-id}
**Scope**：{简要描述}

**创建的文件**：
- spec/changes/{change-id}/proposal.md
- spec/changes/{change-id}/tasks.json
- spec/changes/{change-id}/specs/{capability}/spec-delta.md

**下一步**：
请评审提案。如认可或修正后，请回复 "openspec开发" 或 "按顺序完成任务" 开始实施。

Advanced Topics

EARS Format Details: See reference/EARS_FORMAT.md Validation Patterns: See reference/VALIDATION_PATTERNS.md Full Example: See reference/EXAMPLES.md

Common Patterns

Pattern 1: New Feature Proposal

When adding a new capability:

• Use the ADDED Requirements delta
• Include both positive scenarios and error handling
• Consider edge cases in scenarios

Pattern 2: Breaking Change Proposal

When modifying existing behavior:

• Use the MODIFIED Requirements delta
• Include the full updated requirement text
• Explain the changes and reasons in proposal.md
• Consider migration tasks in tasks.json

Pattern 3: Deprecation Proposal

When removing functionality:

• Use the REMOVED Requirements diff
• Document the removal rationale in proposal.md
• Include cleanup tasks in tasks.json
• Consider user migration in the impact section

Anti-Pattern Avoidance

Don't：

• Skip validation checks (be sure to run the grep pattern)
• Create a proposal without first reviewing existing specs
• Use vague task descriptions (such as "fix it")
• Write requirements without scenarios
• Ignore error-handling scenarios
• Mix multiple unrelated changes in one proposal

Do：

• Check for conflicts before creating a change ID
• Write specific, testable tasks
• Include both positive and negative scenarios
• Address only one concern per proposal
• Validate the structure before presenting

File Templates

All templates are located in the templates/ directory:

• proposal.md - Proposal structure
• tasks.json - Task list format
• spec-delta.md - Spec diff template

References

• EARS_FORMAT.md - Full EARS syntax guide
• VALIDATION_PATTERNS.md - Grep/bash validation
• EXAMPLES.md - Real proposal examples

---

Token Budget: This SKILL.md is about 250 lines, below the recommended 500-line limit. Referenced files are loaded on demand to present them progressively.