manage-refs

Manage-Refs スキル

決定木からツールを選択し、並行する別のパイプラインを作らないでください。参考文献リストを手入力することはありません。リストは常に、pandoc citeproc とジャーナルの CSL、または Zotero Word プラグイン（CWYW）によって生成されます。このスキルは、参考文献の書き込み（生成、挿入、変換）を行います。PubMed／CrossRef に照らした書誌情報の正確性の確認は /verify-refs の担当です。読み取り専用の監査を 1 つ、書き込みを行うものを 1 つに分けます。

決定木

状況	ツール	理由
[@bibkey] と refs.bib の照合（UNDEFINED／UNUSED キー）	scripts/check_citation_keys.py	ビルドを確実に止めるチェックで、数秒で実行できます
単著投稿向けの固定化、出力の凍結	scripts/render_pandoc.sh -j <journal>	再現性があり、CI に適しています
投稿先の変更による連続不採択（例：ER → JVIR → CVIR）	新しい -j を指定した render_pandoc.sh	CSL の差し替えにより、数秒で参考文献の書式を変更できます
投稿先の CSL で、本文中の引用形式／DOI／雑誌名のスタイルが実際に投稿規定どおりに出力されるかを確認	scripts/check_csl_render.py --csl <x>.csl --bib refs.bib --journal <key> --md manuscript.md	スタブ／「従属」CSL は親の書式を継承しますが、その書式が投稿規定と異なる場合があります（括弧付きか上付きか、DOI を残すか、雑誌名を完全表記するかなど）。--md は pandoc が引用として読み取るキーのみを判定します（nocite: '@*' は参考文献全体）。雑誌名としてプレプリントサーバーが指定されている場合（journal = {arXiv}）は略称チェックの対象外です。--journal／--expect-* を指定しない場合、結果は NOT_ASSESSED（終了コード 2）となり、PASS にはなりません。仕様キーとチェック対象外の項目：references/REFERENCE_STYLE_SPECS.md。校正 PDF の確認後ではなく、投稿前に実行してください
参考文献リストに雑誌名が完全表記で出力されるが、投稿先は NLM 略称を要求している	scripts/fill_journal_abbrev.py --bib refs.bib --out refs_abbrev.bib	PubMed（PMID、取得できない場合は DOI → PMID）から shortjournal を取得し、次に CrossRef の short-container-title を取得して、各項目に設定します（多くの場合 ISO 4 のピリオド付きで、NLM とは異なるため確認してください）。各項目のインデントに合わせて雑誌名フィールドの後に挿入し、既存の値は上書きせず、書き込み前に再解析します。終了コード 1 は、一部の検索に失敗したことを示します。Better BibTeX 管理下の bib では、代わりに Zotero の「Journal Abbr」を入力してください
査読者の指摘への修正：共著者が作業中の Word 文書に参考文献を 1～2 件追加	Zotero Word プラグイン（ユーザー GUI）	変更履歴を使った作業フローへの影響を最小限に抑えます
査読者の指摘への修正：参考文献をまとめて変更	Markdown の SSOT を編集し、render_pandoc.sh を再実行	整合性を保ち、チェリーピックのリスクを避けます
pandoc 用に [N] の番号マーカーを [@key] に変換	scripts/md_marker_convert.py --to-keys	マッピングに基づいて変換するため、部分的な変換でも安全です
往復変換／デバッグ用に [@key] を [N] に変換	scripts/md_marker_convert.py --to-numbers	同じマッピングで逆方向に変換します
ネイティブ Zotero CWYW フィールドコードを .docx に組み込み、Word でライブ更新できるようにする	scripts/inject_zotero_cwyw.py	共著者との Word ワークフローや、回覧後の編集可能性に適しています
原稿とレンダリング済み DOCX の相互参照 QC	scripts/check_xref.py --strict	投稿時のゲート（不一致は P0 のブロッカー）
図表を別添ファイルとして提出（放射線医学および多くの医学系雑誌）	check_xref.py --strict --allow-separate-attachments	MISSING_DOCX を WARN に格下げします。MISSING_BODY／MISMATCH は引き続き P0 です
v_(N+1) の DOCX ビルド時再生成チェック	check_xref.py --vN-docx-md5 <prev>.docx [--vN-md <prev>.md]	同一性は未変更のシードコピーで判定します。差分行が欠落している場合、本文が再生成されていません
ビルド成果物内の参考文献の重複	scripts/check_reference_duplication.py --docx <built>.docx（または --text <rendered>.md）	DUP_REF_HEADING／REF_NUMBER_RESTART／REF_SIGNATURE_DUP（Major）を検出します。手入力の ## References リストと pandoc の --citeproc による自動参考文献が併存し、リストが 2 つ出力されるケース（2 つ目は凡例の後に出力されることがよくあります）を検出します。citeproc を使ったビルドの後に実行してください
.bib のタイトル内の出版社マークアップ（出力が文字化け）	scripts/check_bib_title_markup.py --bib refs.bib --strict	CrossRef のタイトルには <scp>WHO</scp>／<i>IDH</i> が含まれることがあります。BBT はこれらを {$<$}scp{$>$} のようにエスケープするか、スペースを戻さずに削除します（andTERTPromoter）。verify_refs は参考文献が「正しい」ことを確認し、こちらは正しく「出力される」ことを確認します。TITLE_MARKUP／TITLE_FUSION（Major）
投稿前の総合ゲート（投稿前の実行を推奨）	scripts/pre_submission_gate.sh	check_citation_keys → check_bib_title_markup → verify_refs --strict → render_pandoc（任意） → check_xref --strict を順に実行します。単一の成果物は qc/pre_submission_gate.json です
参考文献監査を内蔵した直接レンダリング	scripts/render_pandoc.sh（最初に /verify-refs で .bib を監査し、FABRICATED／MISMATCH／重複があれば停止します。UNVERIFIED の行はクリーンではないものとして報告しますが、処理は停止しません。レンダリング後、shortjournal がない引用済み雑誌項目について警告します。このスタイルでは雑誌名が完全表記で出力されます）	ベストエフォートです（/verify-refs が同じ場所にない場合は警告を出してスキップします）。-S で無効にできます。総合ゲートではステージ 3 で verify_refs を実行するため、-S を渡します
PubMed／CrossRef に基づく書誌監査	/verify-refs に委任	監査のみを行います。執筆者と監査者を分離してください

