bmad-distillator

Distillator: ドキュメント蒸留エンジン

概要

このスキルは、任意のソースドキュメントの集合から、超圧縮されたトークン効率の高いドキュメント（蒸留物）を生成します。蒸留物は、ソースに含まれるすべての事実、決定、制約、関係を保持しつつ、人間には必要だが LLM には不要なすべてのオーバーヘッドを排除します。情報抽出および圧縮のスペシャリストとして動作します。出力は単一の高密度なドキュメント（または意味的に分割された集合）であり、下流の LLM ワークフローが情報を失うことなく唯一のコンテキスト入力として消費できます。

これは圧縮タスクであり、要約タスクではありません。要約は非可逆です。蒸留物は LLM の消費に最適化された可逆圧縮です。

有効化時

1. 入力を検証します。 呼び出し元は以下を提供する必要があります。

   • source_documents（必須） — 蒸留する 1 つ以上のファイルパス、フォルダパス、または glob パターン
   • downstream_consumer（任意） — この蒸留物を消費するワークフロー／エージェント（例: 「PRD 作成」、「アーキテクチャ設計」）。指定された場合は、シグナルとノイズを判断するために使用します。省略された場合は、すべてを保持します。
   • token_budget（任意） — おおよその目標サイズ。指定され、蒸留物がそれを超える場合は、意味的分割をトリガーします。
   • output_path（任意） — 保存先。省略された場合は、主要なソースドキュメントの隣に -distillate.md サフィックスを付けて保存します。
   • --validate（フラグ） — 蒸留物の生成後に往復再構築テストを実行します。

2. ルーティング — ステージ 1 に進みます。

ステージ

#	ステージ	目的
1	分析	分析スクリプトを実行し、ルーティングと分割を決定
2	圧縮	コンプレッサーエージェントを起動して蒸留物を生成
3	検証と出力	完全性チェック、フォーマットチェック、出力の保存
4	往復検証	（--validate のみ）再構築して元のドキュメントと差分を比較

ステージ 1: 分析

scripts/analyze_sources.py --help を実行し、次にソースパスを指定して実行します。そのルーティング推奨とグループ化出力を使用してステージ 2 を進めます。ソースドキュメントを自分で読まないでください。

ステージ 2: 圧縮

シングルモード（ルーティング = "single"、3 ファイル以下、推定 15K トークン以下）:

agents/distillate-compressor.md を使用して 1 つのサブエージェントを起動し、すべてのソースファイルパスを渡します。

ファンアウトモード（ルーティング = "fan-out"）:

1. 分析出力のグループごとに 1 つのコンプレッサーサブエージェントを起動します。各コンプレッサーはそのグループのファイルパスのみを受け取り、中間蒸留物を生成します。

2. すべてのコンプレッサーが戻ったら、agents/distillate-compressor.md を使用して最終的な マージコンプレッサー サブエージェントを 1 つ起動します。中間蒸留物の内容を（元のファイルではなく）入力として渡します。その役割は、グループ間の重複排除、テーマ別の再グループ化、および最終圧縮です。

3. 中間蒸留物の内容をクリーンアップします（それはメモリ内にのみ存在し、ディスクには保存されません）。

グレースフルデグラデーション: サブエージェントの起動が利用できない場合は、ソースドキュメントを読み、agents/distillate-compressor.md の同じ指示を使用して圧縮作業を直接実行します。ファンアウトの場合は、グループを順次処理してからマージします。

コンプレッサーは、蒸留物の内容、ソースの見出し、名前付きエンティティ、およびトークン推定値を含む構造化 JSON 結果を返します。

ステージ 3: 検証と出力

コンプレッサー（またはマージコンプレッサー）が返した後:

1. 完全性チェック。 コンプレッサーが返した見出しと名前付きエンティティのリストを使用して、それぞれが蒸留物のコンテンツに含まれていることを確認します。不足が見つかった場合は、完全な再圧縮ではなく、的を絞った修正パスとしてコンプレッサーに送り返します。修正パスは最大 2 回までに制限します。

2. フォーマットチェック。 出力が蒸留物のフォーマットルールに従っていることを確認します:

   • 散文の段落がないこと（箇条書きのみ）
   • 装飾的な書式がないこと
   • 情報の重複がないこと
   • 各箇条書きが自己完結していること
   • テーマが ## 見出しで明確に区切られていること

