agent-research-aggregator

agent-research-aggregator

---

実行すべきか（判断ゲート）

Phase 1 を開始する前に、集約が本当に必要か確認してください。

状況	アクション
workspace/inputs/idea.md と workspace/inputs/experimental_log.md が両方存在し、空でない	このスキル全体をスキップしてください。 そのまま paper-orchestra に進みます。
いずれかのファイルが存在しない、または空で、かつユーザーがディレクトリパスを指定した	そのディレクトリを --search-roots として、このスキルを実行します。
いずれかのファイルが存在しない、または空で、かつディレクトリが指定されていない	デフォルトで cwd と ~ をスキャンし、続行する前に検出結果の概要をユーザーに提示します。
入力ファイルは存在するものの、内容が不十分に見える（例：idea.md が 5 行未満、experimental_log.md に数値データがない）	集約で補足するか、そのまま進めるかをユーザーに確認してください。

このスキルは意図的に前処理として設けられています。実行しなくても支障はなく、構造化された入力がすでに存在しない場合にのみ実行してください。

---

PaperOrchestra（arXiv:2604.05018）用の前処理スキルです。AI コーディングエージェントのキャッシュディレクトリに散在する実験成果物を読み込み、PaperOrchestra のパイプラインが必要とする構造化された (I, E) 入力ペアにまとめます。

[.claude/]  [.cursor/]  [.antigravity/]  [.openclaw/]
      │            │              │               │
      └────────────┴──────────────┴───────────────┘
                          │
                    Phase 1: Discovery
                  (discover_logs.py)
                          │
                    discovered_logs.json
                          │
                    Phase 2: Extraction
                  (LLM call per log batch)
                          │
                    raw_experiments.json
                          │
                    Phase 3: Synthesis
                  (LLM call — consolidate)
                          │
                    synthesis.json
                          │
                    Phase 4: Formatting
                  (format_po_inputs.py)
                          │
             ┌────────────┴────────────┐
      workspace/inputs/         workspace/ara/
        idea.md                   aggregation_report.md
        experimental_log.md       discovered_logs.json
                                  raw_experiments.json
                                  synthesis.json

出力は workspace/inputs/ に直接保存されるため、ユーザーは同じワークスペース上ですぐに paper-orchestra を実行できます。

---

入力

パラメーター	必須	デフォルト	説明
--search-roots	いいえ	cwd, ~	エージェントのキャッシュをスキャンするディレクトリ（カンマ区切り）
--agents	いいえ	all	対象とするサブセット（カンマ区切り）：claude,cursor,antigravity,openclaw
--workspace	いいえ	./workspace	PaperOrchestra のワークスペースルート
--depth	いいえ	4	ディレクトリの最大スキャン深度（大きなホームディレクトリでの過剰なスキャンを防止）
--since	いいえ	none	この日付以降に変更されたログのみを対象とします（ISO 8601：2025-01-01）

ユーザーはスキルの実行時にこれらを指定します。現在のディレクトリに検出可能なエージェントキャッシュがない場合は、--search-roots を指定するようユーザーに依頼してもかまいません。

---

Phase 1 — 検出（決定論的）

検出スクリプトを実行し、関連するすべてのログファイルを一覧化します。

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --out workspace/ara/discovered_logs.json

--project フィルターが設定されていない場合、スクリプトはコード 2 で終了します（初回実行では想定どおりです）。標準出力に 「Projects found」 のリストが表示されるので、すぐにユーザーに提示してください。

ログがまったく見つからない場合： 処理を中止し、--search-roots を指定するか、エージェントのキャッシュフォルダーを含むディレクトリを指定するようユーザーに依頼してください。

---

Phase 1.5 — プロジェクトの選択（必須）

論文の作成に使用できるプロジェクトは 1 つだけです。LLM による処理を開始する前に、使用するプロジェクトをユーザーに必ず確認してください。

1. 検出結果の概要にある番号付きプロジェクトリストを表示します。例：

   Projects found:
     [1] /home/alice/projects/my-rl-experiment  (42 files)
     [2] /home/alice/projects/llm-eval-suite    (17 files)
     [3] /home/alice/projects/old-demo          (3 files)
   

2. 次のように質問します。「この論文の作成に使用するプロジェクトを選んでください。番号を選ぶか、プロジェクトのパスを貼り付けてください。」
3. ユーザーから回答を得るまで、Phase 2 に進まないでください。
4. 選択されたプロジェクトで検出を再実行し、マニフェストを絞り込みます。

python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots <roots> \
    --agents <agents> \
    --depth <depth> \
    --since <since> \
    --project "<chosen project path>" \
    --out workspace/ara/discovered_logs.json

