artifact-analysis

アーティファクト分析

ローカルパスの集合（または beagle プロジェクトで慣例的に使用されるナレッジの場所）を、出典を明記した、インサイト、コンテキスト、決定事項、未加工の詳細の構造化された抽出結果に変換します。

成果物は必ずディスク上に作成されます。呼び出し元が監査できる、記述されたスキャン計画、スライスごとの調査結果ファイル、パスを根拠とする引用付きの統合レポートが作成されます。インラインの文章は返されず、出典パスと逐語的な抜粋がない主張は一切含まれません。

使用する場合

• ユーザーがローカル文書の読み取りを依頼する場合 — 「docs フォルダーを分析して」「プロジェクトをスキャンしてコンテキストを調べて」「.beagle/concepts/ の内容を抽出して」。
• 別の beagle スキルが、根拠付けのための補助機能としてこのスキルをプログラムから呼び出す場合（references/companion-contract.md を参照）。
• 呼び出し元が監査可能な出力を求める場合。抽出の前に計画を書き出し、スライスごとに調査結果ファイルを作成し、引用で裏付けられた統合レポートを作成します。

使用しない場合

• コードベースの検索（「この関数はどこで定義されているか」「このシンボルを grep する」）。代わりにコードベースを検索してください。
• ウェブ調査。web-research を使用してください。
• 2 つの実装の比較評価や、情報源の信頼性の判定。llm-judge を使用してください。
• スキャン対象文書の書き換えや編集。humanize-beagle (../../../beagle-docs/skills/humanize-beagle/SKILL.md) を使用するか、ファイルを直接編集してください。
• PDF／画像の OCR／形式変換。初回バージョンが対応するのはプレーンテキストと Markdown のみです。
• 有料壁や認証が必要なリモートソース。この機能はローカルファイルシステムを対象とします。
• 呼び出し元の質問へのコーチング、異議の提示、再構成。これらは呼び出し元の担当です。

ワークフロー

順番に実行する 4 つのステップです。省略できるステップはありません。

ハードゲート

合格条件が満たされた場合にのみ次のステップに進みます。記憶ではなく、output_dir内のファイル（およびツールの出力）を使って確認してください。

タイミング	合格条件
plan.md の書き込み後	plan.md が存在し、意図、解決済みパス、スライス、スライスごとの概要、スキップパターン、適用した予算、統合方法が含まれていること（**スキャン計画（plan.md）**と同じ項目）。
サブエージェントのディスパッチ後	コーパスが空の場合の経路（サブエージェントなし、plan.md に読み取り可能なドキュメントが0件と記載）を取ったか、plan.md に記載されたすべてのスライスについて findings/<slice-slug>.md がディスク上にあること。
report.md の書き込み後	report.md が存在し、見出しが references/report-template.md（7つのセクションと ## Sources）に一致すること。
呼び出し元に返す前	references/failure-modes.md → **検証チェックリスト（オーケストレーターが最後に実行）**のすべての項目がチェック済みであること。そうでない場合は、同ファイルの指示に従って、失敗したチェックを report.md の ## Gaps & Limitations に記録すること。

1. plan.md を書き込む — 解決済みパス（自動検出を適用した場合はその結果を含む）、意図の要約（指定されている場合）、スライスごとの概要、スキップパターン、調査結果の統合方法を記載します。
2. スライスをディスパッチする — エージェントがサブエージェントに対応している場合は、解決済みパスを重複しないスライスに分けて、1～3個のサブエージェントを並行して起動します。対応していない場合は、同じスライスを自分で順次処理します。出力は同一にします。各スライスは output_dir 内の findings/<slice-slug>.md に書き込みます。
3. report.md を統合して作成する — 調査結果を、パスを明記した引用とともに、固定された7つのセクションにまとめます。
4. 返す前に検証する — ハードゲートの最後の行を満たし、references/failure-modes.md の番号付きチェックリスト（検証チェックリスト（オーケストレーターが最後に実行））を実行します。チェックに失敗した場合は、そのファイルの指示に従って Gaps & Limitations の項目に記載します。チェックリストの失敗を黙って残したまま、成果物を返してはいけません。

Receive paths + optional intent ──→ Auto-discover if paths empty
                                   ↓
                                 Write plan.md (no user-confirmation pause)
                                   ↓
                                 Dispatch subagents (up to 3 parallel)
                                   ↓
                                 Collect findings/<slice>.md files
                                   ↓
                                 Synthesize report.md
                                   ↓
                                 Return paths to caller

