| name | openspec-reverse-update-spec |
| description | 根据代码变更反向更新 OpenSpec 四个工件（proposal/design/specs/tasks）。当用户说"反向更新spec"、"反向更新工件"、"我自己修改了代码，更新下spec文档"时使用此技能。支持无输入（分析 Git 变更）或指定文件路径。输出更新建议后必须询问用户确认再执行更新。 |
| metadata | {"author":"Kinney Yan","version":"1.0"} |
Reverse Spec Update
根据代码变更或指定文件反向更新 OpenSpec 四个工件（artifacts）。
Usage
/openspec-reverse-update-spec
/openspec-reverse-update-spec src/components/checkout-form.tsx
/openspec-reverse-update-spec src/api/payment.ts src/components/checkout-form.tsx
Workflow
Copy this checklist and check off items as you complete them:
- [ ] Step 1: 获取 OpenSpec 概念定义
- [ ] Step 2: 确定分析范围
- [ ] Step 3: 定位对应的 Change
- [ ] Step 4: 分析代码变更
- [ ] Step 5: 评估四个工件的更新需求
- [ ] Step 6: 输出更新建议
- [ ] Step 7: 询问用户并执行更新
Step 1: 校验 OpenSpec 概念理解
在开始分析前，必须校验自己对 OpenSpec 四个工件（artifacts）最新定义的理解：
curl -m 10 -s https://raw.githubusercontent.com/Fission-AI/OpenSpec/refs/heads/main/docs/concepts.md
理解核心流转逻辑：Proposal (Why) -> Specs (What) -> Design (How) -> Tasks (Steps)。
Step 2: 确定分析范围
Step 3: 定位对应的 Change
在 openspec/changes/ 目录下（优先搜索活跃目录，次选 openspec/changes/archive/ 归档目录）寻找与代码变更最匹配的 Change：
- 查看 change 的 proposal.md - 理解其意图 (Why) 和范围 (Scope)。
- 查看 change 的 design.md - 了解其原定技术方案 (How)。
- 匹配代码变更 - 通过文件路径、功能描述和模块域名匹配当前变更所属的 Change。
匹配标准：
- 代码修改的文件路径与
design.md 中 "File Changes" 列表匹配。
- 实现的功能逻辑与
proposal.md 描述的意图一致。
- 变更模块与
specs/ 下的目录结构对应。
注意
- 若匹配到已归档的 Change，仍应基于该 Change 的工件进行反向更新建议。
- 若未匹配到任何 Change，告知用户并结束工作流。
Step 4: 分析代码变更
对每个变更的文件，分析：
- 新增文件 - 实现了什么新功能/组件
- 修改文件 - 改变了什么行为/逻辑
- 删除文件 - 移除了什么功能
分析维度：
- 行为变化：对外可见的输入/输出/错误处理是否改变
- 架构变化：是否有新的模块/组件/数据流
- 配置变化：是否有新的配置项/环境变量
Step 5: 评估四个工件的更新需求
基于 Step 1 的核心原则，分析代码变更（Diff）并决定更新内容：
1. 决策矩阵
| 工件 | 更新触发条件 (基于代码实际实现) | 核心操作 |
|---|
| Proposal | 实际实现范围(Scope)或方法(Approach)与原计划有显著偏离 | 修正 Intent/Scope/Approach |
| Specs | 引入了新行为、修改了现有逻辑或删除了功能 | 按 Delta 格式 编写需求 |
| Design | 实际选用的技术方案、架构决策或文件路径与原设计不符 | 更新技术方案及 File Changes 列表 |
| Tasks | 任务已完成、发现遗漏步骤或顺序调整 | 勾选 [x] 或增删任务项 |
2. Specs 更新规范 (Delta 格式)
必须使用 ADDED/MODIFIED/REMOVED 结构描述行为变化，严禁记录内部实现细节：
## [ADDED/MODIFIED/REMOVED] Requirements
### Requirement: [名称]
[描述变更内容。如果是 MODIFIED，需注明 (Previously: ...)]
#### Scenario: [场景名]
- GIVEN...
- WHEN...
- THEN...
3. Design & Tasks 补充要点
- Design: 务必同步
design.md 中的 File Changes 列表，反映实际新增、修改和删除的文件路径。
- Tasks: 保持
tasks.md 的层级编号格式（如 1.1, 1.2），确保所有已完成的步骤均标记为 [x]。
Step 6: 输出更新建议
以结构化格式输出：
## 分析结果
**匹配的 Change**: `openspec/changes/[change-name]/` or `openspec/changes/archive/[change-name]/`
### 需要更新的工件
| 工件 | 是否需要更新 | 修改摘要 |
| ----------- | ------------ | ---------- |
| proposal.md | ✅/❌ | [简要说明] |
| specs/ | ✅/❌ | [简要说明] |
| design.md | ✅/❌ | [简要说明] |
| tasks.md | ✅/❌ | [简要说明] |
### 详细修改建议
#### proposal.md
[具体修改内容或"无需修改"]
#### specs/[domain]/spec.md
[具体的 delta spec 内容]
#### design.md
[具体修改内容]
#### tasks.md
[具体修改内容]
Step 7: 询问用户并执行更新
输出分析结果后，若没有需要更新的工件，则结束工作流。否则必须询问用户："以上是代码变更对应的工件更新建议。是否需要我现在帮您更新这些文件？"，选项：1. 是、2. 否、3. 指定只更新某些工件（如"只更新 specs"）
用户同意后，执行更新：
- 读取现有文件（如果存在）
- 应用修改建议 - 更新文件
- 确认更新完成 - 列出已更新的文件路径
更新原则：
- 保留文件中与变更无关的内容
- 使用 delta 格式更新 specs
- tasks.md 保持层级编号格式
- 如果文件不存在，创建新文件
注意事项
- 行为优先：Specs 只记录外部可见的行为变化，不包含内部实现细节。
- 轻量级：大多数变更使用 Lite spec 模式，只有高风险变更需要完整 spec。
- Delta 格式：Specs 必须使用 ADDED/MODIFIED/REMOVED 三段式 delta 格式。
- 保持同步：四个工件之间要保持一致性，不能相互矛盾。
- 存量优先 (Brownfield-first)：理解代码是在现有系统上的增量修改。Delta Spec 必须反映这种“增量行为变化”，而非重新描述整个系统的原始逻辑。
示例
示例 1：无输入，分析 Git 变更
用户输入：
反向更新四个工件
你的操作：
- 获取 OpenSpec 概念文档
- 运行
git diff HEAD 获取所有变更
- 遍历
openspec/changes/ 找到匹配的 change
- 分析代码变更
- 输出四个工件的更新建议
- 询问用户是否执行更新
- 用户确认后，更新对应文件
示例 2：指定文件路径
用户输入：
我自己修改了代码，更新下 spec 文档 src/auth/login.ts src/components/AuthForm.tsx
你的操作：
- 获取 OpenSpec 概念文档
- 读取用户指定的文件
- 定位到
openspec/changes/ 中与 auth 相关的 change
- 分析代码变更
- 输出四个工件的更新建议
- 询问用户是否执行更新
- 用户确认后，更新对应文件
示例 3：用户只更新部分工件
用户：
反向更新spec
你：（输出分析结果）
以上是代码变更对应的工件更新建议。是否需要我现在帮您更新这些文件？
- 输入 "是"/"yes"/"更新" 开始更新
- 输入 "否"/"no" 仅保留建议
- 或者指定只更新某些工件（如"只更新 specs"）
用户：
只更新 specs
你：仅更新 openspec/changes/[change-name]/specs/ 下的 delta spec 文件
