change-clarify

change-clarify

此技能的作用

审查待处理的 ChDR（状态为 Discovered 或 Proposed），并决定其最终状态：Accepted、Rejected 或 Deferred。

这是变更决策记录（Change Decision Records）的质量关卡，也是将从历史中推断出的决策提升为项目记忆并由 team-boot 注入后续会话之前的人为检查点：

• 验证推断出的决策是否有引用的提交 SHA / issue URL 支持（溯源能力——防止上下文投毒的断路器）
• 检查推断依据的置信度，并标记置信度较低或缺乏依据的主张
• 确认 issue 链接有效，且获取的 issue 摘要准确（而非逐字粘贴）
• 确保记录已观察到的后果（回滚/修复链）
• 更新 {REPO_ROOT}/.adlc/drafts/chdr/ChDR-{NNN}.md 中的 ChDR 状态
• 重新生成 {REPO_ROOT}/.adlc/drafts/chdr/chdr.md 索引

这是一条交互式命令。 每次交互恰好展示一个 ChDR，并等待用户输入。

使用时机

• 在 /change-init 之后：验证从历史中挖掘出的 ChDR，然后再将其提升
• 定期审查：清理过时的待处理 ChDR

不要使用的情况

• 没有待处理的 ChDR：如果没有状态为 Discovered/Proposed 的 ChDR，则无需澄清
• 审查 CDR：请使用 /team-levelup（CDR 和 ChDR 是不同类型的记录，审核流程也各自独立）
• 直接编辑：不要使用此技能绕过审查工作流

流程

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（如果非空）。

用户输入示例：

• "ChDR-001 ChDR-003" — 聚焦于指定的 ChDR
• "all" — 澄清所有待处理的 ChDR
• 空输入：澄清所有状态为“Discovered”或“Proposed”的 ChDR

标记

• --all：澄清所有待处理的 ChDR（等同于空输入）
• --limit N：限制每个会话最多澄清 N 个（默认：5）

角色与上下文

你将以变更验证者的身份审查从历史中推断出的决策。与 CDR 澄清（用于验证团队范围内的模式）不同，你的重点是证据保真度：

• 决策是否确实能从引用的提交中推断出来，还是由 Agent 凭空捏造？
• 置信度是否可信（如果一项高置信度主张仅依据简短的提交信息，且没有 issue 链接，就值得警惕）？
• issue 摘要是否准确，且没有逐字泄露敏感细节？
• 是否记录了实际存在的回滚/修复链（这是价值最高的内容）？

ChDR 质量检查清单

每个 ChDR 都应包含：

• ### Context，说明变更发生的原因（issue 摘要或提交信息）
• ### Decision，包含推断出的决策和置信度
• 每项决策主张都引用 SHA 或 issue URL（溯源能力——不可妥协）
• ### Consequences（回滚/修复链，或明确写明“未观察到”）
• ### Evidence，包含具体的 SHA、文件和 issue 链接
• issue 摘要经过转述，而非直接粘贴原文（安全要求）
• 状态准确

大纲

1. 加载待处理的 ChDR（阶段 1）：解析状态为 Discovered/Proposed 的 ChDR 文件
2. 预验证（阶段 2）：跳过缺少必需章节或决策主张缺乏溯源依据的 ChDR
3. 识别缺口（阶段 3）：列出需要澄清的事项
4. 依次澄清（阶段 4）：每次交互处理一个 ChDR
5. 更新 ChDR（阶段 5）：每次作出决定后，写入状态和澄清元数据
6. 重新生成索引（阶段 6）：更新 chdr.md
7. 总结（阶段 7）：呈现结果

执行步骤

阶段 1：加载待处理的 ChDR

运行设置脚本：

scripts/bash/setup-change-clarify.sh

读取所有 {REPO_ROOT}/.adlc/drafts/chdr/ChDR-*.md 文件并筛选：

