paper-notes

論文ノート

トリガーとルーティング

• トリガー：論文ノート、構造化ノート、読書ノート、论文笔记、paper_notes.jsonl。
• 使用する場合：サーベイのエビデンス段階（C3）で、papers/core_set.csv（および任意の全文テキスト）がすでにあり、後続の claims／citations／writing に備えて引用可能なエビデンスが必要な場合。

後続のステップ（claims、visuals、writing）で確実に統合できる、一貫性があり検索可能な論文ノートを作成します。

ここでは引き続き文章は書きません。ノートは箇条書きまたは短いフィールドで記述し、説明的な段落にはしないでください。

読み込み順序

必ず読むもの：

• references/overview.md
• references/note_schema.md

タスクに応じて読むもの：

• 制約事項を書く、またはレビューする場合は、references/limitation_taxonomy.md（定型文を避けます）
• key_results を抽出する場合は、references/result_extraction_examples.md（良い例と悪い例）
• result／limitation フィールドに論文の自己叙述や著者による結果の言い回しが残っている場合は、references/source_text_hygiene.md

機械可読アセット：

• assets/note_schema.json — 検証用の JSONL レコードスキーマ
• assets/evidence_tags.json — エビデンスバンクのタグ付けカテゴリ（コード変更なしで拡張可能）
• assets/source_text_hygiene.json — ノートフィールドにおける原文の文の整理ポリシー
• リポジトリ全体の assets/limitation-signals.json — 未解決の制約と、解決済みの失敗や改善とを区別するための共通極性ルール

スクリプトの範囲

scripts/run.py は、次の用途にのみ使用してください。

• core_set とメタデータから、決定的なひな形を生成する
• マッピングの網羅率に基づいて優先順位を選定する
• 構造化ノートフィールドからエビデンスバンクを構築する

run.py を次の用途に使用しないでください。

• 論文固有の制約事項の文章化（指針には references/limitation_taxonomy.md を使用）
• コード内に隠された、分野固有の評価ヒューリスティクス
• 読者向けの説明文

役割カード（プロンプトレベルのガイダンス）

• 精読担当

  • 使命：具体的で検証可能な事項（設定、手法、指標、制約）を抽出します。
  • 実施事項：具体的なタスクやベンチマーク、および論文が実際に測定している内容を記載します。
  • 避けること：どの論文にも当てはまるような、一般的な要約の定型文。

• 結果記録担当

  • 使命：後の執筆で必要となる評価の要点を記録します。
  • 実施事項：可能な場合は、タスク＋指標＋制約（予算／ツールへのアクセス）を記録します。
  • 避けること：その数値を意味あるものにする評価設定を添えず、数値だけをコピーすること。
  • 避けること：成果物の紹介（X enables ...、our framework features ...）を key_results に格上げすること。
  • 避けること：ベンチマークにおける位置付け、分野の動機付け、または著者による説明の案内（we apply ... and show ...、we then discuss how ...）を key_results に格上げすること。

• 制約記録担当

  • 使命：解釈を左右する留意事項を記録します。
  • 実施事項：論文固有の制約（プロトコルの不一致、アブレーションの不足、脅威モデルの不足など）を記述します。
  • 避けること：具体性のない「一般化できない可能性がある」といった、繰り返し使える一般的な制約事項。

使用するタイミング

• コアセット（できればマッピングも）が揃い、エビデンスに使えるノートが必要になった後。
• サーベイの草稿を書く前。

入力

