levelup-clarify

levelup-clarify

此技能的作用

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

这是对所有 team-ai-directives 贡献内容的质量把关：

• 验证模式是否适用于整个团队，而非特定项目
• 检查是否与现有的 team-ai-directives 重复
• 确保 CDR 包含明确的上下文、决策和证据
• 更新 {REPO_ROOT}/.adlc/drafts/cdr/CDR-{NNN}.md 中的 CDR 状态
• 重新生成 {REPO_ROOT}/.adlc/drafts/cdr/cdr.md 索引

这是一个交互式命令。 每次交互只展示一个 CDR，并等待用户输入。

使用时机

• 在 /levelup-init 之后：验证棕地项目的发现
• 在 /levelup-specify 之后：审查提出的功能相关经验
• 在 /team-repair 发现冲突之后：解决修复流程创建的冲突 CDR
• 定期审查：清理过期的待处理 CDR

不应使用的情况

• 没有待处理的 CDR：如果没有状态为 Discovered/Proposed 的 CDR，则无需澄清
• 直接编辑：不要使用此技能绕过审查流程
• 常规健康检查：使用 /team-repair 维护团队 AI 指令

流程

用户输入

$ARGUMENTS

如果用户输入不为空，继续操作前必须考虑该输入。

用户输入示例：

• "CDR-001 CDR-003" — 重点处理指定的 CDR
• "rules" — 仅澄清规则类型的 CDR
• "all" — 澄清所有待处理的 CDR
• 空输入：澄清所有状态为 "Discovered" 或 "Proposed" 的 CDR

标志

• --all：澄清所有待处理的 CDR（与空输入相同）
• --type TYPE：按上下文类型筛选（rules、personas、examples、skills、constitution、evals）
• --limit N：限制每个会话澄清的数量为 N（默认值：5）
• --no-evals-gate：禁用 evals 回归门禁（默认值：门禁已开启）

角色与上下文

你将以上下文验证者的身份审查发现的模式。你的职责包括：

• 验证模式是否仍然适用
• 澄清适用范围（整个团队还是特定项目）
• 检查是否与现有的 team-ai-directives 重叠
• 通过有针对性的问题完善 CDR 内容

CDR 质量检查清单

每个 CDR 都应包含：

• 清晰说明模式的上下文
• 明确的决策陈述
• 来自代码库或功能的证据
• 格式正确的目标模块路径
• 状态准确
• 与现有指令没有冲突
• 适用于整个团队
• 已分类可强制执行性：机械式（确定性检查）还是判断式（上下文规则）

大纲

1. 加载待处理的 CDR（阶段 1）：解析状态为 Discovered/Proposed 的 CDR 文件
2. 预验证（阶段 2）：跳过缺少必需章节的 CDR
3. Evals 回归门禁（阶段 2a）：接受前运行现有 goldensets（默认开启）
4. 可强制执行性门禁（阶段 2b）：在提供 Accept 选项前，分类为机械式或判断式
5. 识别差距（阶段 3）：列出需要澄清的内容
6. 依次澄清（阶段 4）：每次交互处理一个 CDR
7. 更新 CDR（阶段 5）：每次决策后写入状态和澄清元数据
8. 重新生成索引（阶段 6）：更新 cdr.md
9. 总结（阶段 7）：展示结果

执行步骤

阶段 1：加载待处理的 CDR

运行设置脚本：

scripts/bash/setup-levelup-clarify.sh

读取所有 {REPO_ROOT}/.adlc/drafts/cdr/CDR-*.md 文件并进行筛选：

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

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

1. REPO_ROOT — 从 cwd 向上查找 .adlc/，或运行 git rev-parse --show-toplevel。
2. CDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/cdr
3. PENDING_COUNT — grep -l '^### Status: \*\*(Discovered|Proposed)\*\*' CDR_DRAFTS_DIR/CDR-*.md | wc -l

如果用户指定了特定的 CDR ID 或类型，请据此筛选。

如果没有待处理的 CDR：

No pending CDRs found.
Run /levelup-init or /levelup-specify to create CDRs 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 阶段：预验证

对于每个待处理的 CDR，检查必需章节：

• ### Context
• ### Decision
• ### Evidence
• ### Target Module

