doc-consolidation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTable of Contents
目录
- When to Use
- Quick Start
- Two-Phase Workflow
- Phase 1: Triage (Fast Model)
- Phase 2: Execute (Main Model)
- Workflow Details
- Step 1: Candidate Detection
- Step 2: Content Analysis
- Step 3: Destination Routing
- Step 4: Generate Plan
- Source: API_REVIEW_REPORT.md
- Post-Consolidation
- Step 5: Execute Merges
- Fast Model Delegation
- Content Categories
- Merge Strategies
- Intelligent Weave
- Replace Section
- Append with Context
- Create New File
- Integration
- Example Session
- Troubleshooting
- No candidates found
- Low-quality extractions
- Merge conflicts
- Related Skills
Doc Consolidation
文档合并
Extracts valuable knowledge from ephemeral LLM outputs and merges it into permanent documentation.
从临时LLM输出中提取有价值的知识，并将其合并到永久文档中。
When To Use
适用场景
Use this skill when:
- You have untracked or
*_REPORT.mdfiles from Claude sessions*_ANALYSIS.md - Git status shows markdown files that shouldn't be committed but contain useful content
- You want to preserve insights from code reviews, refactoring reports, or API audits
- Preparing a PR and need to clean up working artifacts
Do NOT use when:
- Files are already in proper documentation locations (,
docs/)skills/ - Files are intentionally temporary scratch notes
- User explicitly wants to preserve the original report format
- Source files have no extractable value (pure log output)
在以下场景使用该技能：
- 你有来自Claude会话的未被追踪的或
*_REPORT.md文件*_ANALYSIS.md - Git状态显示存在不应提交但包含有用内容的Markdown文件
- 你希望保留代码评审、重构报告或API审计中的见解
- 准备PR时需要清理工作临时文件
请勿在以下场景使用：
- 文件已位于正确的文档目录（、
docs/）skills/ - 文件是特意创建的临时草稿笔记
- 用户明确希望保留原始报告格式
- 源文件无任何可提取的价值（纯日志输出）
When NOT To Use
不适用场景
- Files are already in docs/ or skills/ locations
- Files are intentionally temporary scratch notes
- Source files have no extractable value
- Files are already in docs/ or skills/ locations
- 文件已位于docs/或skills/目录下
- 文件是特意创建的临时草稿笔记
- 源文件无任何可提取的价值
- 文件已位于docs/或skills/目录下
Quick Start
快速开始
/consolidate-docsVerification: Run the command with flag to verify availability.
--helpOr invoke directly:
**Verification:** Run the command with `--help` flag to verify availability.
I have some report files that need consolidating into permanent docs.Verification: Run the command with flag to verify availability.
--help/consolidate-docs验证： 运行带有参数的命令以确认工具可用。
--help或直接调用：
**验证：** 运行带有`--help`参数的命令以确认工具可用。
我有一些报告文件需要合并到永久文档中。验证： 运行带有参数的命令以确认工具可用。
--helpTwo-Phase Workflow
两阶段工作流
Phase 1: Triage (Fast Model)
阶段1：分类筛选（轻量模型）
Read-only analysis to generate a consolidation plan:
- Detect candidates - Find untracked markdown files with LLM output markers
- Analyze content - Extract and categorize valuable sections
- Route destinations - Match content to existing docs or propose new files
- Present plan - Show user what will be consolidated and where
Checkpoint: User reviews and approves plan before execution.
只读分析，用于生成合并计划：
- 检测候选文件 - 查找带有LLM输出标记的未被追踪Markdown文件
- 分析内容 - 提取并分类有价值的章节
- 匹配目标路径 - 将内容与现有文档匹配或提议新文件
- 展示计划 - 向用户展示将合并的内容及目标位置
检查点：用户在执行前需审核并批准计划。
Phase 2: Execute (Main Model)
阶段2：执行合并（主模型）
After approval, performs the consolidation:
- Merge content - Weave into existing docs or create new files
- Delete sources - Remove ephemeral files after successful merge
- Generate summary - Report what was created/updated/deleted
获得批准后，执行合并操作：
- 合并内容 - 将内容嵌入现有文档或创建新文件
- 删除源文件 - 合并成功后删除临时文件
- 生成摘要 - 报告已创建/更新/删除的内容
Workflow Details
工作流详情
Step 1: Candidate Detection
步骤1：候选文件检测
Load:
@modules/candidate-detection.mdIdentifies files using:
- Git status (untracked files)
.md - Location (not in standard doc directories)
- Naming (ALL_CAPS non-standard names)
- Content markers (Executive Summary, Findings, Action Items)
加载模块：
@modules/candidate-detection.md通过以下方式识别文件：
- Git状态（未被追踪的文件）
.md - 位置（不在标准文档目录中）
- 命名（全大写的非标准名称）
- 内容标记（执行摘要、发现、行动项）
Step 2: Content Analysis
步骤2：内容分析
Load:
@modules/content-analysis.mdFor each candidate:
- Extract sections as content chunks
- Categorize: Actionable Items, Decisions, Findings, Metrics, Migration Guides, API Changes
- Score value: high/medium/low
加载模块：
@modules/content-analysis.md对每个候选文件：
- 将章节提取为内容块
- 分类：可行动项、决策、发现、指标、迁移指南、API变更
- 价值评分：高/中/低
Step 3: Destination Routing
步骤3：目标路径匹配
Load:
@modules/destination-routing.mdFor each valuable chunk:
- Semantic match against existing documentation
- Apply default mappings if no good match
- Determine merge strategy (weave, replace, append, create)
加载模块：
@modules/destination-routing.md对每个有价值的内容块：
- 与现有文档进行语义匹配
- 若无合适匹配则应用默认映射
- 确定合并策略（嵌入、替换、追加、创建）
Step 4: Generate Plan
步骤4：生成合并计划
Present consolidation plan to user:
markdown
undefined向用户展示合并计划：
markdown
undefinedConsolidation Plan
合并计划
Source: API_REVIEW_REPORT.md
源文件：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 |
| 内容 | 类别 | 价值 | 目标位置 | 操作 |
|---|---|---|---|---|
| API清单 | 发现 | 高 | docs/api-overview.md | 创建 |
| 行动项 | 可行动项 | 高 | docs/plans/2025-12-06-api.md | 创建 |
Post-Consolidation
合并后操作
- Delete: API_REVIEW_REPORT.md
Proceed with consolidation? [Y/n]
**Verification:** Run the command with `--help` flag to verify availability.- 删除：API_REVIEW_REPORT.md
是否继续合并？[Y/n]
**验证：** 运行带有`--help`参数的命令以确认工具可用。Step 5: Execute Merges
步骤5：执行合并
Load:
@modules/merge-execution.mdAfter user approval:
- Group operations by destination file
- Apply merge strategies
- Validate results (frontmatter intact, structure preserved)
- Delete source files
- Generate execution summary
加载模块：
@modules/merge-execution.md获得用户批准后：
- 按目标文件分组操作
- 应用合并策略
- 验证结果（前置元数据完整、结构保留）
- 删除源文件
- 生成执行摘要
Fast Model Delegation
轻量模型任务委托
Phase 1 tasks are delegated to haiku-class models for efficiency:
python
undefined阶段1的任务委托给haiku类模型以提升效率：
python
undefinedscripts/consolidation_planner.py handles:
scripts/consolidation_planner.py 负责：
- scan_for_candidates()
- extract_content_chunks()
- categorize_chunks()
- score_value()
- find_semantic_matches()
**Verification:** Run the command with `--help` flag to verify availability.
Phase 2 stays on the main model for careful merge execution.- scan_for_candidates()
- extract_content_chunks()
- categorize_chunks()
- score_value()
- find_semantic_matches()
**验证：** 运行带有`--help`参数的命令以确认工具可用。
阶段2的任务由主模型处理，以确保合并执行的准确性。Content Categories
内容类别
| Category | Description | Default Destination |
|---|---|---|
| Actionable Items | Tasks, TODOs, next steps | |
| Decisions Made | Architecture choices | |
| Findings/Insights | Audit results, analysis | Best-match existing doc |
| Metrics/Baselines | Before/after comparisons | |
| Migration Guides | Step-by-step procedures | |
| API Changes | Breaking changes, deprecations | CHANGELOG or api docs |
| 类别 | 描述 | 默认目标位置 |
|---|---|---|
| 可行动项 | 任务、待办事项、下一步计划 | |
| 已做出的决策 | 架构选择 | |
| 发现/见解 | 审计结果、分析内容 | 最匹配的现有文档 |
| 指标/基准 | 前后对比数据 | |
| 迁移指南 | 分步流程 | |
| API变更 | 破坏性变更、弃用通知 | CHANGELOG或API文档 |
Merge Strategies
合并策略
Intelligent Weave
智能嵌入
Insert content into matching existing sections, preserving style.
Use when: Destination has relevant section, content is additive.
将内容插入匹配的现有章节，保留原有格式风格。
适用场景：目标文档有相关章节，内容为补充性质。
Replace Section
替换章节
Replace existing section with more detailed new content.
Use when: New content 2x+ more detailed or has later date.
用更详细的新内容替换现有章节。
适用场景：新内容的详细程度是原有内容的2倍以上，或内容日期更新。
Append with Context
带上下文追加
Add new section with date and source reference.
Use when: No matching section, content doesn't fit existing structure.
添加带有日期和源文件引用的新章节。
适用场景：无匹配章节，内容不符合现有文档结构。
Create New File
创建新文件
Generate complete new document.
Use when: No suitable destination exists, content warrants standalone doc.
生成完整的新文档。
适用场景：无合适的目标文档，内容值得独立成篇。
Integration
集成能力
Works with other sanctum skills:
- git-workspace-review: May suggest consolidation when untracked reports detected
- pr-prep: Warns about untracked analysis files before PR creation
- doc-updates: Can invoke for final polish after consolidation
可与其他sanctum技能配合使用：
- git-workspace-review：检测到未被追踪的报告时，可能会建议执行合并
- pr-prep：创建PR前，会针对未被追踪的分析文件发出警告
- doc-updates：合并完成后，可调用该技能进行最终润色
Example Session
示例会话
**Verification:** Run the command with `--help` flag to verify availability.
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.Verification: Run the command with flag to verify availability.
--help**验证：** 运行带有`--help`参数的命令以确认工具可用。
用户：我有来自评审会话的API_REVIEW_REPORT.md文件，能帮我合并到永久文档吗？
Claude：我会将该报告合并到永久文档中。
**阶段1：分类筛选**
正在扫描候选文件...
- 已找到：API_REVIEW_REPORT.md（未被追踪，检测到LLM标记）
正在分析内容...
- 已提取6个内容块
- 高价值：API清单、行动项、CLI建议
- 中价值：安全评估
- 低价值：执行摘要（通用内容）
正在匹配目标路径...
- API清单 → docs/api-overview.md（创建）
- 行动项 → docs/plans/2025-12-06-api-consistency.md（创建）
- CLI命名规范 → docs/adr/0002-cli-naming.md（创建ADR）
- 安全评估 → 已在docs/security.md中覆盖（跳过）
**合并计划**
[展示表格]
是否继续？[Y/n]
用户：Y
Claude：**阶段2：执行合并**
已创建：docs/api-overview.md（1,247字节）
已创建：docs/plans/2025-12-06-api-consistency.md（892字节）
已创建：docs/adr/0002-2025-12-06-cli-naming.md（634字节）
已删除：API_REVIEW_REPORT.md
合并完成。请查看创建的文件，准备就绪后即可提交。验证： 运行带有参数的命令以确认工具可用。
--helpTroubleshooting
故障排查
No candidates found
未找到候选文件
- Check git status for untracked files
- Files may already be in standard locations
- Try explicit file path: "Consolidate API_REVIEW_REPORT.md"
- 检查Git状态中的未被追踪文件
- 文件可能已位于标准目录中
- 尝试指定明确的文件路径："合并API_REVIEW_REPORT.md"
Low-quality extractions
提取内容质量低
- Source file may lack structured sections
- Content may be too generic to categorize
- Try manual extraction for unstructured reports
- 源文件可能缺乏结构化章节
- 内容可能过于通用，无法分类
- 对于非结构化报告，可尝试手动提取
Merge conflicts
合并冲突
- Destination file structure changed
- Try APPEND strategy instead of WEAVE
- Manual intervention may be needed
- 目标文件结构已变更
- 尝试使用APPEND（追加）策略替代WEAVE（嵌入）策略
- 可能需要手动干预
Related Skills
相关技能
- - General documentation updates
sanctum:doc-updates - - Pre-flight workspace analysis
sanctum:git-workspace-review - - Pull request preparation
sanctum:pr-prep - - Understanding recent changes
imbue:catchup
- - 通用文档更新
sanctum:doc-updates - - 工作区预检查分析
sanctum:git-workspace-review - - Pull Request准备
sanctum:pr-prep - - 了解近期变更
imbue:catchup