| name | intent-changes |
| description | Manage structured change proposals for design documents with PR-like review experience. Use /intent-changes start <file> to begin, /intent-changes propose to suggest changes, /intent-changes accept/reject to decide, /intent-changes finalize to apply. |
Intent Changes
设计文档的结构化变更提案与协作 Review 工具。
核心概念
Change Proposal
每个变更是一个独立提案：
| 字段 | 说明 |
|---|
| ID | 唯一标识 (C001, C002...) |
| Type | ADD / MODIFY / REPLACE / DELETE |
| Status | PENDING / ACCEPTED / REJECTED |
| Target | 变更位置 |
| Before/After | 变更内容 |
| Decision | 决策记录 (reviewer, timestamp, comment) |
状态流
PENDING ──accept──> ACCEPTED ──finalize──> Applied
│
└──reject──> REJECTED
命令
| 命令 | 说明 |
|---|
/intent-changes start <file> | 启动或恢复 review |
/intent-changes propose | 提出变更建议 |
/intent-changes accept <id> | 接受变更 |
/intent-changes reject <id> | 拒绝变更 |
/intent-changes status | 查看当前状态 |
/intent-changes finalize | 交互式 apply |
工作流程
/intent-changes start <file>
↓
┌───────────────────┐
│ 检查 .reviews/ │
│ 有则恢复 │
│ 无则创建 │
└─────────┬─────────┘
↓
/intent-changes propose
↓
┌───────────────────────────────────────┐
│ 读取源文档 │
│ 与用户讨论变更内容 │
│ 生成 Change Proposal (C001, C002...) │
│ 写入 .reviews/{name}.review.md │
└─────────┬─────────────────────────────┘
↓
/intent-changes accept/reject
↓
┌───────────────────┐
│ 更新 status │
│ 记录 reviewer │
│ 记录 timestamp │
└─────────┬─────────┘
↓
/intent-changes finalize
↓
┌───────────────────────────────────────┐
│ 逐个显示 ACCEPTED 变更 │
│ 交互确认: Apply? [Y/n/view] │
│ Apply 到源文档 │
│ 生成变更摘要 │
└───────────────────────────────────────┘
执行步骤
命令: start
输入: 文件路径
步骤:
- 验证源文件存在
- 确定 review 文件路径:
.reviews/{basename}.review.md
- 如果 review 文件存在:
- 如果不存在:
- 创建
.reviews/ 目录（如不存在）
- 创建 review 文件，写入 frontmatter
- 设置当前 session 的 source 和 review 路径
输出:
Review session started.
Source: intent/specs/kind-system-spec.md
Review: .reviews/kind-system-spec.review.md
Status: 3 PENDING, 2 ACCEPTED, 1 REJECTED
Commands:
/intent-changes propose - 提出新变更
/intent-changes status - 查看详情
/intent-changes finalize - 应用变更
命令: propose
前置条件: 已执行 start
步骤:
- 读取源文档内容
- 读取当前 review 文件，获取已有提案
- 计算下一个 ID (如已有 C001-C005，下一个是 C006)
- 与用户讨论：
- 展示源文档结构
- 使用 AskUserQuestion 询问变更类型和位置
- 收集变更内容
- 生成 Change Proposal 块
- 追加到 review 文件
交互流程:
使用 AskUserQuestion:
- question: "你想对哪个部分提出变更？"
- header: "变更位置"
- options:
- "## Kind 定义" - 第一个 section
- "## Actions" - 第二个 section
- "## 示例" - 第三个 section
- "其他位置" - 手动指定
使用 AskUserQuestion:
- question: "变更类型是什么？"
- header: "变更类型"
- options:
- "ADD" - 新增内容
- "MODIFY" - 修改现有内容
- "REPLACE" - 替换整个 section
- "DELETE" - 删除内容
然后收集具体内容，生成提案。
命令: accept / reject
输入: 提案 ID，可选 comment/reason
语法:
/intent-changes accept C001
/intent-changes accept C001 --comment "LGTM"
/intent-changes reject C002 --reason "不同意这个改法"
步骤:
- 读取 review 文件
- 找到对应 ID 的提案
- 验证当前状态是 PENDING
- 更新状态为 ACCEPTED 或 REJECTED
- 添加 Decision 记录:
- reviewer: 从 git config user.name 或 $USER 获取
- timestamp: 当前日期
- comment: 用户提供的评论
- 写回 review 文件
Decision 格式:
**Decision:**
- ✓ @robmao (2026-01-21): "LGTM"
或拒绝时:
**Decision:**
- ✗ @robmao (2026-01-21): "不同意这个改法"
命令: status
输出详情:
Review: kind-system-spec.md
Source: intent/specs/kind-system-spec.md
Reviewers: @robmao, @claude
─────────────────────────────────
PENDING (2):
C002 [MODIFY] 修改 Kind 定义的措辞
C004 [ADD] 新增性能章节
ACCEPTED (3):
C001 [ADD] 新增 Action 分类说明
✓ @robmao (2026-01-21)
C003 [MODIFY] 调整示例代码
✓ @claude (2026-01-21)
C005 [DELETE] 删除过时章节
✓ @robmao (2026-01-21)
REJECTED (1):
C006 [REPLACE] 重写整个文档
✗ @robmao (2026-01-21): "改动太大"
─────────────────────────────────
Next: /intent-changes finalize (3 changes ready)
命令: finalize
前置条件: 至少有一个 ACCEPTED 的提案
步骤:
- 读取 review 文件，筛选 ACCEPTED 提案
- 按 Target 位置排序（从文档末尾往前，避免位置偏移）
- 对每个提案交互确认:
[1/3] C001 [ADD]: 新增 Action 分类说明
Target: After "## Actions"
Content to add:
┌────────────────────────────────────────┐
│ Actions 分为三类： │
│ - Inline: 同步执行，决定 commit 成功与否 │
│ - Deferred: 异步执行，失败不影响 commit │
│ - Observational: 只读，可以慢 │
└────────────────────────────────────────┘
Apply this change? [Y/n/view/quit]
用户选项:
Y (默认): Apply 并继续n: Skip 此变更（保持 ACCEPTED 状态但不 apply）view: 显示完整的 before/after diffquit: 中止 finalize
- Apply 变更到源文档
- 更新 review 文件:
- 已 apply 的标记为
[APPLIED]
- 更新 frontmatter status 为
finalized（如果全部处理完）
- 输出摘要
Apply 摘要:
Finalize complete.
Applied: 2
C001 - 新增 Action 分类说明
C003 - 调整示例代码
Skipped: 1
C005 - 删除过时章节 (user chose to skip)
Source updated: intent/specs/kind-system-spec.md
Review archived: .reviews/kind-system-spec.review.md
Review 文件格式
Frontmatter
---
source: intent/specs/kind-system-spec.md
created: 2026-01-21
reviewers:
- robmao
- claude
status: active
---
status 值:
active: 进行中finalized: 已完成 applyabandoned: 已放弃
Change Proposal 块
---
## C001 [ADD] [PENDING]
> 简短描述
**Target:** After "## Actions"
**After:**
```markdown
新增的内容...
C002 [MODIFY] [ACCEPTED]
简短描述
Target: Section "## Kind 定义"
Before:
原内容...
After:
新内容...
Reason: 变更理由
Decision:
- ✓ @robmao (2026-01-21): "LGTM"
## 获取 Reviewer 名称
按优先级:
1. 命令参数 `--reviewer`
2. `git config user.name`
3. 环境变量 `$USER`
```bash
# 获取方式
git config user.name || echo $USER
边界
做什么
- ✓ 结构化管理变更提案
- ✓ 追踪决策过程
- ✓ 支持多 reviewer 署名
- ✓ 交互式 apply
不做什么
- ✗ 格式校验 → intent-validate
- ✗ Section 审批 → intent-review
- ✗ 设计质量判断 → intent-critique
- ✗ 实现一致性 → intent-sync
与其他工具配合
intent-interview → 创建 Intent
↓
intent-critique → 质疑设计
↓
/intent-changes → 管理变更提案 ← 本 Skill
↓
intent-review → 锁定 sections
↓
intent-plan → 开始实现
示例
独立 Review
/intent-changes start intent/specs/tools-spec.md
/intent-changes propose
/intent-changes accept C001
/intent-changes reject C002 --reason "不需要"
/intent-changes finalize
协作 Review
/intent-changes start spec.md
/intent-changes propose
/intent-changes accept C001 --comment "Good"
/intent-changes reject C002 --reason "换个方式"
/intent-changes propose
/intent-changes accept C004
/intent-changes finalize