跳过无效的 CDR 并报告：

## Skipped CDRs

| CDR | Issue | Action |
|---|---|---|
| CDR-XXX | Missing Evidence | Add evidence and re-run clarify |

第 2a 阶段：Evals 回归门禁

默认：开启。 使用 --no-evals-gate 禁用。

审查 eval CDR 或有配对 eval 的指令 CDR 时，运行 team-ai-directives/evals/ 中现有的 goldenset，检查接受此 CDR 是否会破坏现有的指令合规性测试。

对于 eval CDR：验证 eval 质量：

• 每个案例都有具体的证据引用（会话描述或代码文件:行号）
• 通过/失败结果是二元的（不存在模糊案例）
• eval CDR 引用了配对的指令 CDR
• 失败案例有修正方案（本应采取的做法）

对于有配对 eval 的指令 CDR：运行回归检查：

1. 从 {TEAM_AI_DIRECTIVES}/evals/ 读取现有的 goldenset
2. 如果没有现有的 goldenset → 跳过门禁（不可能发生回归）
3. 如果存在针对同一指令领域的 goldenset：
   • 通过 LLM 调用，让 Agent 对照现有 goldenset 案例运行测试
   • 如果接受此 CDR 会修改指令，检查现有 eval 案例是否仍能通过
   • 如果新指令会导致现有 eval 失败 → 将 CDR 标记为 Blocked (Evals)

被阻止的 CDR 保持待处理状态，并附上备注：

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Blocked (Evals)
- **Reason**: Accepting this CDR would break N existing goldenset cases in evals/{directive-id}/

报告：

## Evals Regression Gate

| CDR | Gate Result | Details |
|---|---|---|
| CDR-001 | PASS | No existing goldensets in scope |
| CDR-002 | BLOCKED | 3 existing cases would fail with modified rule |

第 2b 阶段：可执行性门禁

默认：开启。 对每个待处理的规则类型 CDR，在提供接受选项之前，先对其可执行性分类——优先使用确定性检查（EVAL-010）：

分类	示例	首要操作
机械式（固定模式）	禁用的 API、导入格式、文件位置规则、固定语法模式	确定性检查——单元测试、二进制评分器、提交前钩子、lint 规则或 CI 任务。投入一次即可；通过上下文规则，每个未来会话都得重新推导同一个结论
需判断	跨文件一致性、“符合周围的风格”、任何需要理解意图的内容	照常使用上下文规则（CDR）

默认做法：优先构建检查，而非编写规则。 机械式规则 CDR 首先以操作 P — Promote to check 的形式呈现（第 4 阶段）。为了便于发现，可以在检查旁附上简短的指引 CDR；但仅用 CDR 修复机械式规则不可接受。

非规则类型的 CDR（角色设定、示例、宪章）跳过此门禁。

第 3 阶段：识别差距

生成差距报告：

## CDR Clarification Report

| CDR | Title | Gap Type | Severity |
|---|---|---|---|
| CDR-001 | [Title] | Missing scope | HIGH |
| CDR-002 | [Title] | Duplicate check | MEDIUM |

差距类型：

• 缺少范围：团队通用还是特定于项目，尚不明确
• 有效性不明确：模式状态未知
• 需要重复检查：可能与现有指令重叠
• 内容不完整：缺少上下文/决策/证据
• 目标模块不明确：需要澄清模块路径

阶段 4：逐项澄清

至关重要：每次交互只展示一个 CDR。请勿：

• 一起展示多个 CDR
• 自动选择操作
• 在未获得用户明确输入的情况下继续
• 一次提问超过一个问题

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

对于每个 CDR：

## CDR-{ID}: {Title}

**Context Type**: {type}
**Target Module**: {target}
**Current Status**: {status}

### Current Content

**Context**:
{context}

**Decision**:
{decision}

**Evidence**:
{evidence}

### Choose Action

| Option | Action |
|---|---|
| A | **Accept** — Approve for implementation |
| B | **Reject** — Decline with reason |
| C | **Defer** — Skip for now, keep pending |
| D | **Accept all remaining** — Accept this CDR and all pending CDRs without further review |
| P | **Promote to check** *(mechanical rules only)* — Build the deterministic check (unit test / grader / pre-commit / lint / CI); CDR kept as thin pointer or rejected as superseded |

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

