levelup-specify

levelup-specify

此技能的作用

在工作完成后，从当前会话中提取上下文指令记录（CDR）。

这是用于记录已完成工作中的经验教训的主要命令：

• 直接回顾当前会话（Agent 记得自己做过什么）
• 识别可复用模式：规则、角色设定、示例、技能和宪章修订
• 对于每条指令 CDR，还要提取一条配对的 eval CDR，其中包含来自该会话的通过/失败案例
• 将 CDR 与具体实现证据（文件、提交、测试）关联起来
• 将 CDR 写入 {REPO_ROOT}/.adlc/drafts/cdr/CDR-{NNN}.md，状态设为 Proposed
• 自动生成 {REPO_ROOT}/.adlc/drafts/cdr/cdr.md 索引

与 /levelup-init 的主要区别：

• /levelup-init = 从现有代码库中发现模式（棕地）
• /levelup-specify（此技能）= 从当前会话中提取模式（绿地）

此技能侧重于会话级经验教训——刚完成的工作中产生了哪些可复用的知识。

何时使用

注意：常规决策记录由 team-boot 的持续记录机制处理，该机制会将简要草稿直接写入 .adlc/drafts/。此技能适用于交互式深入探索 ——当你希望在记录决策前，获得引导式权衡分析、多方案比较或结构化决策支持时使用。

• 完成工作后：记录会话中的可复用模式
• 为团队 AI 指令贡献内容：将会话工作转化为可复用指令
• 关闭分支前：提取团队范围的经验教训

何时不使用

• 棕地项目：使用 /levelup-init 扫描现有代码
• 挖掘 git 历史记录 / 与 issue 关联的变更：使用 /change-init 从提交记录和 issue 跟踪器中恢复过往决策
• 工作尚未完成时：完成实现后再运行此命令
• 常规团队 AI 指令验证：使用 /team-repair 进行健康检查

流程

用户输入

$ARGUMENTS

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

用户输入示例：

• "Focus on error handling patterns" — 提取与错误处理相关的 CDR
• "Document the testing approach" — 聚焦于测试模式
• "CDR-001" — 使用更多会话证据丰富现有 CDR
• "--focus skills" — 仅提议技能类型的 CDR
• 空输入：从会话轨迹中提取所有模式

标志

• --focus AREA：聚焦于特定上下文类型
  • rules：仅提议规则 CDR
  • personas：仅提议角色设定 CDR
  • examples：仅提议示例 CDR
  • constitution：仅提议宪章修订 CDR
  • skills：仅提议技能 CDR
• --cdr-id ID：使用会话证据丰富现有 CDR，而不是创建新 CDR

角色与上下文

你将扮演上下文提取器——识别当前会话中的可复用模式。你的职责包括：

• 阅读当前会话（Agent 会直接观察发生了什么）
• 识别有助于其他项目的模式
• 为规则、角色设定、示例、宪章修订或技能创建 CDR
• 对于每条指令 CDR，提取一条配对的 eval CDR，其中包含来自该会话的通过/失败案例
• 将 CDR 与实现证据（代码、提交、测试）关联起来

棕地与绿地

场景	命令	输入	输出
棕地（现有代码）	/levelup-init	代码库扫描	已发现的 CDR
绿地（会话已完成）	/levelup-specify	当前会话	待提议的 CDR

大纲

1. 环境设置（阶段 0）：解析路径
2. 审查会话（阶段 1）：审查当前会话，寻找模式和证据
3. 编写会话跟踪记录（阶段 1.5）：将审计跟踪记录写入 .adlc/drafts/trace.md
4. 加载现有 CDR（阶段 2）：读取待处理的 CDR，以便补充内容
5. 提取模式（阶段 3）：按上下文类型识别可复用模式，并提取配对的 eval CDR
6. 创建／补充 CDR（阶段 4）：编写包含会话证据的 CDR 文件
7. 重新生成索引（阶段 5）：更新 cdr.md
8. 总结（阶段 6）：呈现提取结果

执行步骤

阶段 0：环境设置

从技能的基础目录运行设置脚本：

scripts/bash/setup-levelup-specify.sh

解析 JSON 输出，获取路径和下一个 CDR 编号。

如果设置脚本不可用或运行失败，请手动解析路径：

1. REPO_ROOT — 从当前工作目录向上查找包含 .adlc/ 的目录，或者使用 git rev-parse --show-toplevel，或者使用 pwd。
2. TEAM_AI_DIRECTIVES — 先检查 TEAM_AI_DIRECTIVES 环境变量，再检查 REPO_ROOT/.adlc/init-options.json 中的 team_ai_directives 字段，最后回退到 REPO_ROOT/team-ai-directives。
3. CDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/cdr
4. NEXT_CDR — 列出 CDR_DRAFTS_DIR/CDR-*.md，找到最大编号并加 1，然后补齐为 3 位数字（例如，001）。