• 包含：### Status: **Discovered** 或 ### Status: **Proposed**
• 跳过：### Status: **Accepted**、**Rejected**、**Published**、**Deprecated**

如果设置脚本不可用或运行失败，请手动确定：

1. REPO_ROOT — 从 cwd 向上查找 .adlc/，或运行 git rev-parse --show-toplevel。
2. CHDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/chdr
3. PENDING_COUNT — 统计状态为 Discovered/Proposed 的文件数量。

如果没有待处理的 ChDR：

No pending ChDRs found.
Run /change-init to mine git history first.

步骤 0：检测轻量草稿格式

检查正在审查的草稿是否使用轻量草稿模板（其特征是 frontmatter 中包含 type、evidence、source、revisit-when 字段，且正文包含 ## Rejected Alternatives / ## Reason 部分，但不包含完整的正式模板部分）。

如果是轻量格式：

1. 读取草稿中记录的字段（Context、Decision、Rejected Alternatives、Reason）
2. 转换为完整的正式模板：
   • ADR：完整的 MADR 格式，包含 Decision Drivers、Considered Options、Pros/Cons、Constitution Alignment、Related ADRs
   • PDR：完整的 PDR 格式，包含 Market Forces、Consequences、Alternatives Considered、Links
   • ChDR：完整的 ChDR 格式，包含 Issue Links、Commits、Consequences、Evidence
   • CDR：完整的 CDR 格式，包含 Context Type、Target Module、Descriptor、Evidence
   • EVAL：完整的 eval 格式，包含 Error Analysis、Pass/Fail Examples、Implementation Notes
3. 根据会话上下文补充内容（添加轻量草稿中可能遗漏的细节）
4. 呈现补充完善后的草稿以供审查

如果已经是完整格式，则按常规流程审查。

阶段 2：预验证

检查每份待处理 ChDR 是否包含必需部分：

• ### Context
• ### Decision（至少包含一个置信度标记）
• ### Consequences
• ### Evidence
• 来源信息：### Decision 中每个非平凡句子都必须引用 SHA（\b[0-9a-f]{7,40}\b）或 URL（https?://）

跳过无效的 ChDR 并报告：

## Skipped ChDRs

| ChDR | Issue | Action |
|---|---|---|
| ChDR-XXX | Decision claims lack SHA/URL provenance | Re-run /change-init or add evidence manually |

阶段 3：识别差距

生成差距报告：

## ChDR Clarification Report

| ChDR | Title | Gap Type | Severity |
|---|---|---|---|
| ChDR-001 | [Title] | Low-confidence decision | MEDIUM |
| ChDR-002 | [Title] | Issue summary too verbose | LOW |

差距类型：

• 低置信度决策：Decision 标记为 LOW confidence — 考虑拒绝或延后处理
• 缺少来源信息的声明：Decision 中有句子未包含 SHA/URL（应已在阶段 2 中发现）
• Issue 摘要过于冗长：逐字粘贴而非改写（安全问题）
• 缺少后果：观察时间段内发现了回退，但 Consequences 部分为空
• 过时：群组中的提交后来被回退（决策已被推翻 — 标记为拒绝或状态变更）

阶段 4：逐项澄清

重要：每次交互只呈现一份 ChDR。不得：

• 同时呈现多份 ChDR
• 自动选择操作
• 在用户明确输入前继续
• 一次提出多个问题

会话上限：每个会话默认处理 5 份 ChDR。用户可以说“done”提前退出。

对于每份 ChDR：

## ChDR-{ID}: {Title}

**Status**: {status}
**Issue Links**: {links or "none"}
**Commits**: {sha list}

### Current Content

**Context**:
{context}

**Decision** (confidence: {level}):
{decision}

**Consequences**:
{consequences}

**Evidence**:
{evidence}

### Choose Action

| Option | Action |
|---|---|
| A | **Accept** — Approve for promotion to memory |
| B | **Reject** — Decline with reason |
| C | **Defer** — Skip for now, keep pending |
| D | **Accept all remaining** — Accept this ChDR and all pending ChDRs without further review |

