Compound Promotion Ladder

Compound Promotion Ladder — 经验分层沉淀

> Codex 洞察（P4→P5）：本仓库强项不是"自动造 skill"，而是"把经验分层沉淀成可检索、可升级知识"。

---

升级阶梯

原始经验 → solution doc → critical pattern → existing skill 补充 → new skill
   ↑                                                                    ↑
  ce:compound 写入                                           手动决策后创建

| 层级 | 位置 | 形态 | 触发方式 | |------|------|------|----------| | solution | docs/solutions/ | 具体事件记录 + YAML frontmatter | ce:compound 自动写入 | | critical pattern | docs/solutions/ + pattern: tag | 跨场景抽象规律 | 检测到 ≥2 次重复后提升 | | skill supplement | 现有 skills/*/SKILL.md 新增章节 | 在已有 skill 内追加注意事项 | 检测到跨模块影响 | | new skill | skills-custom/ 新目录 | 独立 SKILL.md | 非显然模式 + 影响范围广 |

---

P5a：ce:compound 后的自动检测

ce:compound 写入 solution doc 后，运行以下检测：

检测逻辑

# 1. 统计同类问题出现频次
# 检查 docs/solutions/ 中相同 tags 的文档数量
SIMILAR_COUNT=$(grep -rl "tags:.*$TAG" docs/solutions/ | wc -l)

# 2. 检查是否跨模块
AFFECTED_FILES=$(git log --all -- "$RELATED_FILE" --name-only | sort -u | wc -l)

# 3. 判断是否为非显然模式（无法通过直觉推导）
# 需要人工判断，但 AI 可以提示

升级触发条件

| 条件 | 行动 | 优先级 | |------|------|--------| | 同类问题 ≥ 2 次（相同 tags） | 建议提升为 critical pattern | 中 | | 影响 ≥ 3 个不同模块 | 建议补充到相关 skill | 高 | | 非显然模式 + 频繁出现 | 建议创建新 skill | 高 | | 单次事件，无重复 | 保留 solution doc，不提升 | 低 |

检测输出格式

ce:compound 完成后，如果检测到升级条件，输出：

🪜 Compound Promotion 检测结果：

  同类问题出现 3 次（tags: windows-hooks, encoding）
  影响模块：hooks/, scripts/, .claude/

  建议：
  1. 将 docs/solutions/2026-04-05-windows-hooks-crlf.md 提升为 critical pattern
     → 添加 type: critical-pattern 到 frontmatter
  2. 在 skills/git-worktree/SKILL.md 的 Windows 注意事项节补充此模式

  执行？(y/n/skip)

---

P5b：Recurrence Miner — 定期挖掘重复问题

手动调用时（或每月），从 docs/solutions/ 挖掘重复模式：

# 1. 按 tags 统计频次
grep -r "^tags:" docs/solutions/*.md | \
  sed 's/.*tags: //' | tr ',' '\n' | \
  sort | uniq -c | sort -rn | head -20

# 2. 找出同一 file_path 出现多次的问题
grep -r "^  - " docs/solutions/*.md | \
  grep -E "file_path|affected_files" | \
  awk '{print $NF}' | sort | uniq -c | sort -rn | head -10

输出分析报告：docs/solutions/recurrence-report-YYYY-MM-DD.md

---

升级执行流程

提升为 Critical Pattern

在现有 solution doc 的 frontmatter 中：

# 原 solution frontmatter
type: solution

# 提升后
type: critical-pattern
pattern_id: "CP-001"
first_seen: "2026-03-24"
recurrence_count: 3
affected_modules: ["hooks", "scripts", ".claude"]

补充到现有 Skill

在目标 skill 的 SKILL.md 中找合适章节，追加：

## ⚠️ Windows 注意事项

> **来源**：CP-001（出现 3 次）

Windows 上运行 hooks 时注意：
- CRLF 换行符导致脚本解析失败 → 使用 `dos2unix` 或 git attributes
- 详见 docs/solutions/2026-04-05-windows-hooks-crlf.md

创建新 Skill

当模式足够独立、通用，且不适合补充到任何现有 skill：

# 1. 使用 create-agent-skills skill 创建
# 2. 放入 skills-custom/ (fork overlay)
# 3. 在 docs/solutions/ 中链接新 skill

---

防过拟合机制

| 风险 | 防御 | |------|------| | 为通过 eval 优化 prompt | Promotion 基于真实重复，不基于 eval 结果 | | 过度抽象 | 升级需 ≥2 次真实出现，单次不升级 | | eval 案例泄漏进 skill prompt | 铁律：evals/ 内容绝不复制到 skill prompt |

---

与 ce:compound 的集成

ce:compound 完成写入 docs/solutions/-.md
    ↓
自动运行 Promotion 检测（本 overlay P5a）
    ↓
检测到升级条件？
    ├─ 否 → 完成，结束
    └─ 是 → 展示升级建议 → 等待用户确认 → 执行升级

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jerrylalala
• Source: Jerrylalala/compound-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.