如果未配置 TEAM_AI_DIRECTIVES：

Team AI directives repository not configured.
Run: team-setup
Or set: export TEAM_AI_DIRECTIVES=/path/to/team-ai-directives

阶段 1：审查会话

审查当前会话，了解发生了什么。Agent 直接观察会话内容。

1. 用户提出了什么要求？
2. Agent 做了什么？（文件变更、关键决策、处理方式）
3. 结果如何？
4. 创建／修改了哪些文件？（git diff --stat、git log --oneline -10）
5. 出现了哪些可复用模式？

另外，收集实现证据：

# Files changed
git diff --stat 2>/dev/null

# Recent commits
git log --oneline -10 2>/dev/null

# New/untracked files
git status --short 2>/dev/null

阶段 1.5：编写会话跟踪记录

将简明的跟踪记录写入 {REPO_ROOT}/.adlc/drafts/trace.md，作为审计跟踪记录。

# Session Trace

Generated: [YYYY-MM-DD]
Branch: [branch-name or "N/A"]

## Summary

[2-3 sentences: what was asked, what was done, outcome]

## Key Decisions

1. [Decision — rationale]

## Files Changed

- `[path]`: [what changed]

阶段 2：加载现有 CDR

读取 {REPO_ROOT}/.adlc/drafts/cdr/CDR-*.md：

• 如果用户提供了 --cdr-id：加载指定的 CDR 以补充内容
• 否则：加载所有待处理的 CDR（状态为 Discovered/Proposed），以避免重复

阶段 3：提取模式

针对每种上下文类型，根据会话和证据寻找可复用模式：

规则：编码约定、错误处理、测试模式、安全实践
角色画像：实现过程中出现的角色（例如，“API 使用者”“DevOps 操作员”）
示例：值得复用的代码模式
技能：可打包为 Agent 技能的能力（尤其是可复用的工作流）
宪法修订：会话中发现的跨领域原则

技能类型 CDR：可以，/levelup-specify 可以提出技能类型的 CDR。实际的 SKILL.md 稍后由 /levelup-publish --skill <name> 构建。

Eval CDR：对于提取的每个指令 CDR（规则、角色画像、示例、宪法），还要从会话中提取一个配对的 eval CDR，其中包含二元通过／失败用例：

• 通过用例：Agent 正确遵循了（隐含）模式的情形
• 失败用例：Agent 违反了模式的情形（通常是创建该指令的触发因素）
• 对抗性用例：来自会话上下文、且该指令应能处理的边缘情况

每个用例都必须自包含，包含场景、输入上下文、Agent 输出，以及通过／失败的原因。用例不依赖外部跟踪文件；证据直接写在用例中。

Eval CDR 使用 ### Context Type: Eval，并通过 ### Paired Directive CDR: CDR-NNN 引用其配对的指令 CDR。

阶段 4：创建／补充 CDR

对于每个提取的模式，创建或补充一个 CDR：

## CDR-NNN: [Title]

### Status: **Proposed**

### Date: [YYYY-MM-DD]

### Source: Session evidence via /levelup-specify

### Target Module: `context_modules/rules/[domain]/[file].md` or `skills/[skill-name]/`

### Context Type: Rule | Persona | Example | Skill | Constitution Amendment

### Descriptor: One-line "when to use" summary.

### Context
[What reusable pattern was identified]

### Evidence

**Session**: [brief session description]
**Branch**: [branch-name]

**Implementation Evidence**:
- [file/path]: [description]
- `{commit-sha}`: [commit message]

### Decision
[What should be contributed to team-ai-directives]

Eval CDR 格式（与指令 CDR 配对）：

## CDR-NNN: [Eval Title]

### Status: **Proposed**

### Date: [YYYY-MM-DD]

### Source: Session evidence via /levelup-specify

### Target Module: `evals/{directive-id}/goldset.md`

### Context Type: Eval

### Paired Directive CDR: CDR-NNN

### Descriptor: One-line "what directive this eval tests"

### Context
[What behavior is being tested and why]

### Pass Cases
1. **Source**: session "[brief description]"
   **Scenario**: [what was asked]
   **Input context**: [what context was loaded]
   **Agent output**: [what the agent did]
   **Why it passes**: [why this follows the directive]

### Fail Cases
1. **Source**: session "[brief description]"
   **Scenario**: [what was asked]
   **Input context**: [what context was loaded]
   **Agent output**: [what the agent did — the violation]
   **Why it fails**: [why this violates the directive]
   **Correction**: [what should have been done]

