bmad-shard-pro

Shard Pro

長いドキュメントを、エージェントが後で安価かつ安全に読めるようにします。読み手は検索する場合もしない場合もあり、次に何を開くか判断するまでにファイルの最初の200行だけを見ることもあります。そこで見た情報から、どの事実がどこにあるかを把握できなければなりません。処理の途中で、ソースの内容が失われたり変更されたりすることはありません。どこで区切り、何と呼ぶかはあなたが決め、スクリプトが分割します。その後はユーザーが成果物を保守するため、更新も簡単でなければなりません。

規約

• {skill-root} はこのスキルのフォルダー、{project-root} は _bmad/ を含む最も近いフォルダーです。
• このスキルのスクリプトは uv run {skill-root}/scripts/shard_tool.py です。引数を確認するには、--help または <command> --help を指定して実行します。memlog スクリプトは uv run {project-root}/_bmad/scripts/memlog.py です。_bmad/ がない場合は、memlog への書き込みを省略し、その旨を一度だけ伝えます。
• {doc_folder} は成果物を格納するフォルダーです。分割する場合、入力ファイルのフォルダー名がファイル名にちなんだものであれば（prd-x/prd-x.md）、そのフォルダーを使います。それ以外の場合は、入力ファイルの隣に、ファイルのステム名を付けた新しいフォルダーを作成します。メインファイルの名前はフォルダー名と同じにします。目次リストを作成する場合は、ファイルと同じフォルダーを使います。

起動時

• ドキュメントのメインファイルがシャード化ドキュメントに関する注記から始まる場合、またはこのスキルで作成した目次リストがある場合（`` から始まります）は、references/update.md を最後まで読み、その指示に従います。
• 文字起こし、チャットのエクスポート、メールのスレッド、会議メモの集まりは、分割するドキュメントではなく、意思決定、アクション、メモを抽出するための入力です。その旨を伝え、bmad-ingest スキルがインストールされていれば、そのスキルを使って処理します。インストールされていない場合は、まず処理が必要であることをユーザーに伝えます。その後、終了します。
• Markdown またはプレーンテキスト以外のファイル（.docx、PDF、HTML）の場合は、ユーザーが使用しているツールを使うか、あなたに依頼して、まずMarkdownに変換するよう求めます。その後、変換されたファイルを使って続行します。
• それ以外のドキュメントは、「評価」に進みます。

評価

入力に対して outline を実行します。次のいずれかを推奨し、理由を1行で述べます。

• そのままにする。 全体を読むのに十分短いか、すでに構成が分かりやすく示されています。
• 目次リスト。 ファイルは1つのまま、上部に詳細な目次リストを追加します。変更が少なく、読者が検索や行範囲をたどる場合、ツールやスキルがドキュメントを1つのファイルとして扱うことを想定している場合、または読み方を判断できない場合に選びます。
• 忠実に分割。 ソースを一言一句そのままシャードに分割し、マップを付けます。読者がファイル全体を読み込むため、各自が一部分だけを読み込めるようにしたい場合や、ドキュメントを部分ごとに保守する場合に選びます。内容は失われず、スクリプトで検証されます。

分割すると、後から読む人は毎回マップを経由することになるため、そうしない場合に読者の負担がより大きくなる場合に限って推奨します。ユーザーが特定の結果（「シャード化して」「目次を追加して」など）を求めた場合は、アウトラインから見て読みにくくなる場合を除き、その結果を推奨します。読みにくくなる場合は、その理由を伝えます。

そのままにする場合は、理由を伝えて終了します。それ以外の場合は、「計画」に進みます。

アウトラインから計画する

アウトラインをもとに計画し、必要な範囲だけを読みます。長い文書を丸ごとコンテキストに保持するのは、コストのかかる誤りです。提案された分割案から始め、内容に応じて変更します。

• シャードは、文字数でおよそ 3～14 KB にします。行の長さはばらつきが大きすぎるため、行数では測りません。無関係な主題をまとめたシャードより、1 つの主題を扱う短いシャードのほうが適切です。
• 表、手順のリスト、図の途中では決して分割しません。build はフェンス付きブロック、表、番号付きリストの途中での分割を拒否します。それ以外については、自分で確認してください。
• 各シャードには、内容を表す名前を kebab-case で付けます。文書種別の接頭辞で名前を始めてはいけません。prd-* の glob で別の PRD として読み込まれてしまうためです。
• 見出しが単独の識別子（## 3、### C-2 など）の場合は、その内容からシャード名を付けます（アウトラインには、そのような見出しの下にある最初の行が示されています）。タイトルには識別子を残します。
• 原文独自の索引や番号付けの規則を使う前に、本文と照合します。多くの場合、旧版のものです。
• マトリックス、登録簿、用語集などの総覧は、行を数える読者が一か所で確認できるよう、全体をまとめておきます。小さなものは同じシャードにまとめてもかまいません。
• 読者が疑問を持ったときに、そのシャードが該当するものだと分かるように、各マップ要約を書きます。シャードの内容が原文で後に置き換えられている場合は、その旨を要約に記載します。
• 原文で同じ事項に 2 つの値が示されている場合、いずれかの値を含む各シャードの要約でそのことを伝え、もう一方の値を含むシャードを示します。原文に優先順位の規則が記されていても、どちらか一方を選んではいけません。
• 読者が、マップのタイトルだけでは解決できない識別子を使って情報を探す場合に限り、検索パターンを設定します（たとえば、数百件の要件 ID がある場合）。

build --help が示す形式で、計画を JSON として記述します。

計画に合意する

• ユーザーがいる場合：結果、その理由、結果の保存先、シャード一覧（タイトルと 1 行の要約）を提示してから、返答を待ちます。分割する場合は、入力が .source/ に移動し、シャードが文書になることを伝えます。ユーザーの合意後にのみビルドします。
• ユーザーから中断せずに実行するよう依頼された場合、またはユーザーが不在の状態で別のスキルからこのスキルが呼び出された場合は、処理を続行し、最後に報告します。

ビルド

build を実行するか、目次を作成する場合は計画を指定して toc を実行します。その後に計画を変更するには、計画を編集して build を再実行します。ソースを .source/ から読み込み、古いシャードを置き換えます。

次に、結果と、ユーザーが行った変更や決定を {doc_folder}/.memlog.md に記録します。すでに memlog がある場合は保持します。存在しない場合は memlog.py init --workspace {doc_folder} を実行し、その後 append --type decision|change|event を実行します。

確認してから報告する

結果に対して check を実行し、忠実に分割した後は --rebuild を指定します。完了する前に、すべてのエラーを修正します。

ユーザーには、次の内容を報告します。

• 結果とメインファイルの場所。
• 分割した場合は、入力が .source/ に格納されたこと。
• 原文で確認した内容：両方の値が示されている矛盾と、それぞれの記載箇所、索引の誤り、誤りの疑い。
• 分割後に参照先が解決しなくなったと check が警告するリンク。シャードには原文の表現がそのまま残るため、修正するかどうかはユーザーが判断します。

確認事項は報告と memlog に記録し、シャードには記載しません。シャードには原文に書かれている内容を記載します。読者は、どれがあなたの判断でどれが著者の判断かを見分けられません。