ワークフロー

A. Pandoc citeproc（単著者および最終提出向けのデフォルト）

ユーザーが [@bibkey] 形式の引用を含む manuscript.md と refs.bib を用意します。

1. 確認：python3 "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib — UNDEFINED キーがあると、ゼロ以外の終了コードを返します。修正して再実行してください。/write-paper が作成する [@NEW:topic_slug] の執筆用プレースホルダーも UNDEFINED として報告されます。各プレースホルダーについて、Zotero に引用文献を追加し（/lit-sync によって refs.bib が更新されます）、実際の [@bibkey] に置き換えてください。[@NEW:...] をレンダリング済み DOCX に残さないでください。
2. レンダリング：

   "${CLAUDE_SKILL_DIR}/scripts/render_pandoc.sh" \
     -j european-radiology \
     -i manuscript.md \
     -b refs.bib \
     -o manuscript_final.docx
   

   現在のスタイル一覧と各スタイルのレンダリング内容については、citation_styles/README.md を参照してください。この表がスタイルの登録簿です。-j で指定したスタイルが見つからない場合、render_pandoc.sh はディスク上にあるスタイルも一覧表示します。そのため、ここに記載された一覧を鵜呑みにせず、スクリプトに確認してください。継続して使用するフォールバックは 2 つあります。RYAI には radiology、JVIR には vancouver を使用してください（どちらにも専用の CSL はありません）。 引用キーが .bib に存在しない場合、レンダリングは終了コード 5 で終了し、そのキーを示します。pandoc は出力内で (key?) と表示しますが、それ自体では失敗しません。
