| name | agf-writing-change |
| description | Use when product-lead is about to formalize a feature into a change folder (the OpenSpec-style intake that replaces PRD as of v6.9.0). Provides the four-artifact structure (proposal / delta specs / design / tasks), the Requirement+Scenario delta format (ADDED/MODIFIED/REMOVED/RENAMED), the AC↔scenario mapping that keeps the AGF verification spine intact, the validate gate, and the archive-merge hand-off. Replaces agf-writing-prd (deprecated). |
Writing a Change（变更文件夹入口）
变更文件夹（docs/changes/<change>/）是 AGF 自 v6.9.0 起的新需求入口，取代 PRD（OpenSpec 风格，决策见 ADR-012）。它把需求表达成对活规格的 delta，交付签字后 merge 进 docs/specs/——让「系统当前有哪些行为」永远有 SSOT。
Use this skill when：
- product-lead 跑完
superpowers:brainstorming 且用户批准了大方向。
- 要把一个 feature 正式化成
docs/changes/<change>/ 四件套，再派工。
- 既有 change 在 open question 解决后更新。
验证脊柱不变：apply 之后的 SIT 自跑 / code review + SIT Audit / 部署门 / E2E / UAT pass² / 业务签字全照旧。本 skill 只管入口。
Pre-conditions
任一不满足：停，别建 change，回 brainstorming 或 SendMessage 用户澄清。
建一个 change
cp -r docs/changes/_TEMPLATE docs/changes/<change-kebab-case>
<change> 用 kebab-case 动词短语（如 add-dark-mode、oauth-login）。一个 change 一个文件夹。
四件套
1. proposal.md —— why + what + scope
- Why：用户痛点 / 业务驱动（1–3 段）。
- What：本次交付的能力一句话；Non-Goals 至少 1 项。
- 影响的能力表：列触及的 capability + 对应活规格路径 + 本次 delta 文件（新建能力标 NEW）。
- Open Questions：每条标 Owner + Due（缺则不进派工）。
- 顶部填 effort tier（Small/Medium/Large）+ 交付 lane（full/fast；高风险一律 full）。
2. specs/<capability>.md —— delta（唯一会 merge 进活规格的部分）
对每个触及的能力写一个 delta 文件（文件名 = capability kebab-case）。段头只保留用到的：
## ADDED Requirements
### Requirement: <新行为名>
The system MUST <规范性契约>.
#### Scenario: <名>
- WHEN <触发>
- THEN <可观察结果>
## MODIFIED Requirements
### Requirement: <既有行为名> # header 须与活规格精确匹配（whitespace-insensitive）
The system MUST <改后的完整行为>. # 整块复制活规格里的 requirement+scenario 再改
#### Scenario: <名>
- WHEN ...
- THEN ...
## REMOVED Requirements
### Requirement: <被删行为名>
**Reason**: <为什么删>
**Migration**: <调用方/用户怎么迁移>
## RENAMED Requirements
- FROM: `### Requirement: <旧名>`
- TO: `### Requirement: <新名>`
铁律：每个 ### Requirement:（ADDED/MODIFIED）下至少 1 个 #### Scenario:（恰好 4 个 #）；Requirement 用 MUST/SHALL；REMOVED 必带 Reason+Migration。
3. design.md —— 单 change 技术「怎么做」（薄，可省）
简单 change 删掉本文件即可。高风险 change（auth / schema 迁移 / LLM 切换 / cross-cutting）引用一个新 ADR（tech-lead 写），不在 design.md 自拍架构。API 契约 SSOT 仍是 OpenAPI（ADR-006）。
4. tasks.md —— 实现 checklist + AC↔scenario 映射
关键：维护 AC-N ↔ <capability> / Requirement / Scenario 映射表。AC 仍是 AC-N（编号 / 优先级 / progress 5 段格式 / SIT hook 全不变，ADR-012 决策 4），语义来源是 delta 的 scenario——dev 逐 AC 自验、qa 逐 AC 测、PL 逐 AC 签字，照旧。
写 delta 前：消歧自检（借鉴 Spec Kit /clarify）
brainstorming 探索完、动笔写 delta 前，按这张 taxonomy 核一遍关键维度有没有遗漏（避免"写完才发现没问清"）；有 Partial / Missing 的回去 SendMessage 用户澄清：
| 维度 | 自检 |
|---|
| Scope / 边界 | 本次做什么、明确不做什么（Non-Goals）清楚？ |
| 数据 / 实体 | 关键实体 / 字段 / 约束 / 生命周期定义了？ |
| UX / 流程 | 用户主路径 + 关键分支（含失败 / 空态）覆盖？ |
| 非功能 | 性能 / 并发 / 配额 / 安全 / 合规有要求吗？有则量化（别写"快"/"高效"，写阈值） |
| 集成 / 依赖 | 触及哪些既有能力 / 外部服务 / 契约？ |
| 边界 / 异常 | 错误 / 超时 / 越权 / 并发冲突等 edge case 想过？ |
| 术语 | 与活规格既有术语一致（无同义漂移）？ |
每个有内容的维度落进对应 delta 的 Requirement / Scenario；与本 change 无关的维度跳过即可，不强凑。
validate（对齐前自检）
bash .claude/scripts/agf-spec-validate.sh docs/changes/<change>/specs/*.md
advisory（不阻断）；修掉 flag 省一轮 review 打回。code-reviewer 在 review 时也会跑。
完成前的验证
任一不行 → 不要派工，回去补。
Hand-off
- 对齐门：SendMessage 用户审
proposal.md + specs/ delta，批准后才派工（写码前对齐）。
TaskCreate 建 Agent Teams task（按 product-lead Step 2 的 6 段 schema，引用 tasks.md）。- SendMessage 执行层："change 已就绪 docs/changes//，请在 Plan Mode 报告里 cite AC 编号"。
- 如有 UI → SendMessage uiux-designer 起稿。
归档（UAT 业务签字后，PL 执行）
bash .claude/scripts/agf-spec-archive.sh <change> <YYYY-MM-DD> --dry-run
bash .claude/scripts/agf-spec-archive.sh <change> <YYYY-MM-DD>
按 RENAMED→REMOVED→MODIFIED→ADDED 把 delta merge 进 docs/specs/<cap>/spec.md，change 移 docs/changes/archive/<date>-<change>/。脚本 pre-flight 门控：名称失配 / 重名 Requirement 等异常 → 非零退出、不写不归档（确认有意则 --force 放行）。与 archive-progress.sh（归档 progress）各跑各的。
同一 capability 同时只允许一个在途 change（防并行 change 归档时后者覆盖前者已合并行为的 lost-update）。多个在途 change 触及同一能力时，PL 串行归档、后者基于前者已 merge 的活规格重写 delta。
反模式
- ❌ delta 写实现细节（SQL 字段长度等）——Requirement 是行为契约，不是代码方案。
- ❌ Requirement 无 Scenario / 用「应该」弱断言 / 不用 MUST。
- ❌ 直接手改
docs/specs/ 活规格做功能变更——一律走 delta + archive-merge。
- ❌ 不列 Non-Goals / Open Questions 留空无 owner。
- ❌ 高风险 change 在 design.md 自拍架构而不开 ADR。
