systematic-literature-review

システマティック・レビュー

bensz-collect-bugs との連携ルール

• ユーザー環境でこのスキルの設計上の欠陥に起因するバグが発生した場合は、bensz-collect-bugs を使って、規定に従い ~/.bensz-skills/bugs/ に記録することを優先してください。ユーザーのローカル環境にある Claude Code / Codex にインストール済みのスキルのソースコードを直接変更することは厳禁です。
• AI が回避策を使ってユーザーのタスクを続行できる場合は、先にバグを記録してから、現在のタスクを完了してください。
• ユーザーが「report bensz skills bugs」など、公開の報告を明確に要求した場合は、ローカルの gh と bensz-collect-bugs を呼び出し、新規バグのみを huangwb8/bensz-bugs にアップロードしてください。バグリポジトリ全体の pull / clone はしないでください。

位置づけ

• 目標：隔離された作業ディレクトリ内で、「検索 → 重複排除 → スコアリング → 文献選定 → 執筆 → 検証 → PDF/Word エクスポート」までの完全なレビューのパイプラインを実行します。
• 対象：ユーザーがシステマティック・レビュー、文献レビュー、関連研究、文献調査を明確に希望し、LaTeX + BibTeX + PDF/Word の成果物を求めている場合。
• 対象外：参考文献を1件だけ追加したい場合、既存本文の推敲のみを希望する場合、一般的な要約のみを希望する場合、またはレビューに関係のない記事を執筆したい場合。
• 最優先の原則：利用可能な最良のエビデンスと執筆品質に基づいてレビューを完成させます。不確かな場合は対応方法を明記し、急ぐために信頼性を犠牲にしないでください。

入力

最低限必要なもの：

1. {主题}：一文で示したテーマ。
2. 任意の範囲：期間、言語、研究の種類、データベースの希望など。
3. プラン：Premium / Standard / Basic。指定がない場合は config.yaml のデフォルト値を読み込みます。
4. 目標文字数と参考文献の範囲：指定がない場合は config.yaml.scoring.default_*_range に従います。
5. 出力ディレクトリまたはサニタイズ済みのプレフィックス：指定がない場合はサニタイズしたテーマ名を使用します。

出力

デフォルトで以下の主要ファイルを納品します：

• {主题}_工作条件.md：入力、検索、スコアリング、文献選定、構成、検証の記録。
• {主题}_review.tex：本文の唯一の LaTeX ソースファイル。
• {主题}_参考文献.bib：選定文献の BibTeX。
• word_budget_run{1,2,3}.csv、word_budget_final.csv、non_cited_budget.csv：レビューの文字数予算。
• {主题}_验证报告.md：文字数、章、引用の整合性などの検証結果。
• {主题}_review.pdf
• {主题}_review.docx

必要な中間成果物：

• papers*.jsonl
• scored_papers.jsonl
• selected_papers.jsonl
• selection_rationale.yaml
• 任意の evidence_cards_{主题}.jsonl

必須要件

• PDF と Word のエクスポートは必須です。明確な失敗とその理由を記録した場合に限り、出力がなくてもかまいません。
• 本文の文字数と参考文献数は、現在のプランの範囲内に収めてください。ユーザーによる上書きが可能で、デフォルト値は config.yaml に従います。
• 本文には必ず、要旨、序論、少なくとも1つのサブテーマの節、考察、今後の展望、結論を含めてください。
• \cite{key} は BibTeX の key と一致していなければなりません。不一致はエラーとして報告してください。
• 本文で AI のワークフローを明かすことは禁止です。「検索／重複排除／スコアリング／文献選定／文字数予算」などのメタナラティブは {主题}_工作条件.md にのみ記載してください。
• 要旨は単一段落とし、方法論の羅列を避けてください。表の幅とスタイルの制約については references/review-tex-section-templates.md を参照してください。
• 引用数を満たすために低スコアの文献を積み上げないでください。確認できない場合は、変更せず、引用しないことを優先してください。

主な手順

0. 準備

• テーマ、プラン、文字数／参考文献の範囲、出力ディレクトリを記録します。
• 開始前に、以下を優先して読みます：
  • references/ai_query_generation_prompt.md
  • references/ai_scoring_prompt.md
  • references/expert-review-writing.md
  • references/review-tex-section-templates.md
  • 翻訳を行う場合は references/multilingual-guide.md も読みます。

1. 複数クエリでの検索

• AI がテーマに合わせたクエリのバリエーションを計画します。通常は5～15組です。
• OpenAlex を優先し、必要に応じて config.yaml.search.provider_priority に従って自動的にフォールバックします。
• 検索結果を Search Log に記録します。再開時に papers のパスが無効になっている場合は、クリーンアップしてから再検索してください。

2. 重複排除

• dedupe_papers.py を使って、重複排除済みの結果と対応表を生成します。
• 以降のすべての処理では、重複排除後の候補セットのみを読み込みます。

3. AI によるスコアリングとデータ抽出