3. 品質チェック：

   python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \
     --md manuscript.md --docx manuscript_final.docx \
     --out qc/xref_audit.json --strict
   

   submission_safe: false は停止指示として扱ってください。症状に応じて修正先を判断してください。references/check_xref_symptoms.md の表を参照してください。
4. 監査の引き継ぎ：サインオフ前に、PubMed／CrossRef 監査を /verify-refs で実行してください。

B. Zotero CWYW（共著者向けの Word ワークフロー）

ユーザーは Markdown の SSOT を持ち、査読者が Word で引用を直接編集できるようにしたいと考えています。各文献はすでに Zotero アイテムとして登録されている必要があります。ユーザーから [N] → ZoteroKey の対応表が提供されます。

1. マーカーを変換：

   python3 "${CLAUDE_SKILL_DIR}/scripts/md_marker_convert.py" \
     --input manuscript.md --output manuscript_keys.md \
     --map ref_map.json --to-keys
   

   変換処理で番号に対応する Zotero キーを推測することはありません。対応表にないマーカーは [N] のまま残り、stderr に報告され、スクリプトは終了コード 1 で終了します（部分出力は書き込まれます。受け入れる場合は --allow-partial を指定してください）。[1-3] のような範囲は展開されます。角括弧で囲まれた数字はすべてマーカーとして扱われるため、角括弧で囲まれた年（[2019-2021]）も UNMAPPED として報告されます。必要に応じて、まず --active-ns 1,2,3,4,19 を指定してサンプルを作成できます（5 件の文献を使ったサンプルなら、デバッグ中に Word Refresh の影響範囲を抑えられます）。
2. pandoc で .docx にレンダリングし（ワークフロー A）、本文にプレーンテキストの [@key] マーカーが含まれるようにします。または、別の方法で事前に .docx を作成し、プレーンテキストの [@key] が含まれる状態にします。
3. CWYW を挿入：

   python3 "${CLAUDE_SKILL_DIR}/scripts/inject_zotero_cwyw.py" \
     --input manuscript_keys.docx --output manuscript_cwyw.docx \
     --user-id <zotero-user-id> --keys-from keys.txt
   

   スクリプトはローカルの Zotero コネクター（ポート 23119）からアイテムのメタデータをライブで取得するため、Zotero がローカルで起動している必要があります。Web API によるフォールバックはありません。HTTP エラーが発生するとゼロ以外の終了コードで中止されるため、不完全な参考文献リストがユーザーに渡ることはありません。Zotero のメタデータを捏造しないでください。
4. 初回ビルドの手順（必須）：スクリプトは空の ADDIN ZOTERO_BIBL スタブを書き込みます。Word の Zotero Refresh はこれをユーザーがカスタマイズしたものとみなし、内容の挿入を拒否します。出力ファイルを Word で開き、Zotero タブから Add/Edit Bibliography を一度実行してください。その後は、著者が編集するたびに Refresh を実行すれば引用と参考文献リストが同期されます。
5. 局所的なパッチ適用は安全ではありません：後続の作業で文献を追加する場合は、Markdown の SSOT を編集して .docx 全体を再ビルドしてください。CWYW 適用後のファイルに正規表現でパッチを適用しないでください。Zotero がレンダリングした [N] の上付き文字とプレーンな [N] マーカーが衝突し、フィールドコードが破損する可能性があります。

C. リジェクト後のカスケード再レンダリング（ジャーナル検索の引き継ぎ）

ユーザーがジャーナル A からリジェクトされ、/find-journal がジャーナル B を推奨しました。

1. 新しい CSL が citation_styles/ にあることを確認します（または https://citationstyles.org/styles から取得して配置します）。
2. 同じ manuscript.md と refs.bib を対象に、render_pandoc.sh -j <new-csl> を再実行します。
3. check_xref.py --strict を再実行します。
4. ジャーナル間の改訂で新しい文献を追加した場合は、/verify-refs を再実行します。

D. 相互参照の QC のみ

ユーザーが原稿を提出したところ、査読者から表／図の不一致を指摘されました。

1. 現在の manuscript.md と .docx に対して check_xref.py --strict を実行します。

