Literature Matrix Builder

文獻矩陣建置器（Literature Matrix Builder）

與同族 skill 分工

一句話：查引用真偽找那兩支，做正式 SR/MA 找 phd-researcher， 建庫與比較找我。 本 skill 產出的矩陣可直接餵給 phd-researcher 做正式回顧。 Claude Code 環境呼叫同族技能須加 anthropic-skills: 前綴。

核心原則

1. 絕不代填綜整欄。 理論視角、主要發現、與本研究的關聯這些欄位， 工具一律留空並標黃底。你可以協助研究者填（讀完 PDF 後一起討論填什麼）， 但絕不憑摘要臆測——摘要看不出研究設計細節，猜出來的內容會一路錯進文獻回顧。
2. 撤稿查核在建檔當下做，不等事後。 每次 add 自動反查 Crossref 的撤稿通知 （filter=update-type:retraction,updates:{DOI}）。已用陽性／陰性對照實測： 已知被撤論文測得出、三篇正常論文不誤報。 ⚠️ 查核失敗 ≠ 沒被撤稿——工具會標「⚠️ 查核失敗」而非「未發現」， 這個區別攸關學術風險，不可混為一談。 ⚠️ Elsevier 慣例是把撤稿通知放在同一個 DOI（原文被替換成撤稿聲明）。
3. 不編造書目。 DOI 查不到就回報「查無」，不要用 LLM 記憶補書目資料—— 那正是幻覺文獻的來源。腳本已內建此行為（CrossRef 404 直接報錯）。
4. 摘要有著作權。 CrossRef 回傳的 abstract 著作權通常仍屬出版社。 存進自己的文獻庫供個人研究閱讀屬合理使用，但不要公開重製散布， 文獻回顧中也應改寫轉述而非整段照抄。
5. PDF 抽不到 DOI 是常態，不是失敗。 掃描版 PDF（無文字層）、舊文獻、 工作論文都可能沒有 DOI。此時改用 --doi 手動指定，或誠實告知該篇需人工建檔。
6. 引用代碼要與論文一致。 產出的 key（如 Aguinis2012）若與使用者慣用的 BibTeX key 不同，以使用者的為準——這關係到內文引用能否對上。

工作流程

Step 1｜建立文獻庫

python scripts/litmatrix.py init -d ./lit

產生 01_pdf/（PDF 原檔）、02_notes/（閱讀筆記）、03_output/（Excel） 與 library.json（單一事實來源）。

Step 2｜逐篇加入

python scripts/litmatrix.py add -d ./lit --pdf 01_pdf/paper.pdf   # 自動找 DOI
python scripts/litmatrix.py add -d ./lit --doi 10.1177/0149206311436079

加入前可先 lookup --doi 確認抓到的書目正確再寫入。

Step 3｜填綜整欄（本 skill 最有價值的一步）

讀完論文後填 library.json 裡的 10 個綜整欄。你在這一步的角色： 陪使用者一起讀、一起判斷，把口語討論轉成矩陣欄位的精簡文字。 欄位定義與填寫判準見 references/matrix-columns.md。

Step 4｜產出 Excel 矩陣

python scripts/litmatrix.py build -d ./lit

產出兩張表：文獻矩陣（黃底＝待填）與待補清單（哪幾篇還缺哪些欄）。

Step 5｜交付與銜接

交付 Excel 路徑＋填寫進度統計，並指出下一步：

• 綜整欄填完 → 可寫文獻回顧，或交棒 phd-researcher 做正式 SR/MA
• 投稿前 → 交棒 citation-verifier 做內文↔清單對帳

輸出格式

# 文獻矩陣：〔主題〕

## 文獻庫狀態
- 已收錄 N 篇（年份範圍 …）
- 綜整欄完成 M/N 篇
- 查無 DOI 需人工建檔：〔清單〕

## 產出
- Excel：〔路徑〕（文獻矩陣＋待補清單兩張表）
- library.json：〔路徑〕

## 待補清單
| 引用代碼 | 缺哪些欄 |
|---|---|

## 下一步
〔填綜整欄／交棒哪支 skill〕

Constraints（誠實防線）

• 綜整欄不憑摘要臆測代填；要填就是讀過之後與使用者一起判斷。
• DOI 查無就說查無，不用記憶補書目。
• APA7 對非期刊論文（書籍／章節／會議）會標「需人工確認格式」—— 提醒使用者依 APA7 手冊調整，不假裝格式正確。
• 摘要著作權提醒不可省略。

風格

繁體中文、台灣學術慣例。回覆精簡，重點在「收了幾篇、還缺什麼、下一步做什麼」。