doc-consolidation

ドキュメントの統合

一時的な LLM の出力から価値ある知識を抽出し、永続的なドキュメントに統合します。

使用するタイミング

次の場合にこのスキルを使用します。

• 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.

2 段階のワークフロー

フェーズ 1：トリアージ（高速モデル）

統合計画を作成するための読み取り専用分析を行います。

1. 候補を検出 - LLM 出力のマーカーを含む、追跡対象外の 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

ユーザーの承認後：

• 操作を移行先ファイルごとにまとめます
• 統合方法を適用します
• 結果を検証します（フロントマターが保たれていること、構造が維持されていること）
• ソースファイルを削除します
• 実行概要を作成します

高速モデルへの委任

フェーズ 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 を確認してください
• ファイルはすでに標準の保存先にある可能性があります
• 明示的なファイルパスを指定してください：「API_REVIEW_REPORT.md を統合」

抽出の品質が低い

• ソースファイルに構造化されたセクションがない可能性があります
• 内容が一般的すぎて、カテゴリーに分類できない可能性があります
• 構造化されていないレポートは、手動での抽出を試してください

マージの競合

• 保存先ファイルの構成が変更されています
• WEAVE の代わりに APPEND 戦略を試してください
• 手動での対応が必要になる場合があります

関連スキル

• sanctum:doc-updates - 一般的なドキュメントの更新
• sanctum:git-workspace-review - 事前のワークスペース分析
• sanctum:pr-prep - プルリクエストの準備
• imbue:catchup - 最近の変更の把握

完了条件

• ファイルを変更する前に、ソースファイル、コンテンツのカテゴリー、保存先のパス、マージ戦略を示す統合計画をユーザーに提示している
• ソースの一時ファイル（*_REPORT.md、*_ANALYSIS.md など）が、内容のマージに成功した後、すべて削除されている
• マージ後も、各マージ先ファイルのフロントマターが保たれ、既存の構成が維持されている
• 異なる読者向けに書かれたドキュメントに内容が移されていない。階層をまたぐ内容は、リンクされた詳細な解説に記載されている
• 統合完了後、git status に未追跡のレポート形式の Markdown ファイルが表示されない
• 候補が見つからない場合、何も報告せずに完了するのではなく、使用した検索条件とともに「候補なし」と報告している