web-research とは異なり、artifact-analysis では計画レビューのゲートで処理を一時停止しません。ローカルのスキャンは低コストです。plan.md は監査可能性のために作成されるため、数週間後に読んだ人も、各サブエージェントにどのような指示が与えられたかを確認できます。web-research とは異なり、ツールが見つからない場合でも即時に処理を中断することはありません。エージェントの環境では、ファイルシステム検索（read、glob、grep）が利用できるものとします。

入力

フィールド	型	必須	デフォルト	目的
intent	文字列	いいえ	—	呼び出し元が探しているもの、またはその理由です。指定されていない場合、スキルは構造上重要な情報を抽出します。
paths	文字列のリスト	いいえ	自動検出	ディレクトリおよび／または明示的に指定されたファイルです。指定されていない場合は自動検出します（下記参照）。
output_dir	絶対パス	いいえ	導出	plan.md、findings/、report.md の出力先です。
refresh	bool	いいえ	false	true の場合、同じ output_dir にある過去の実行結果の上書きを許可します。

このスキルは、呼び出し元固有の構造を解析しません。呼び出し元は意図を表す文字列、および／またはパスのリストを渡します。

自動検出

paths が指定されていないか空の場合、beagle の標準的なナレッジ格納場所をスキャンします。

• .beagle/concepts/ — 概念仕様書と分析フォルダー。
• .planning/ — ロードマップ、状態、フェーズの成果物。
• docs/ — プロジェクトのドキュメント。
• トップレベルにある、README*、BRIEF*、OVERVIEW*、CONTEXT*、CLAUDE.md、AGENTS.md に一致するファイル。

自動検出した場合も含め、解決済みパスは plan.md にそのまま記載されます。これにより、呼び出し元はどのファイルが含まれたかを正確に確認できます。

インテントモード

• intent が指定されている場合 — インテントに関連する内容を対象に抽出します。インテントから外れた内容は、残しておく価値のある具体的な引用や指標である場合に限り、Raw Detail Worth Preserving に含めます。
• intent が指定されていない場合 — 汎用的な重要事項の抽出モードです。サブエージェントは解釈による絞り込みを行わず、構造的に重要な情報（知見、決定事項、技術的制約、ユーザーや市場に関する背景など）を抽出します。

出力先

呼び出し元が output_dir を渡した場合は、その値をそのまま使用します。それ以外の場合は、デフォルト値を次のように導出します。

.beagle/analysis/<slug>/

スラッグの導出方法（同じ日に同じ入力を再実行しても、同じフォルダーに出力されるようにします）：

1. intent が指定されている場合は、インテント文字列からスラッグを作成します。小文字にし、句読点を除去し、空白を単一のハイフンにまとめ、単語の途中で切れないように60文字で切り詰めます（60文字より前に最後のハイフンがある場合はそこで切り、ない場合は60文字で切ります）。
2. intent が指定されていない場合は、最初にスキャンしたパスのベース名から、同じルールでスラッグを作成します。
3. YYYY-MM-DD- を先頭に付けます。

再実行の保護。 書き込みを開始する前に、output_dir に plan.md または report.md がすでに存在するか確認します。存在し、refresh が true でない場合は、既存のフォルダー名を示すメッセージを出して処理を拒否します。refresh: true の場合は、最初に既存の内容を <output_dir>/.archive-<timestamp>/ にアーカイブします。references/failure-modes.md を参照してください。

アーティファクト分析をコンセプトフォルダーの規約（例：prfaq-beagle）に組み込む呼び出し元は、分析結果を利用側の隣に配置するため、output_dir を明示的に渡します：.beagle/concepts/<concept-slug>/analysis/。

スキャン計画（plan.md）

計画は、サブエージェントの実行前に作成します。これは監査証跡であり、レビューの承認ゲートではありません。このスキルは、ユーザーの確認を求めて処理を一時停止しません。

plan.md には次の内容を含めます。

• Intent — 入力文字列をそのまま記載します。intent が指定されていない場合は "generic salient extraction" とします。
• 解決済みパス — 実際にスキャンするすべてのパスを記載し、自動検出された項目と呼び出し元が指定した項目を、それぞれ注記します。
• スライス — 解決済みパスを1～3個のサブエージェントにどのように割り当てるかを記載します。スライスは重複しません。
• スライスごとの概要 — 各スライスについて、そのサブエージェントに抽出するよう指示した内容を1段落で要約します。仕様から機械的に導出し、plan.md を読めば各サブエージェントへの指示内容を予測できるようにします。
• スキップパターン — 今回の実行に適用される拒否リストを記載します（references/skip-patterns.md を参照）。
• 適用される予算 — 今回の実行におけるサブエージェント数（1～3）と、適用される概要確認のしきい値を記載します（下記の予算のデフォルト値を参照）。
• 統合方法 — スライスごとの調査結果をどのように統合して report.md を作成するかを記載します。