2. qc/xref_audit.json を確認します。本文のキャプションが SSOT です。manuscript.md を修正して再ビルドし、.docx を手作業で修正してはいけません。

3. MISSING_BODY／MISSING_DOCX／MISMATCH のトリアージ表については、references/check_xref_symptoms.md を参照してください。

4. 図と表を個別の添付ファイルとして受け付けるジャーナル（European Radiology、Radiology、AJR、JVIR、KJR、および大半の医学ジャーナル）では、--allow-separate-attachments を渡します。このオプションは、根拠が異なるため別々に報告される次の 2 つの行の重大度を引き下げます。

   • MISSING_DOCX — --docx が指定され、レンダリングされた本文書にフロートが含まれていないことが確認された場合です。個別の添付ファイルはこのようになります。
   • MISSING_BODY で、--docx が指定されていない場合 — 何も確認されていません。申告に基づいて免除され、EXCUSED WITHOUT EVIDENCE として出力され、summary.downgraded_unchecked に計上されます。

   MISMATCH は引き続き P0 です。レンダリングされた DOCX にフロートが含まれている場合の MISSING_BODY も同様です。これは SSOT のずれであり、添付ファイルに関するどのような方針でも免除されません。

   提出前に、--docx を指定して一度実行してください。 このフラグは申告であり、検証ではありません。DOCX を指定することで初めて、申告が根拠に変わります。

D'. v_(N+1) docx の再生成チェック（ビルド時の補助チェック）

固定された v_N から v_(N+1) をビルドする際、v_(N+1) の docx は内容が v_N の docx と異なっていなければなりません。同一バイトのコピーは、査読時に markdown の編集内容を巻き戻してしまう、気付かれにくいシードコピーです。check_xref.py には、/sync-submission の scripts/verify_package_integrity.py --assert-vN-docx-changed による提出時チェックを補完するビルド時チェック用のフラグが 2 つあります。

python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \
    --md manuscript_v2.md \
    --docx manuscript_v2.docx \
    --vN-docx-md5 manuscript_v1.docx \
    --vN-md manuscript_v1.md \
    --strict

• --vN-docx-md5 のみ：MD5 の同一性チェックです。バイト列が同一なら FAIL になります。
• --vN-docx-md5 + --vN-md：さらに、v_N と v_(N+1) の markdown のみの差分を抽出し、40 文字以上の差分行がそれぞれ、新しい docx の本文 XML にそのまま（空白を正規化し、大文字小文字を区別せずに）含まれていることを検証します。差分行が見つからない場合は、本文に markdown の編集内容が反映されていません。

結果は qc/xref_audit.json の vN_docx_check に記録されます。どちらの失敗モードでも、--strict がなくても終了コードは 0 以外になります。

E. 提出前のマスターゲート（エンドツーエンドのチェーンを推奨）

ワークフロー A と D、および /verify-refs を組み合わせた、単一のエントリーポイントによる中断型チェーンです。提出直前、または v_N パッケージを上級共著者に回覧する前に使用してください。

bash "${CLAUDE_SKILL_DIR}/scripts/pre_submission_gate.sh" \
    --md manuscript/manuscript.md \
    --bib manuscript/_src/refs.bib \
    --docx submission/<journal>/manuscript.docx \
    --allow-separate-attachments    # omit if the journal accepts inline figures/tables

ステージの順序（最初の失敗で中断します）：

1. check_citation_keys.py manuscript.md refs.bib — 未定義／未使用のキー
2. check_bib_title_markup.py --strict — .bib のタイトルにおける出版社のマークアップ／タグ除去による文字列の融合
3. verify_refs.py refs.bib --strict — エントリーごとの PubMed／CrossRef 検証
4. render_pandoc.sh -S -j <csl> -i ... -b ... -o ... — --docx が省略された場合にのみ実行します （--journal <csl>、既定値は vancouver）
5. check_xref.py --md ... --docx ... --strict [--allow-separate-attachments]