3. 出力フォーマットを決定します。 ステージ 1 の分割予測と実際の蒸留物のサイズを使用します:

   単一蒸留物（約 5,000 トークン以下、または token_budget を超えていない場合）:

   frontmatter 付きの単一ファイルとして保存します:

   ---
   type: bmad-distillate
   sources:
     - "{relative path to source file 1}"
     - "{relative path to source file 2}"
   downstream_consumer: "{consumer or 'general'}"
   created: "{date}"
   token_estimate: {approximate token count}
   parts: 1
   ---
   

   分割蒸留物（約 5,000 トークンを超える場合、または token_budget がそれを要求する場合）:

   以下を含むフォルダ {base-name}-distillate/ を作成します:

   {base-name}-distillate/
   ├── _index.md           # Orientation, cross-cutting items, section manifest
   ├── 01-{topic-slug}.md  # Self-contained section
   ├── 02-{topic-slug}.md
   └── 03-{topic-slug}.md
   

   _index.md には以下が含まれます:

   • sources を含む frontmatter（蒸留物フォルダから元ファイルへの相対パス）
   • 3〜5 個の箇条書きによるオリエンテーション（何を、何から蒸留したか）
   • セクションマニフェスト: 各セクションのファイル名 + 1 行の説明
   • 複数のセクションにまたがる横断的な項目

   各セクションファイルは自己完結型で、独立して読み込むことができます。1 行のコンテキストヘッダーを含めます: 「このセクションでは [トピック] を扱います。M 部中の N 番目です。」

   frontmatter 内のソースパスは、蒸留物の場所からの相対パスでなければなりません。

4. 蒸留物を測定します。 最終的な蒸留物ファイルに対して scripts/analyze_sources.py を実行し、出力の正確なトークン数を取得します。この分析の total_estimated_tokens を distillate_total_tokens として使用します。

5. 結果を報告します。 常に構造化された JSON 出力を返します:

   {
     "status": "complete",
     "distillate": "{path or folder path}",
     "section_distillates": ["{path1}", "{path2}"] or null,
     "source_total_tokens": N,
     "distillate_total_tokens": N,
     "compression_ratio": "X:1",
     "source_documents": ["{path1}", "{path2}"],
     "completeness_check": "pass" or "pass_with_additions"
   }
   

   ここで、source_total_tokens はステージ 1 の分析による値で、distillate_total_tokens はステップ 4 による値です。compression_ratio は source_total_tokens / distillate_total_tokens を「X:1」の形式（例: 「3.2:1」）で表したものです。

6. --validate フラグが設定されている場合は、ステージ 4 に進みます。そうでなければ、完了です。

ステージ 4: ラウンドトリップ検証（--validate のみ）

このステージでは、蒸留物だけからソースドキュメントを再構築することで、蒸留物がロスレスであることを証明します。情報の損失が許容できない重要なドキュメントに使用するか、重要な下流ワークフローの品質ゲートとして使用します。日常的な使用には向きません — 大幅なトークンコストが追加されます。

1. 再構築エージェントを起動します。agents/round-trip-reconstructor.md を使用します。蒸留物ファイルのパス（分割蒸留物の場合は _index.md のパス）のみを渡します — 元のソースドキュメントにアクセスさせてはなりません。

   分割蒸留物の場合は、セクションごとに 1 つの再構築エージェントを並行して起動します。各エージェントは、自身のセクションファイルと、横断的なコンテキストのための _index.md を受け取ります。

   グレースフルデグラデーション: サブエージェントの起動が利用できない場合、このステージはメインエージェントでは実行できません（メインエージェントはすでに元ファイルを見ているため）。ラウンドトリップ検証にはサブエージェントのサポートが必要であることを報告し、スキップします。

2. 再構築結果を受け取ります。 再構築エージェントは、蒸留物に隣接して保存された再構築ファイルのパスを返します。

3. セマンティック差分を実行します。 元のソースドキュメントと再構築結果の両方を読みます。元の各セクションについて、以下を評価します:

   • 再構築結果に中核的な情報が含まれているか?
   • 具体的な詳細（数値、名前、決定事項）が保持されているか?
   • 関係性と根拠が損なわれていないか?
   • 再構築結果が元にないものを追加していないか?（ギャップを埋めるハルシネーションを示す）

4. 検証レポートを作成します。蒸留物に隣接して -validation-report.md として保存します:

   ---
   type: distillate-validation
   distillate: "{distillate path}"
   sources: ["{source paths}"]
   created: "{date}"
   ---
   
   ## Validation Summary
   - Status: PASS | PASS_WITH_WARNINGS | FAIL
   - Information preserved: {percentage estimate}
   - Gaps found: {count}
   - Hallucinations detected: {count}
   
   ## Gaps (information in originals but missing from reconstruction)
   - {gap description} — Source: {which original}, Section: {where}
   
   ## Hallucinations (information in reconstruction not traceable to originals)
   - {hallucination description} — appears to fill gap in: {section}
   
   ## Possible Gap Markers (flagged by reconstructor)
   - {marker description}
   

5. ギャップが見つかった場合は、完全な再圧縮を行わずに不足情報を追加する、蒸留物への的を絞った修正パスの実行を提案します。修正パスは最大 2 回までに制限します。

6. クリーンアップ — レポート生成後、一時的な再構築ファイルを削除します。