Wrote plan.md と報告して、サブエージェントの実行に進みます。処理の一時停止や承認ゲートはありません。

サブエージェントの実行

最大3個のサブエージェントを、重複しないスライスに対して並行実行します。各サブエージェントには、plan.md から機械的に導出した概要を渡します。計画と概要の間で解釈にずれが生じることはありません。概要のテンプレートは references/subagent-brief.md にあります。

各サブエージェントは次の処理を行います。

• 割り当てられたパスのスライスをスキャンし、概要確認の戦略（sharded-doc：最初にインデックスを読む、large-doc：最初に目次や見出しを読む）とスキップパターンに従います。
• output_dir の下に findings/<slice-slug>.md を書き込みます。
• オーケストレーターに返すのは、パスとステータスを含む簡潔なステータス行1行のみです。調査結果をインラインで返してはいけません。

オーケストレーターはすべてのサブエージェントの完了を待ち、その後、統合前に想定された調査結果ファイルがすべて存在することを確認します。ファイルがない場合はサイレント失敗として記録し、「不足と制限」に含めます。references/failure-modes.md を参照してください。

流し読みの戦略

サブエージェントはすべてを最初から最後まで読むわけではありません。次の方法を適用します。

• 分割されたドキュメント（index.md と複数のサブファイルがあるフォルダー） — まず index.md を読み、次に関連すると示されたサブファイルだけを読みます。
• 大規模なドキュメント（単一ファイルが約50ページ超、または約2000行超） — まず目次、エグゼクティブサマリー、セクション見出しを読みます。次に、意図に関連するセクション（意図がない場合は構成上重要なセクション）だけを全文読みます。調査結果ファイルには、流し読みしたセクションと全文を読んだセクションが記録されます。
• 短いドキュメント（単一ファイルで中程度のサイズ） — 最初から最後まで読みます。

スキップパターン

機密情報、バイナリ、ベンダー／ビルド関連のパスは、呼び出し元が再指定しなくても黙ってスキップされます。デフォルトの拒否リストは references/skip-patterns.md にあります。各サブエージェントは、スキップしたパスを paths_skipped フロントマターフィールドに記録し、監査証跡から除外対象を正確に確認できるようにします。

引用

調査結果ファイルと report.md のすべての主張には引用が付いています。形式は references/citation-schema.md に記載されています。概要は次のとおりです。

• 必須フィールド： path（可能な場合はスキャン対象ルートからの相対パス）、excerpt（ドキュメントからの逐語引用）。
• 任意フィールド： lines（サブエージェントが自然に取得できる場合に限り、行の範囲または単一行。決して推定で作成しない）、heading（直近の親見出し）、document_type。

本文中の参照には [^n] の脚注を使用します。完全な引用は、レポート下部の番号付き Sources セクションに記載します。

統合（report.md）

レポートは、次の順序で並ぶ固定の7セクション構成です。すべてのセクションが毎回必須です。内容が少ないセクションでも、その旨を示す箇条書きを含めます。

1. ## Documents Found — 含めた各パスと、その関連性についての1行の注記。
2. ## Key Insights — コーパスから得られた、特に重要な所見をテーマ別にまとめます。
3. ## User / Market Context — ドキュメントから明らかになったユーザー、顧客、競合、市場データ。
4. ## Technical Context — プラットフォーム、制約、統合、依存関係。
5. ## Ideas & Decisions — 各項目に根拠とともに accepted、rejected、open のいずれかのタグを付けます。却下されたアイデアも意図的に残し、将来の作業で再び提案されないようにします。
6. ## Raw Detail Worth Preserving — 要約によって失われる具体的な引用、データポイント、指標、その他の詳細。
7. ## Gaps & Limitations — コーパスから確認できなかったこと、空だった、スキップされた、または読み取り不能だったパス、失敗したサブエージェント。

スキャンが完全に見える場合でも、Gaps & Limitations は必須です。コーパスに含まれていたものと含まれていなかったものを正直に記録することも、プロダクトの一部です。このスキルがコピーする完全なリテラル形式のひな形は references/report-template.md にあります。

失敗モード