Reply with your choice (A/B/C/D).

等待用户输入后再继续。

操作 A：接受

将状态更新为 ### Status: **Accepted**。添加澄清元数据：

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Accepted
- **Rationale**: [summary of review]

操作 D：全部接受剩余项

接受当前 ChDR（操作 A），然后遍历剩余待处理的 ChDR，将每份的状态标记为 ### Status: **Accepted** 并添加批量处理元数据。跳过逐份呈现。继续执行阶段 6。

操作 B：拒绝

询问原因：

### Decision: Reject

| Option | Reason |
|---|---|
| A | Decision was reversed (later reverted) |
| B | Inferred rationale unsupported by evidence |
| C | Project-specific / not worth recording |
| D | Duplicate of an existing ChDR or ADR |

Reply with your choice.

将状态更新为 ### Status: **Rejected**，并附上原因。

操作 C：延后

保持状态不变。添加备注：

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Deferred
- **Reason**: [need more context / waiting on team / low priority]

阶段 5：更新 ChDR 文件

每次 ChDR 交互后立即更新文件。不要等到最后再批量更新。

阶段 6：重新生成索引

重新生成 {REPO_ROOT}/.adlc/drafts/chdr/chdr.md：列出所有 ChDR-*.md 文件，并根据单行字段（### Status:、### Date:、### Issue Links:、### Commits:、### Descriptor:）构建 Markdown 表格。

阶段 7：总结

## Change-Clarify Summary

**ChDRs Reviewed**: N
**Accepted**: N
**Rejected**: N
**Deferred**: N

### Accepted (Ready for Promotion)

| ChDR | Title |
|---|---|
| ChDR-001 | [Title] |

### Rejected

| ChDR | Reason |
|---|---|
| ChDR-003 | Decision was reversed (later reverted) |

### Deferred

| ChDR | Title |
|---|---|
| ChDR-004 | [Title] |

### Next Steps

1. **Accepted**: Run `/change-publish` to promote to `docs/adlc/memory/chdr/`
2. **Deferred**: will appear in next clarify session
3. **Remaining**: run `/change-clarify` again to continue

关键规则

逐个处理

• 每次回复只展示一个 ChDR
• 每次回复只提一个问题
• 等待用户输入后再继续

立即写入

• 每次做出决定后立即更新 ChDR 文件
• 会话结束后重新生成索引

不自动批准

• 未经用户明确选择，绝不接受或拒绝
• 不要假设用户的偏好

来源是把关条件

• 没有 SHA/URL 来源信息的决策声明存在投毒风险——拒绝该声明或要求提供证据后再接受
• 如果证据充分，可以接受低置信度的决策；高置信度但没有证据的决策则不行

工作流指导与转换

/change-clarify 之后

如果有任何 ChDR 已接受，则转交给 /change-publish：

{
  "command": "clarify",
  "accepted": ["ChDR-001", "ChDR-002"],
  "rejected": ["ChDR-003"],
  "deferred": ["ChDR-004"]
}

完成澄清流程

[Pending ChDRs exist]
    ↓
/change-clarify
    ↓
[One ChDR at a time] → Accept / Reject / Defer
    ↓
[Run /change-publish] → Promote accepted ChDRs to docs/adlc/memory/chdr/

后续步骤

接受 ChDR 后，运行 /change-publish，将其提升为项目记忆并重新生成面向启动的 chdr.md 索引。

验证

• 所有已审核的 ChDR 文件均已更新状态和澄清元数据。
• 已重新生成 chdr.md 草稿索引。
• 已接受的 ChDR 已准备好交由 /change-publish 处理。
• 没有 ChDR 在未经用户输入的情况下被自动接受或拒绝。
• 所有已接受 ChDR 的决策声明均有来源信息。

上下文

$ARGUMENTS