これにより discovered_logs.json が上書きされ、選択されたプロジェクトのファイルだけが残ります。スクリプトは成功時に 0 で終了します。

検出されたプロジェクトが 1 つだけの場合： 質問を省略し、ユーザーに 「プロジェクトが 1 つだけ見つかりました：<path>。これを論文に使用します。」 と伝えてから、自動的に --project を指定して再実行します。

絞り込み後も検出結果の概要に無関係なファイルが含まれている場合： Phase 2 に進む前に、それらを含めるか除外するかをユーザーに確認してください。抽出プロンプトは保守的なので、含める方を優先してください。

フェーズ 2 — 抽出（LLM による支援）

検出されたログをバッチ単位で処理します（エージェントの種類ごとにまとめ、コンテキスト制限に収まるよう、各バッチの生テキストを約 50 KB 未満に保ちます）。

各バッチについて：

1. バッチ内のログファイルを読み込みます（スクリプトの --list 出力に、読み込むファイルパスが示されます）。
2. references/extraction-prompt.md の抽出プロンプトをシステムメッセージとして適用します。
3. 生ログのテキストをユーザーメッセージとして渡します。
4. LLM が返す構造化 JSON を収集します（スキーマはプロンプトを参照してください）。
5. workspace/ara/raw_experiments.json に追記します。

すべてのバッチの処理後：

python skills/agent-research-aggregator/scripts/extract_experiments.py \
    --discovered workspace/ara/discovered_logs.json \
    --out workspace/ara/raw_experiments.json \
    --validate-only

--validate-only モードで実行し、結合した JSON の形式が正しく、最小スキーマを満たしていることを確認します（experiments 配列が空でなく、各エントリに hypothesis、method、results のいずれかが含まれていること）。フェーズ 3 に進む前に、形式が正しくないエントリを修正してください。

---

フェーズ 3 — 統合（LLM による支援）

複数のエージェントキャッシュに含まれる重複している可能性のある実験記録を、まとまりのある単一の研究ストーリーに統合します。LLM の呼び出しは 1 回です。

システムメッセージ： references/synthesis-prompt.md をそのまま使用します。

ユーザーメッセージ：

<raw_experiments>
{contents of workspace/ara/raw_experiments.json}
</raw_experiments>

LLM は、次のキーを含む synthesis.json を返す必要があります。

• research_question — 調査対象となる全体的な問い
• hypothesis — 提案する解決策または主張の核心
• method_summary — アプローチの仕組み（簡潔にし、データ漏洩を避ける）
• key_contributions — 箇条書きの文字列 2～5 個
• experimental_setup — データセット、指標、ベースライン、実装に関する注記
• results_tables — {title, headers[], rows[]} 形式の Markdown 表オブジェクトの配列
• qualitative_observations — 自由形式のテキストブロック（うまくいったこと、いかなかったこと、失敗モード、アブレーション分析から得られた知見）
• iteration_history — 複数のイテレーションが検出された場合、{iteration_id, change_description, outcome} エントリの順序付きリスト
• open_questions — ログ内で未解決のまま残っている問い

workspace/ara/synthesis.json に保存します。

注記： この時点までに、ユーザーはフェーズ 1.5 で単一のプロジェクトをすでに選択しています。統合結果は、まとまりのある単一の研究テーマを表す必要があります。LLM が依然として複数の関連性のない研究上の問いを提示した場合は、監査レポート（フェーズ 5）でデータ品質上の警告として報告します。ただし、プロジェクトの選択を再度求めないでください。この決定はすでに済んでいます。

---

フェーズ 4 — フォーマット変換（決定論的）

synthesis.json を PaperOrchestra の入力ファイルに変換します。

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/

これにより、次の 2 つのファイルが生成されます。

workspace/inputs/idea.md（Sparse 形式）

PaperOrchestra Sparse Idea 形式（arXiv:2604.05018, §3.1）に従います。

# [Synthesized Research Title]

## Problem
<2–4 sentence problem statement derived from research_question>

## Hypothesis
<hypothesis from synthesis>

## Method
<method_summary from synthesis>

## Key Contributions
<key_contributions as bullet list>

## Open Questions
<open_questions, if any>

workspace/inputs/experimental_log.md

PaperOrchestra Experimental Log 形式（App. D.3）に従います。

## 1. Experimental Setup
<experimental_setup from synthesis, formatted as prose + sub-bullets>

## 2. Raw Numeric Data
<results_tables converted to GitHub-Flavored Markdown tables>

## 3. Qualitative Observations
<qualitative_observations from synthesis>

