doc-consolidation

文档整合

从临时的大模型输出中提取有价值的知识，并将其合并到永久文档中。

适用场景

在以下情况使用此技能：

• 你有 Claude 会话生成的未跟踪 *_REPORT.md 或 *_ANALYSIS.md 文件
• Git 状态显示有不应提交、但包含有用内容的 Markdown 文件
• 你想保留代码审查、重构报告或 API 审计中的见解
• 准备 PR 时，需要清理工作产物

以下情况请勿使用：

• 文件已位于合适的文档目录中 （docs/、skills/）
• 文件是有意保留的临时草稿
• 用户明确希望保留原报告格式
• 源文件没有可提取的价值（纯日志输出）

不适用场景

• 更新文档以匹配代码变更（使用 sanctum:doc-updates）
• 检测散文中的 AI 模式（使用 scribe:slop-detector）

格式规范

将内容合并到永久文档时，请遵循 Skill(leyline:markdown-formatting) 约定：正文每行不超过 80 个字符（优先在句子或分句边界换行），标题前后留空行，仅使用 ATX 标题，列表前留空行，较长的 URL 使用引用式链接。

快速开始

/consolidate-docs

或者直接调用：

I have some report files that need consolidating into permanent docs.

两阶段工作流

阶段 1：筛选（快速模型）

进行只读分析，生成整合计划：

1. 检测候选文件 - 查找带有大模型输出标记的未跟踪 Markdown 文件
2. 分析内容 - 提取并归类有价值的部分
3. 确定目标位置 - 将内容对应到现有文档，或提出新建文件的建议
4. 展示计划 - 告知用户将整合哪些内容及其目标位置

检查点：执行前由用户审查并批准计划。

阶段 2：执行（主模型）

获批后，执行整合：

1. 合并内容 - 融入现有文档或创建新文件
2. 删除源文件 - 成功合并后移除临时文件
3. 生成摘要 - 报告创建、更新和删除的内容

工作流详情

步骤 1：检测候选文件

加载：@modules/candidate-detection.md

通过以下方式识别文件：

• Git 状态（未跟踪的 .md 文件）
• 位置（不在标准文档目录中）
• 命名（全大写的非标准名称）
• 内容标记（Executive Summary、Findings、Action Items）

步骤 2：分析内容

加载：@modules/content-analysis.md

对每个候选文件：

• 将各部分提取为内容块
• 分类：可执行事项、决策、发现、指标、迁移指南、API 变更
• 评估价值：高／中／低

步骤 3：确定目标位置

加载：@modules/destination-routing.md

对每个有价值的内容块：

• 与现有文档进行语义匹配
• 找不到合适目标时应用默认映射
• 确定合并策略（融入、替换、追加、创建）
• 确定目标文档的受众层级后再进行路由。 一个目标文档只面向一类读者，跨层级合并会让入门页面塞进审计表。报告中的发现、指标和理由属于 expert 内容：应将其放入 docs/deep-dive/<topic>.md、ADR 或基准测试页面，再从 newcomer 文档链接过去，而不是融入其中。层级表和删减测试见 scribe:slop-detector 模块 audience-targeting.md。如果无法明确目标文档自身的层级，请询问，不要猜测。

步骤 4：生成计划

向用户展示整合计划：

# Consolidation Plan

## Source: API_REVIEW_REPORT.md

| Content | Category | Value | Destination | Action |
|---------|----------|-------|-------------|--------|
| API inventory | Findings | High | docs/api-overview.md | Create |
| Action items | Actionable | High | docs/plans/2025-12-06-api.md | Create |

### Post-Consolidation
- Delete: API_REVIEW_REPORT.md

Proceed with consolidation? [Y/n]

步骤 5：执行合并

加载：@modules/merge-execution.md

用户批准后：

• 按目标文件对操作分组
• 应用合并策略
• 验证结果（frontmatter 完整，结构保留）
• 删除源文件
• 生成执行摘要

快速模型委派

为提高效率，阶段 1 的任务会委派给 haiku 级模型：

