levelup-clarify 是一个交互式命令技能,用于审查待处理的 CDR(状态为 Discovered 或 Proposed),并决定其最终状态:Accepted、Rejected 或 Deferred。它是所有提交到 team-ai-directives 的贡献的质量门,负责验证模式是团队级而非项目专属、对照现有 team-ai-directives 检查重复、确保 CDR 具有清晰的上下文、决策与证据,然后更新 {REPO_ROOT}/.adlc/drafts/cdr/CDR-{NNN}.md 中的状态,并重新生成 {REPO_ROOT}/.adlc/drafts/cdr/cdr.md 索引。
用途与使用时机
该技能可在以下情况使用:/levelup-init 之后验证棕地发现;/levelup-specify 之后审查提出的功能学习;/team-repair 发现冲突后解决由修复创建的冲突 CDR;以及定期审查以清理滞留的待处理 CDR。在以下情况不应使用:没有待处理 CDR(若没有状态为 Discovered/Proposed 的 CDR,则无可澄清项);直接编辑(不要用此技能绕过审查工作流);常规健康检查(应使用 /team-repair 进行团队 AI 指令维护)。
主要能力
技能加载待处理 CDR(Phase 1),解析状态为 Discovered/Proposed 的 CDR 文件;预验证(Phase 2),跳过缺少必需章节的 CDR;Evals 回归门(Phase 2a),在默认开启的情况下运行现有 goldenset 以检查接受该 CDR 是否会破坏现有指令合规测试;可执行性门(Phase 2b),在提供接受选项前将机械式规则与判断式规则分类;缺口识别(Phase 3),列出需要澄清的项;顺序澄清(Phase 4),每次交互仅处理一个 CDR;更新 CDR(Phase 5),在每次决策后写入状态与澄清元数据;重新生成索引(Phase 6);汇总(Phase 7)。
CDR 质量检查清单包括:清晰解释模式的上下文、明确的决策陈述、来自代码库或功能的证据、格式良好的目标模块路径、状态准确、与现有指令无冲突、团队级适用性,以及可执行性分类(机械式确定性检查 vs 判断式上下文规则)。
使用方式与标志
用户输入在 $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 限制每次会话的澄清数量(默认 5);--no-evals-gate 禁用 evals 回归门(默认开启)。
执行流程
Phase 1 运行 scripts/bash/setup-levelup-clarify.sh 并读取所有 CDR 文件进行过滤,若脚本不可用则手动解析 REPO_ROOT 与 CDR_DRAFTS_DIR。Step 0 检测草稿是否为轻量格式,若是则转换为完整正式模板(ADR/PDR/ChDR/CDR/EVAL 各自格式)并从会话上下文丰富它;若已是完整格式则进行常规审查。Phase 2 检查每个 CDR 的必需章节(Context、Decision、Evidence、Target Module),跳过无效 CDR 并报告。Phase 2a 运行 evals 回归门,可能将 CDR 标记为 Blocked (Evals) 并保持待处理状态。Phase 2b 对规则类 CDR 分类可执行性:机械式(固定模式,如禁用 API、导入形状、文件位置规则、固定语法模式)应使用确定性检查(单元测试、二值评分器、pre-commit 钩子、lint 规则或 CI 作业),判断式(跨文件一致性、匹配周围风格、需要意图判断的任何情况)则按常规使用上下文规则。默认先构建检查而非编写规则。非规则类型跳过此门。Phase 3 生成缺口报告。Phase 4 顺序澄清,每次仅呈现一个 CDR,等待用户输入,提供选项 A 接受、B 拒绝、C 推迟、D 接受所有剩余、P 提升为检查(仅机械式规则)。动作 P 会提议确定性检查并在批准后构建与验证,然后更新 CDR 为拒绝(机械可执行——提升为确定性检查)或保留为薄指针。动作 A 更新状态为 Accepted 并添加澄清元数据。动作 D 批量接受剩余。动作 B 拒绝并询问原因(项目专属、与现有指令重复、已弃用/过时模式、低价值、机械可执行——提升为确定性检查)。动作 C 推迟并保留状态。Phase 5 在每次交互后立即更新文件,不批量处理。Phase 6 重新生成 cdr.md 索引。Phase 7 输出汇总,包括已审查、接受、拒绝、推迟的数量以及下一步。
适用场景与限制
关键规则包括:一次一个(每个响应恰好呈现一个 CDR,每次恰好询问一个问题,等待用户输入);立即写入(每次决策后更新 CDR 文件,会话结束后重新生成索引);不自动批准(未经用户明确选择绝不接受或拒绝,不假设用户偏好);会话限制(默认每次会话 5 个 CDR,遵守 --limit N,用户可说“done”提前退出)。
工作流衔接方面,若有 CDR 被接受,则交给 /levelup-publish,输出 JSON 如 {"command": "clarify", "accepted": ["CDR-001", "CDR-002"], "rejected": ["CDR-003"], "deferred": ["CDR-004"]}。完成澄清流程后运行 /levelup-publish 将接受的 CDR 编译为 team-ai-directives PR。验证要求:所有已审查的 CDR 文件更新了新状态与澄清元数据,cdr.md 索引重新生成,接受的 CDR 准备好用于 /levelup-publish,没有 CDR 在无用户输入的情况下被自动接受或拒绝。