• AI は references/ai_scoring_prompt.md に従い、各文献のタイトルと要旨を読み、scored_papers.jsonl を出力します。
• 各文献には少なくとも score、subtopic、rationale、alignment、extraction を含めてください。
• スコアの範囲は1～10点に固定します。関連性の低い論文がサブテーマの計画に影響しないよう、5点以上の文献にのみサブテーマを割り当ててください。
• スコアの分布が適切かどうかを自己検証してください。高スコアは約20～40％、中スコアは40～60％、低スコアは10～30％を目安とします。

4. 文献選定と Bib の生成

• select_references.py で、目標とする参考文献の範囲と高スコア文献の優先割合に基づき、最終的な文献セットを選定します。
• selected_papers.jsonl、references.bib、selection_rationale.yaml を生成します。
• Bib のクリーニングでは、大文字と小文字を区別しない key の重複排除、LaTeX の特殊文字のエスケープ、フィールド欠落の警告を必ず保持してください。
• 要旨がない、または短すぎる項目には do_not_cite のフラグを付け、レポートで要旨の網羅率に関するリスクを示してください。

5. サブテーマと配分の計画

• AI はスコアリング結果に基づいて3～7個のサブテーマを計画し、段落ごとの配分を提示します。
• デフォルトの目安は、序論が約1.5k文字、考察と今後の展望がそれぞれ約1k文字、結論が約0.6k文字で、残りをサブテーマの節に配分します。
• 結果を作業条件とデータ抽出表に記録し、執筆の指針とします。

6. 文字数予算

• plan_word_budget.py で3つの予算 CSV を生成し、word_budget_final.csv にまとめます。
• 引用がある段落と引用のない段落の両方を予算に含めてください。合計文字数の誤差は config.yaml.word_budget.tolerance の範囲内に収める必要があります。

7. 執筆

• 本文の章構成は、要旨、序論、サブテーマの節、考察、今後の展望、結論で固定します。
• 執筆前に word_budget_final.csv を読み、文献のレビューと記述に関する予算に沿ってエビデンスを構成します。
• デフォルトでは、個別文献の引用を優先します。引用は裏付けとなる主張の直後に置き、段落末にまとめて並べることを避けてください。
• 詳細な執筆規範が必要な場合は、以下に直接従ってください：
  • references/expert-review-writing.md
  • references/review-tex-section-templates.md

8. 自然な加筆と検証

• 文字数が不足している場合は、最短またはエビデンスが不足しているサブテーマの節のみ、部分的に加筆できます。新しいサブテーマを追加せず、元の主張と引用を変更しないでください。
• 以下を順に実行します：
  • validate_counts.py
  • validate_review_tex.py
  • 任意の validate_word_budget.py
  • generate_validation_report.py

9. エクスポートと多言語対応

• compile_latex_with_bibtex.py で PDF を生成します。
• convert_latex_to_word.py で Word を生成します。
• ユーザーが多言語版を求めている場合は、multi_language.py で本文を翻訳してスマートコンパイルします。失敗した場合はエラーレポートと broken ファイルを保持し、バックアップからの復元を優先してください。

作業ディレクトリとファイルの分離

• すべての中間ファイルを {work_dir}/.systematic-literature-review/ に書き込む必要があります。
• 最終成果物は作業ディレクトリのルートに配置します。
• AI の一時スクリプトは {work_dir}/.systematic-literature-review/scripts/ に配置する必要があります。
• 一時ファイルを作業ディレクトリのルートに書き込まないでください。/tmp/* への絶対パス指定で書き込まず、他の run ディレクトリの読み書きも行わないでください。
• 環境変数 SYSTEMATIC_LITERATURE_REVIEW_SCOPE_ROOT と SYSTEMATIC_LITERATURE_REVIEW_SCRIPTS_DIR を基準にしてください。

主なコマンド

# 推荐主入口
python3 scripts/run_pipeline.py --topic "{主题}" --runs-root runs

# 旧入口 / resume
python3 scripts/pipeline_runner.py --topic "{主题}" --domain general --work-dir runs/{safe_topic}
python3 scripts/pipeline_runner.py --resume runs/{safe_topic}

# 阶段 3 评分后，从第 4 阶段继续
python3 scripts/pipeline_runner.py --resume runs/{safe_topic} --resume-from 4

环境与脚本

• 运行环境：Python 3.9+、LaTeX（xelatex/bibtex）、pandoc。
• 关键脚本：
  • 检索：multi_query_search.py、openalex_search.py
  • 去重：dedupe_papers.py
  • 选文：select_references.py、build_reference_bib_from_papers.py
  • 数据抽取：update_working_conditions_data_extraction.py
  • 字数预算：plan_word_budget.py、validate_word_budget.py
  • 校验：validate_counts.py、validate_review_tex.py、generate_validation_report.py
  • 导出：compile_latex_with_bibtex.py、convert_latex_to_word.py

可选：成本追踪

• 初始化：python3 systematic-literature-review/scripts/pipeline_cost.py init
• 抓取定价：python3 systematic-literature-review/scripts/pipeline_cost.py fetch-prices
• 记录 token：pipeline_cost.py log ...
• 汇总：pipeline_cost.py summary
• 所有成本数据写到 .systematic-literature-review/cost/

参考材料

• references/ai_query_generation_prompt.md
• references/ai_scoring_prompt.md
• references/expert-review-writing.md
• references/review-tex-section-templates.md
• references/multilingual-guide.md
• references/development-validation-guide.md