change-writer

Skill: Change Writer

辅助填写变更提案——分析变更影响范围，生成结构化的 proposal.md 和按阶段拆解的 tasks.md，确保变更可追溯、影响可控。

触发条件

• 用户刚运行完 openlogos change <slug> 并希望 AI 帮忙填写提案
• 用户描述需要修改、新增或删除某个场景/功能
• 用户提到"变更提案"、"change proposal"、"迭代"、"改需求"

前置依赖

1. 项目已初始化（logos/logos.config.json 存在）
2. 变更提案目录已由 CLI 创建（logos/changes/<slug>/ 存在）
3. 主文档可读（logos/resources/ 中有已生效的文档）

如果前置条件不满足，提示用户先运行 openlogos change <slug> 创建提案目录。

核心能力

1. 理解用户描述的变更意图
2. 扫描 logos/resources/ 中的现有文档，定位受影响范围
3. 根据变更传播规则判断变更类型（需求级 / 设计级 / 接口级 / 代码级）
4. 生成符合规范的 proposal.md
5. 按变更类型自动拆解 tasks.md

执行步骤

Step 1: 理解变更意图

与用户确认以下信息（信息不足则追问，最多 2 轮）：

• 变更是什么：要新增、修改还是删除什么？
• 变更原因：为什么要做这个变更？来自需求反馈、Bug 还是优化？
• 关联场景：涉及哪些已有场景编号（S01, S02...）？

Step 2: 分析影响范围

扫描 logos/resources/ 中的文档，确定影响范围：

1. 读取需求文档（prd/1-product-requirements/），检查相关场景定义
2. 读取产品设计（prd/2-product-design/），检查相关功能规格和原型
3. 读取技术方案（prd/3-technical-plan/），检查相关时序图
4. 读取 API 文档（api/），检查相关端点
5. 读取 DB 文档（database/），检查相关表结构
6. 读取编排测试（scenario/），检查相关测试用例

Step 3: 判断变更类型

参照变更传播规则确定变更类型及最小更新范围：

变更类型	最少需要更新
需求级变更	全链路（需求 → 设计 → 架构 → API/DB → 编排 → 代码）
设计级变更	原型 + 场景 + API/DB + 编排 + 代码
接口级变更	API/DB + 编排 + 代码
代码级修复	代码 + 重新验收

Step 4: 生成 proposal.md

按以下模板生成，写入 logos/changes/<slug>/proposal.md：

# 变更提案：[变更名称]

## 变更原因
[为什么要做这个变更？来源于哪个需求/反馈/Bug？]

## 变更类型
[需求级 / 设计级 / 接口级 / 代码级]

## 变更范围
- 影响的需求文档：[列表，精确到文件名和章节]
- 影响的功能规格：[列表]
- 影响的业务场景：[场景编号列表]
- 影响的 API：[端点列表]
- 影响的 DB 表：[表名列表]
- 影响的编排测试：[列表]

## 变更概述
[用 1-3 段话概述具体改什么]

Step 5: 生成 tasks.md

根据变更类型和影响范围，自动拆解任务清单。只列出需要更新的阶段：

# 实现任务

## Phase 1: 文档变更
- [ ] 更新需求文档中 S0x 的验收条件
- [ ] 在场景总览表中新增/修改场景

## Phase 2: 设计变更
- [ ] 更新功能规格中 S0x 的交互设计
- [ ] 更新原型

## Phase 3: 技术变更
- [ ] 更新 S0x 的时序图
- [ ] 更新 API YAML
- [ ] **验证 API YAML** — `logos/resources/api/` 下所有文件必须为有效 YAML 且符合 OpenAPI 3.x 规范（所有包含 `:` 或特殊字符的 `description`/`summary` 值必须用双引号包裹）
- [ ] 更新 DB DDL
- [ ] 更新编排测试用例
- [ ] 实现代码变更

Step 6: 引导后续操作（链式驱动）

提供一条可直接执行的提示词，让用户一句话启动全部任务的链式执行：

• 需求级 / 设计级变更（多任务）：建议用户说「按 tasks.md 帮我逐步更新 S0x 的所有受影响文档」
• 代码级修复（少任务）：建议用户说「帮我修复 S0x 的 [问题描述] 并重新验收」

链式执行的行为规范：

1. AI 读取 tasks.md，按顺序逐项执行
2. 每完成一项任务，汇报修改摘要，并自动提示「继续下一项？」
3. 用户说「继续」或给出调整意见后，执行下一项
4. 全部任务完成后，提醒用户运行 openlogos merge <slug>

关键原则：不要让用户手动跟踪任务清单——AI 应主动驱动流程。

输出规范

• 文件格式：Markdown
• 存放位置：logos/changes/<slug>/
• 文件名：proposal.md 和 tasks.md（覆盖 CLI 生成的模板）

实践经验

• 宁可高估影响范围：漏掉一个环节的更新比多检查一遍更危险
• 变更类型决定工作量：帮助用户在动手前理解改一个需求可能需要全链路更新
• tasks.md 是执行清单：每完成一项打一个 [x]，方便追踪进度
• 小变更也走流程：看似"只改一行 API"的变更，可能影响编排测试和代码

推荐提示词

以下提示词可以直接复制给 AI 使用：

填写提案：

• 帮我填写变更提案 <slug>
• 我要给 S02 登录场景加一个记住密码功能，帮我分析影响范围
• 这个 Bug 修复只涉及代码层，帮我快速写个提案

执行任务（提案填写完成后）：

• 按 tasks.md 帮我逐步更新 S02 的所有受影响文档
• 帮我修复 S02 登录接口的 500 错误并重新验收