成功すると、チェーンは submission_safe: true を含む qc/pre_submission_gate.json（および各ステージの成果物 qc/bib_title_markup.json、qc/reference_audit.json、qc/xref_audit.json）を書き込みます。失敗時は、JSON に失敗したステージと終了コードが記録され、スクリプトは 0 以外で終了します。失敗したステージが合格するまで提出しないでください。

このゲートはどのチェックも再実装しません。既存のスクリプトをサブプロセスとして呼び出します。新しいチェックは基盤となるスクリプトに追加してください。追加後、ゲートにも反映されます。

F. BibTeX の著者形式の破損（表示名の確認）

author = {Surname AB and Surname2 CD}（姓＋イニシャル、カンマなし）の形式で記述された項目は、BibTeX に最後のトークンを姓として扱わせるため、「AB S, CD S2」と表示されます。必ず author = {Family, Full Given} の形式で保存してください。カンマがあってもイニシャルを連結した形式（Family, AB）では、CSL の initialize-with によって単一のイニシャルにまとめられるため、PubMed の efetch からフルネームを使用してください。

/verify-refs は BibTeX の内容と PubMed を照合しますが、表示された出力は確認しません。レンダリングされた docx と BibTeX を個別に grep してください：

unzip -p out.docx word/document.xml | sed 's/<[^>]*>//g' | grep -oE "[A-Z]{2} [A-Z], [A-Z]{2} [A-Z]"   # corruption signature in output
grep -nE 'author\s*=\s*\{[A-Z][a-z]+ [A-Z]{1,3}( |\})' refs.bib                                          # no-comma source entries

品質ゲート

このスキルには、3 つの提出ゲートと1 つのユーザー承認ゲートがあります。

• ゲート 1（引用キーの整合性）：check_citation_keys.py は、未定義のキーがあるとゼロ以外の値で終了します。パイプラインは停止し、ユーザーが確認して修正します。
• ゲート 2（相互参照の整合性）：check_xref.py --strict は、MISSING_DOCX／MISSING_BODY／MISMATCH の行があると 1 で終了します（Markdown で定義されているものの DOCX にない図表は、本文中の引用が認識されていなくても MISSING_DOCX になります。HTML コメント内またはフェンス付きコード内の凡例はレンダリングされないため、UNCITED のままです）。--docx を指定して python-docx がない場合は 2 で終了します。これは DOCX の監査が実行されなかったことを意味します。ユーザーは続行する前に qc/xref_audit.json を確認し、問題を解決します。--allow-separate-attachments を指定した場合は、submission_safe だけでなく summary.downgraded_unchecked も確認してください。ゼロ以外の値は、確認されずに通過した行があることを意味します。
• ゲート 3（監査の引き継ぎ）：承認前に、ユーザーは /verify-refs を実行し、qc/reference_audit.json で submission_safe: true であることを確認する必要があります。このスキルが独自に参考文献を監査済みとすることはありません。
• ユーザー承認ゲート（CWYW の初回ビルド）：最初の inject_zotero_cwyw.py によるビルド後、ユーザーは Word → Zotero → Add/Edit Bibliography を手動で実行する必要があります。この操作はスキルでは自動化できず、必要であることを stderr に警告します。

出所

scripts/_vendor_citation_writer.py は alisoroushmd/zotero-mcp @ ed5dfb71 からベンダリングしたもので、MIT ライセンスです。NOTICE.md および LICENSE.zotero-mcp を参照してください。

既知の制限事項

• ウェブページ／非ジャーナルの項目タイプ：Zotero のネイティブ CSL-JSON を取得するパッチ適用済みの zotero_to_csl_json で処理します。このパッチを迂回しないでください。
• 「Table 1 and 2」（単数形の種類語＋番号リスト）：check_xref.py はこの表現から Table 1 しか読み取りません。本文中の「and」に続く単独の数字も解析すると、「Table 1 and 2 patients」を引用として読み取ってしまうためです。Markdown で定義されているものの DOCX にない図表は、引き続き MISSING_DOCX としてブロックされます。定義もレンダリングもされていないものは検出されません。「Tables 1 and 2」または「Table 1 and Table 2」と記述してください。