• papers/core_set.csv
• 任意：outline/mapping.tsv（優先順位付け用）
• 任意：papers/fulltext_index.jsonl ＋ papers/fulltext/*.txt（全文モードで実行する場合）

出力

• papers/paper_notes.jsonl（JSONL、論文ごとに1レコード）
• papers/evidence_bank.jsonl（JSONL、ノートから生成される参照可能なエビデンスの抜粋。目標値：コース論文では論文あたり平均4件以上、A150++では平均7件以上）

判断：エビデンスの深さ

• 抽出済みのテキスト（papers/fulltext/*.txt）がある場合 → 全文の抜粋を用いて重要論文の内容を充実させ、evidence_level: "fulltext" を設定します。
• 抄録のみの場合（デフォルト） → ロングテールのノートは抄録レベルにとどめますが、重要度の高い論文は引き続き十分に充実させます（以下を参照）。

ワークフロー（ヒューリスティック）

使用するもの：outline/mapping.tsv、papers/fulltext_index.jsonl。

1. 網羅性を確保します。papers/core_set.csv 内のすべての paper_id に、JSONL レコードが1つずつ存在する必要があります。
2. マッピングを使って優先度の高い論文を選びます。
   • 複数のサブセクションで頻繁に再利用されているもの
   • 重要な古典的論文（対象範囲内であれば ReAct/Toolformer/Reflexion…）
3. 優先度の高い論文について、以下を記録します。
   • 3〜6個の要約箇条書き（新規性、問題設定、ループの内容）
   • method（メカニズムとアーキテクチャ。ベースラインとの違い）
   • key_results（ベンチマーク／指標。入手可能であれば数値も含める）
   • limitations（具体的な前提条件／失敗モード。一般的な定型文は避ける）
4. 重要度の低い論文については、以下のとおりです。
   • 要約の箇条書きは短くします（アブストラクトに基づく内容でもかまいません）
   • 少なくとも1つの制限事項を記載します。可能な限り具体的にします
5. 引用生成用に、各論文に安定した bibkey を割り当てます。

品質チェックリスト

• 網羅性：papers/core_set.csv 内のすべての paper_id が papers/paper_notes.jsonl に含まれている。

• 優先度の高い論文に、TODO ではない method／結果／制限事項が記載されている。

• 多くの論文で制限事項がコピー＆ペーストされていない。

• evidence_level が正しく設定されている（abstract 対 fulltext）。

• エビデンスバンク：papers/evidence_bank.jsonl が存在し、選択したプロファイルの要件を満たしている（コース論文は4件以上、A150++ は論文あたり平均7項目以上）。

ヘルパースクリプト（任意）

クイックスタート

• uv run python .codex/skills/paper-notes/scripts/run.py --help
• uv run python .codex/skills/paper-notes/scripts/run.py --workspace <workspace>

すべてのオプション

• --help を参照してください（このヘルパーは意図的に最小限の機能にしています）

例

• ノートを生成した後、必要に応じて priority=high の論文を充実させます。
  • ヘルパーを1回実行し、その後 papers/paper_notes.jsonl を修正します（例：主要な論文に全文の詳細を追加し、制限事項に多様性を持たせます）。

注意事項

• ヘルパーは、決定的なメタデータ／アブストラクトレベルのノートを書き込み、主要な論文に priority=high のマークを付けます。
• pipeline.py --strict では、優先度の高いノートが未完成（method／key_results／limitations が不足）またはプレースホルダーを含む場合、処理がブロックされます。

トラブルシューティング

よくある問題

問題：優先度の高いノートが依然として雛形のように見える

症状：

• 品質ゲートで method/key_results の不足、または TODO プレースホルダーが報告される。

原因：

• ノートがアブストラクトのみから生成され、主要な論文が充実化されていない。

解決策：

• priority=high の論文を十分に充実させます。method、1件以上の key_results、3件以上の summary_bullets、具体的な limitations を1件以上記載してください。
• 全文のエビデンスが必要な場合は、主要な論文に対して pdf-text-extractor を fulltext モードで実行します。

問題：複数の論文で制限事項が繰り返される

症状：

• 品質ゲートで、制限事項の定型文の繰り返しが報告される。

原因：

• 論文固有の失敗モード／前提条件ではなく、制限事項がコピー＆ペーストされている。

解決策：

• 定型文を、論文固有の制限事項（設定、データ、評価の不足、失敗事例）に置き換えます。

復旧チェックリスト

• papers/paper_notes.jsonl が papers/core_set.csv 内のすべての paper_id を網羅している。
• priority=high のノートの80％以上で、method／結果／制限事項がそろっている。
• 優先度の高いノートに TODO が残っていない。