• 部分的な成功 — 1つ以上のサブエージェントが失敗します。このスキルは成功した結果を使って続行し、Gaps & Limitations の下に、失敗した各スライスを最後に判明している概要とスタブファイルになった理由とともに列挙します。
• コーパスが空 — パス解決（自動検出＋明示的なパス）の結果、読み取り可能なドキュメントが0件になります。このスキルは plan.md と、Gaps & Limitations の下に「ドキュメントが見つかりません」という箇条書きが1つだけある最小限の report.md を書き込み、サブエージェントを起動せず、呼び出し元に正常に戻ります。以降の対応は呼び出し元が決定します。
• サイレント失敗の検出 — 各サブエージェントは、戻る前に少なくともスタブの findings/<slice-slug>.md を書き込み、フロントマターに status:（ok、empty、failed）を記録します。ディスパッチ後にファイルが見つからない場合はサイレント失敗とみなし、Gaps & Limitations に記録します。
• 再実行の保護 — 上記の「出力先」で説明しています。詳細は references/failure-modes.md を参照してください。

web-research とは異なり、artifact-analysis はツールが見つからなくても即座に失敗しません。ファイルシステム検索（read、glob、grep）はエージェントの環境に存在するものとします。何らかの理由で存在しない場合、スキル全体を中止するのではなく、部分的な成功におけるサブエージェントの失敗として報告します。

完全なルールと構造化されたエラー形式は references/failure-modes.md に記載されています。

既定の予算

調整可能な設定値であり、ハードコードされた不変条件ではありません。

設定項目	既定値
並列サブエージェント数	1-3
スライスの重複	なし（強制）
大規模とみなす行数・ページ数の閾値	> 約2000行または > 約50ページ

より狭い範囲または広い範囲が必要な呼び出し元は、より具体的な paths リストを渡して上書きします。サブエージェントごとに1つのパスを指定するとスライスが狭まり、単一のフォルダーを指定するとスキルが内部で分割できます。

連携スキルの呼び出し規約

ほかの beagle スキルは、小規模で文書化された規約を使ってこのスキルを呼び出します。最小限の呼び出しでは intent のみを渡し、完全な呼び出しでは paths、output_dir、refresh も追加します。

既知の3つの呼び出し元（prfaq-beagle、brainstorm-beagle、strategy-interview）の実例と、成功時および拒否時の戻り値の形式は references/companion-contract.md に記載されています。呼び出し元は、独自の並行した呼び出し形式を考案せず、規約をそのまま守ることが期待されています。

トーン

このスキルはトーンに依存しないプリミティブです。次のことは行いません。

• どのドキュメントが重要かについて、呼び出し元に助言する。
• ドキュメントの品質や主張の信頼性を判定する（これは llm-judge の役割です）。
• 呼び出し元の意図を別の質問に作り変える。
• 姿勢（徹底的、ソクラテス式、親しみやすい）を採用する（これは呼び出し元の役割です）。
• 調査結果やレポートに論評を加える。

呼び出し元がコーチングスキル（prfaq-beagle、brainstorm-beagle）の場合、コーチングはこのスキルの実行前後に行われます。このスキル内では、意図は確定したものとして扱われます。

対象外

• 有料壁や認証で保護されたリモートソースのスキャン。まずファイルツールを使って内容を抽出し、その後にパスを渡してください。
• ドキュメントの品質や主張の信頼性に対する LLM-as-judge 評価。llm-judge を使用してください。
• 意図に対するコーチング、異議申し立て、または意見を加えた再構成。
• スキャン対象ドキュメントの書き換えや編集。設計上、読み取り専用です。
• バイナリや画像の OCR、PDF からのテキスト抽出、形式変換。初版ではプレーンテキストと Markdown のみを読み取ります。
• 多言語分析。現時点では英語のみです。
• 呼び出しをまたいだ調査結果のキャッシュや再利用。
• 長時間実行またはスケジュールされたスキャン。

参照ファイル

• references/subagent-brief.md — オーケストレーターが各サブエージェントのディスパッチ時に plan.md から機械的に埋めるテンプレートです。
• references/citation-schema.md — 必須および任意の引用フィールド、脚注の規則、形式の整った例を記載しています。
• references/report-template.md — 固定の7つのセクションをすべて含む、report.md の文字どおりのひな形です。
• references/failure-modes.md — 部分的な成功、コーパスが空の場合、サイレント障害の検出、および再実行の保護ルールを記載しています。
• references/companion-contract.md — prfaq-beagle、brainstorm-beagle、strategy-interview の実例を含む、プログラムからの呼び出し形式を記載しています。
• references/skip-patterns.md — すべての実行に適用される、デフォルトの拒否リスト（機密情報、バイナリ／メディア、ベンダー／ビルド）です。