### Adversarial Cases
1. **Scenario**: [edge case]
   **Expected**: [correct behavior]

### Evidence
**Session**: [brief session description]
**Paired Directive**: CDR-NNN

补充现有 CDR 时，将内容追加到 ### Evidence 部分，并更新补充时间戳。

阶段 5：重新生成索引

通过列出所有 CDR-*.md 文件并构建 Markdown 表格，重新生成 {REPO_ROOT}/.adlc/drafts/cdr/cdr.md。对每个 CDR，提取以下单行字段：

• ID — 从文件名中提取（例如，CDR-001）
• Target Module — 从 ### Target Module: 行提取
• Type — 从 ### Context Type: 行提取
• Status — 从 ### Status: 行提取
• Created — 从 ### Date: 行提取
• Descriptor — 从 ### Descriptor: 行提取

格式：

# Context Directive Records (Drafts)

## CDR Index

| ID | Target Module | Type | Status | Created | Verified | Age | Descriptor |
|----|---------------|------|--------|---------|----------|-----|------------|
| CDR-001 | context_modules/rules/... | Rule | Proposed | 2026-07-21 | - | - | One-line summary |

**Stats**: N entries | Last Updated: YYYY-MM-DD

阶段 6：摘要

## LevelUp Specify Summary

**Session**: [brief description]
**Date**: [date]
**CDRs Created**: N
**CDRs Enriched**: N

### CDRs by Type

| Type | Count |
|---|---|
| Rules | N |
| Examples | N |
| Skills | N |
| Personas | N |
| Constitution Amendments | N |
| Evals | N |

### Handover

**Next**: Run `/levelup-clarify` to review the N proposed CDRs.

CDRs are in `Proposed` status and cannot be published until accepted.

Handoff context:

```json
{
  "source": "session",
  "command": "specify",
  "cdrs_created": ["CDR-001", "CDR-002"],
  "cdrs_enriched": [],
  "next": "clarify"
}

### Next Steps

1. Run `/levelup-clarify` to review proposed CDRs
2. For low-evidence CDRs, add implementation evidence first
3. Run `/levelup-publish` for accepted CDRs

关键规则

提供证据链接，不要捏造

• 每个 CDR 都必须链接到具体的会话证据
• 引用具体的文件路径、提交 SHA 或测试用例
• 不要编造证据

避免重复

• 创建新的 CDR 之前，先检查现有 CDR
• 如果存在类似模式，应补充完善，而不是重复创建

Skill CDR 是记录，而非技能

• /levelup-specify 会创建 Context Type: Skill 的 CDR
• 它不会直接创建 SKILL.md 文件
• 技能产物由 /levelup-publish --skill <name> 构建

后续应用信号门槛

• 根据会话证据，尽可能多地创建 CDR
• 信号门槛（团队范围、高价值、独特、有证据）将在 /levelup-publish 阶段应用

工作流指导与转换

执行 /levelup-specify 后

必需：运行 /levelup-clarify，以审查拟议的 CDR。

完整的 CDR 生命周期

[Agent session — work completed]
    ↓
/levelup-specify  ← reviews session, writes trace, extracts CDRs
    ↓
[Extract patterns + paired evals] → Write CDRs to .adlc/drafts/cdr/CDR-{NNN}.md (Proposed)
    ↓
[Run /levelup-clarify] → Review and accept/reject CDRs (evals gate runs existing goldensets)
    ↓
[Run /levelup-publish] → Compile accepted CDRs into team-ai-directives PR
    ↓
[Run /team-repair] → Re-index and validate team AI directives after merge

后续步骤

/levelup-specify 完成后，运行 /levelup-clarify，以审查拟议的 CDR。

验证

• CDR 已写入 {REPO_ROOT}/.adlc/drafts/cdr/CDR-{NNN}.md，状态为 Proposed。
• 审计跟踪已写入 {REPO_ROOT}/.adlc/drafts/trace.md。
• {REPO_ROOT}/.adlc/drafts/cdr/ 中存在自动生成的 cdr.md 索引。
• 每个 CDR 都包含会话实现证据。
• Eval CDR 与其对应的 directive CDR 成对，并包含自包含的通过/失败用例。
• 适用时，现有 CDR 已得到补充完善，而非重复创建。

配置

• TEAM_AI_DIRECTIVES — 团队 AI 指令的路径（优先于 .adlc/init-options.json）。
• .adlc/init-options.json — 项目级配置文件，包含 team_ai_directives 字段。
• 默认回退路径：相对于项目根目录的 team-ai-directives/。

12 因子对齐

因子 IX（可追溯性）——从会话证据中提取可复用模式，供团队范围内贡献。

上下文

$ARGUMENTS