# plugins/sanctum/scripts/consolidation_planner.py handles:
-scan_for_candidates()
-extract_content_chunks()
-categorize_chunks()
-score_value()
-find_semantic_matches()

阶段 2 仍由主模型负责，以谨慎执行合并。

内容类别

类别	描述	默认目标位置
可执行事项	任务、TODO、后续步骤	docs/plans/YYYY-MM-DD-{topic}.md
已做出的决策	架构选择	docs/adr/NNNN-{date}-{topic}.md
发现／见解	审计结果、分析	最匹配的现有同层级文档，否则放入 docs/deep-dive/
指标／基线	前后对比	docs/benchmarks/
迁移指南	分步操作流程	docs/migration-guide.md
API 变更	重大变更、弃用	CHANGELOG 或 API 文档

合并策略

智能编织

将内容插入匹配的现有章节，同时保留原有风格。

适用情况：目标文档包含相关章节，且内容是补充信息。

替换章节

用更详尽的新内容替换现有章节。

适用情况：新内容详尽程度至少是原内容的 2 倍，或日期更新。

添加并附上上下文

新增章节，并注明日期和来源。

适用情况：没有匹配的章节，且内容不适合现有结构。

创建新文件

生成完整的新文档。

适用情况：没有合适的目标位置，且内容足以独立成文。

集成

可与其他 sanctum 技能协同工作：

• git-workspace-review：检测到未跟踪的报告时，可能会建议合并整理
• pr-prep：创建 PR 前会提醒用户检查未跟踪的分析文件
• doc-updates：合并整理后可调用，以进行最终润色

示例会话

User: I have API_REVIEW_REPORT.md from our review session. Can you consolidate it?

Claude: I'll consolidate the report into permanent documentation.

**Phase 1: Triage**

Scanning for candidates...
- Found: API_REVIEW_REPORT.md (untracked, LLM markers detected)

Analyzing content...
- Extracted 6 content chunks
- High value: API inventory, action items, CLI recommendation
- Medium value: security assessment
- Low value: executive summary (generic)

Routing destinations...
- API inventory → docs/api-overview.md (CREATE)
- Action items → docs/plans/2025-12-06-api-consistency.md (CREATE)
- CLI naming → docs/adr/0002-cli-naming.md (CREATE ADR)
- Security → Already covered in docs/security.md (SKIP)

**Consolidation Plan**
[table shown]

Proceed? [Y/n]

User: Y

Claude: **Phase 2: Executing**

Created: docs/api-overview.md (1,247 bytes)
Created: docs/plans/2025-12-06-api-consistency.md (892 bytes)
Created: docs/adr/0002-2025-12-06-cli-naming.md (634 bytes)
Deleted: API_REVIEW_REPORT.md

Consolidation complete. Review the created files and commit when ready.

故障排除

未找到候选项

• 检查 git status，确认是否存在未跟踪文件
• 文件可能已位于标准位置
• 尝试指定文件路径：「Consolidate API_REVIEW_REPORT.md」

提取质量较低

• 源文件可能缺少结构化章节
• 内容可能过于笼统，难以分类
• 对于结构不清晰的报告，尝试手动提取

合并冲突

• 目标文件的结构已发生变化
• 尝试使用 APPEND 策略，而非 WEAVE
• 可能需要手动干预

相关技能

• sanctum:doc-updates - 常规文档更新
• sanctum:git-workspace-review - 工作区预检分析
• sanctum:pr-prep - Pull request 准备
• imbue:catchup - 了解近期变更

退出标准

• 在修改任何文件之前，向用户展示合并整理计划，其中包括源文件、 内容类别、目标路径和合并策略
• 所有源临时文件（*_REPORT.md、*_ANALYSIS.md 等） 均在内容成功合并后删除
• 每个合并后的目标文件都保留完整的 frontmatter， 且合并后现有结构保持不变
• 没有将内容合并到面向不同读者的文档中。跨层级内容 应放入带有链接的深度解析文档
• 合并整理完成后，git status 中没有未跟踪的报告类 Markdown 文件
• 如果没有找到候选项，应报告「未找到候选项」并说明 使用的搜索条件，而不是悄然结束