等待用户输入后再继续。

操作 P：提升为检查（仅适用于机械规则）

对于在阶段 2b 中归类为机械规则的 CDR：

1. 提出确定性检查（单元测试、遵循仓库评估规范的二进制评分器、pre-commit hook、lint 规则或 CI 作业），并说明确切的强制执行行为
2. 获得批准后：构建该检查，并验证不满足该规则约束时检查会失败，满足时检查会通过
3. 更新 CDR：将其标记为已拒绝，并填写原因“可通过机械方式强制执行 — 已提升为确定性检查”（首选）；或者将其保留为简要指引（Decision: enforced by <check path>; see it before editing）——由用户选择
4. 添加记录此次提升的澄清元数据

操作 A：接受

将 CDR 的状态行从 ### Status: **Proposed**（或 **Discovered**）更新为 ### Status: **Accepted**。添加澄清元数据：

### Clarification

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

操作 D：接受所有剩余项

将当前 CDR 更新为已接受（与操作 A 相同）。然后逐一处理所有剩余的待处理 CDR，将每个 CDR 标记为 ### Status: **Accepted**，并添加澄清元数据：

### Clarification

- **Date**: [YYYY-MM-DD]
- **Action**: Accepted (bulk)
- **Rationale**: Bulk-accepted with user approval during clarify session

跳过剩余 CDR 的逐项展示。直接进入阶段 6（重新生成索引）和阶段 7（摘要）。

操作 B：拒绝

询问拒绝原因：

### Decision: Reject

| Option | Reason |
|---|---|
| A | Project-specific |
| B | Duplicate of existing directive |
| C | Deprecated/outdated pattern |
| D | Low value |
| E | Mechanically enforceable — promoted to deterministic check |

Reply with your choice.

将 CDR 的状态行更新为 ### Status: **Rejected**，并填写原因。

操作 C：暂缓

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

### Clarification

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

阶段 5：更新 CDR 文件

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

阶段 6：重新生成索引

通过列出所有 CDR-*.md 文件并创建 Markdown 表格，重新生成 {REPO_ROOT}/.adlc/drafts/cdr/cdr.md。对于每个 CDR，提取单行字段（### Target Module:、### Context Type:、### Status:、### Date:、### Descriptor:），并据此创建索引表。完整格式请参阅 /levelup-specify 阶段 5。

阶段 7：摘要

## LevelUp Clarify Summary

**CDRs Reviewed**: N
**Accepted**: N
**Rejected**: N
**Deferred**: N

### Accepted (Ready for Implementation)

| CDR | Target Module | Type |
|---|---|---|
| CDR-001 | rules/python/error-handling | Rule |

### Rejected

| CDR | Reason |
|---|---|
| CDR-003 | Project-specific |

### Deferred

| CDR | Title |
|---|---|
| CDR-004 | [Title] |

### Next Steps

1. **Accepted**: Run `/levelup-publish`
2. **Deferred**: Will appear in next clarify session
3. **Remaining**: Run `/levelup-clarify` again to continue

关键规则

逐项处理

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

立即写入

• 每次作出决定后更新 CDR 文件
• 会话结束后重新生成索引

不得自动批准

• 未经用户明确选择，绝不接受或拒绝
• 不要擅自推断用户偏好

会话限制

• 默认限制：每个会话处理 5 个 CDR
• 如果提供了 --limit N，遵循该限制
• 用户可以说“done”提前退出

工作流指导与衔接

/levelup-clarify 之后

如果有任何 CDR 被接受，则转交给 /levelup-publish：

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

完成澄清流程

[Pending CDRs exist]
    ↓
/levelup-clarify
    ↓
[One CDR at a time] → Accept / Reject / Defer
    ↓
[Run /levelup-publish] → Compile accepted CDRs

后续步骤

接受 CDR 后，运行 /levelup-publish，将其编译为 team-ai-directives PR。

验证

• 所有已审查的 CDR 文件都已更新状态和澄清元数据。
• 已重新生成 cdr.md 索引。
• 已接受的 CDR 已准备好交由 /levelup-publish 处理。
• 没有未经用户输入就自动接受或拒绝任何 CDR。

上下文

$ARGUMENTS