### Iteration History
<iteration_history as an ordered narrative, if present>

スクリプトを実行した後、ユーザーと一緒に両方のファイルを確認します。

1. workspace/inputs/idea.md を読み上げ、「これは研究上の問いと手法を正確に表していますか？」と尋ねます。
2. workspace/inputs/experimental_log.md の表のヘッダーを読み上げ、「これらの指標とベースラインは正しいですか？」と尋ねます。

PaperOrchestra に進む前に、フィードバックに基づいて修正します。

---

フェーズ 5 — 監査レポート（決定論的）

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/ \
    --report workspace/ara/aggregation_report.md

--report フラグを指定すると、スクリプトは aggregation_report.md も書き込みます。レポートには次の内容が含まれます。

• スキャンしたエージェントキャッシュ数、読み込んだファイル数、処理したバッチ数
• エージェントごとの内訳（エージェントの種類ごとに見つかったファイル数）
• 抽出した実験記録（件数、日付範囲）
• 検出したイテレーション（件数、収束の方向）
• データ品質上の警告（欠落、信頼度の低い抽出、矛盾する数値）
• 書き込んだファイルとそのサイズ

レポートをユーザーに提示します。データ品質のセクションに警告が記載されている場合は、paper-orchestra を実行する前に話し合ってください。入力が悪ければ、出力も悪くなります。

---

PaperOrchestra への引き継ぎ

ユーザーが idea.md と experimental_log.md を確認したら、ワークスペースの準備は完了し、paper-orchestra パイプラインに進めます。まだ次のファイルが必要です。

ファイル	状態	対応
workspace/inputs/idea.md	✓ 生成済み	ユーザーによる確認を推奨
workspace/inputs/experimental_log.md	✓ 生成済み	ユーザーによる確認を推奨
workspace/inputs/template.tex	不足	会議の LaTeX テンプレートを提供するようユーザーに依頼
workspace/inputs/conference_guidelines.md	不足	提供するようユーザーに依頼（ページ数の上限、締め切り、書式ルール）

不足しているファイルがこの2つであることをユーザーに正確に伝え、提供されたら paper-orchestra を実行することを提案してください。

---

エラー処理

状況	対応
キャッシュディレクトリが存在しない	何もせずスキップし、レポートに記載
ファイルがバイナリまたはテキスト以外	スキップし、レポートに記載
ファイルが 200 KB を超える	200 KB で切り詰め、パスとともにレポートに記載
LLM による抽出で不正な JSON が返される	解析エラーを追記して一度だけ再プロンプトし、それでも不正な場合はバッチを status: failed として記録し、続行
統合後の research_question が 1 件を超える	監査レポートにデータ品質の警告として記録し、プロジェクトについて再質問しない（Phase 1.5 で選択済み）
統合後の results_tables が空	ユーザーに警告する — PaperOrchestra のセクション執筆エージェントには数値データが必要です

---

厳守事項（決して違反しないこと）

1. エージェントのキャッシュディレクトリには書き込まないでください。 このスキルは .claude/、.cursor/、.antigravity/、.openclaw/ を読み取り専用で扱います。
2. 生成する idea.md または experimental_log.md に個人情報（メールアドレス、氏名、認証情報、API キー）を含めないでください。抽出プロンプトでは LLM に個人情報の除去を指示していますが、引き継ぎ前に再確認してください。
3. 結果を捏造しないでください。 ある指標が信頼度の低いログ1件にしか記載されていない場合、黙って含めず、表で [UNVERIFIED] とマークしてください。
4. スキャンで 50 ファイルを超えるファイルが見つかった場合は、見つかったファイル一覧についてユーザーの確認を得るまで Phase 1 を先に進めないでください。

---

クイックリファレンス

# Phase 1: discover all projects (exits with code 2 — project selection required)
python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots . ~ --out workspace/ara/discovered_logs.json

# Phase 1.5: re-run with chosen project (exits 0)
python skills/agent-research-aggregator/scripts/discover_logs.py \
    --search-roots . ~ \
    --project "/home/user/projects/my-chosen-project" \
    --out workspace/ara/discovered_logs.json

# ... (Phase 2: LLM extraction calls, see above) ...

python skills/agent-research-aggregator/scripts/extract_experiments.py \
    --discovered workspace/ara/discovered_logs.json \
    --out workspace/ara/raw_experiments.json --validate-only

# ... (Phase 3: LLM synthesis call, see above) ...

python skills/agent-research-aggregator/scripts/format_po_inputs.py \
    --synthesis workspace/ara/synthesis.json \
    --out workspace/inputs/ \
    --report workspace/ara/aggregation_report.md