paper-review + paper-digest

Two Claude Code skills for reading a single academic paper properly — one appraises whether it can be trusted, the other absorbs what it says. Built by a practising physician for real journal-club and clinical use, then generalized for sharing.

🔭 Discovery paper-radar ｜ ⬇️ Download paper-fetch ｜ 📖 Reading paper-review-and-digest — a literature radar finds and ranks papers, a route-ladder fetcher gets their full text, and these skills appraise and digest them; together the three repos form the full paper pipeline.

English · 繁體中文

What this is

Reading a paper well is really two different jobs, and good readers keep them separate:

They are independent and can both run on one paper.

Part of a pipeline. These skills are the reading end. The discovery end — a personal literature radar that pulls dozens of journal feeds + PubMed searches, ranks them by your interest model, and hands the picks off for appraisal/digest — is paper-radar. paper-radar's /paper-sync dispatches a picked paper straight into /paper-review (🔬 quality) or /paper-digest (📚 content). Use them together, or either alone.

Why it isn't just a clever prompt

Most "AI paper review" tools make two claims loosely — that they grade the evidence and that they catch spin. Here those claims are made true by real, deterministic code. The split is the whole point: the language model does semantic judgement; a program does the logic and the arithmetic.

grade_judge.py — GRADE as arithmetic, not vibes

The model rates the five GRADE domains (risk of bias, inconsistency, indirectness, imprecision, publication bias) as not serious / serious / very serious. A pure-stdlib script then recomputes the final certainty from the starting level and the summed downgrades/upgrades, clamped to [Very low … High]. The model's self-reported grade is advisory only; the script's number is authoritative, and it warns when the two disagree. It also enforces GRADE rules the model tends to forget — e.g. observational evidence can't be upgraded once any domain is downgraded.

argdown_lint.py — inference gaps as a real gate

The model tags each supporting finding by premise type (direct_rct, association, surrogate_outcome, single_study, subgroup, secondary_outcome, mechanistic, expert_opinion). A stdlib script then deterministically flags the illicit jumps and exits nonzero:

• surrogate outcome → hard-endpoint / causal benefit claim
• association → causal claim
• single study → "consistently shown"
• subgroup / secondary outcome only → benefit claim (classic spin)

CrossRef existence gate

Before any semantic citation comparison, each selected reference is checked against the live CrossRef API — catching fabricated DOIs and "right DOI, wrong paper" swaps that a purely semantic read misses. (Unaudited LLM-written citations run ~40–80% accuracy; this is the cheap deterministic guard.)

Delegated fan-out, and failures reported as gaps

The deep review keeps the intelligence-bound work (reading the paper once, appraisal, GRADE) in the main context and delegates the fan-out lookups — author profiling, reference verification, citation / PubPeer sweeps — to parallel subagents, so raw search dumps never bloat the analysis. Every lookup that fails is reported as an explicit gap ("PubPeer sweep: FAILED / no hits"), never silently dropped — an unrun check must not read as "nothing found".

Design-routed risk of bias (not one checklist)

Observational studies additionally get checked against 35 bundled causal-inference doctrines (causal-appraisal.md, digesting Hernán & Robins and the Users' Guides to the Medical Literature).

Quick sanity check

cd paper-review
# GRADE: RCT starting High, two 'serious' domains → Low
echo '{"starting_level":"high","domains":[{"name":"risk_of_bias","rating":"serious"},{"name":"inconsistency","rating":"not_serious"},{"name":"indirectness","rating":"not_serious"},{"name":"imprecision","rating":"serious"},{"name":"publication_bias","rating":"not_serious"}]}' | python grade_judge.py -

# Argdown: surrogate premise → hard-endpoint claim → 1 gap flagged, exit 1
echo '{"claim":"Drug lowers fractures","claim_type":"hard_endpoint","premises":[{"id":"P1","type":"surrogate_outcome"}]}' | python argdown_lint.py - ; echo "exit=$?"

Both scripts are Python 3 stdlib only — no install, no dependencies, no network, no secrets.

Install & configure

See SETUP.md. In short:

1. Drop paper-review/ and paper-digest/ into ~/.claude/skills/.
2. cp paper-review/config.example.yaml paper-review/config.yaml and fill in your values.
3. Everything optional (vault paths, full-text resolvers, review-card site, clinical persona) is off until you configure it. The science core works with nothing configured.

Then in Claude Code: /paper-review <DOI> or /paper-digest <DOI>.

Honest scope

This is a reference implementation, published as a one-time share and updated occasionally — not a maintained product. It grew inside one person's Obsidian + Zotero + self-hosted review-site setup; those couplings now live behind config.yaml.

• Portable and dependency-free: grade_judge.py, argdown_lint.py, causal-appraisal.md, the RoB routing table, the CrossRef gate, and the three-layer digest method work for anyone.
• Yours to fill in: vault paths, your library's full-text resolver, an optional review-card site, your clinical persona.

Not medical advice; not a replacement for reading the paper. It is a structured second reader that refuses to let a plausible-but-wrong appraisal stand.

Repository layout

paper-review/
  SKILL.md                 the appraisal skill
  fulltext-acquisition.md  shared full-text route ladder
  causal-appraisal.md      35 bundled causal-inference doctrines (no external dependency)
  grade_judge.py           deterministic GRADE recompute (stdlib)
  argdown_lint.py          deterministic inference-gap linter (stdlib)
  config.example.yaml      copy → config.yaml, fill in
  SETUP.md                 setup guide
  journal_cache.json       optional local cache to avoid repeat lookups
  author_cache.json        optional local cache
paper-digest/
  SKILL.md                 the content-digest skill (reads paper-review/config.yaml)

config.yaml is git-ignored — only config.example.yaml ships.

Credits & licence

Deterministic GRADE and the CrossRef / argument-gate ideas are ported from and inspired by htlin222/robust-lit-review. RoB tools, GRADE, and PRISMA are the standard EBM instruments; the causal doctrines digest Hernán & Robins, Causal Inference: What If and Guyatt et al., Users' Guides to the Medical Literature.

Licence: MIT (see LICENSE). The bundled EBM/causal content summarizes published methodological literature for personal study use; cite the primary sources, not this repo, in academic work.

繁體中文

兩個 Claude Code skill，用來把一篇論文「好好讀完」。 一個負責評「這篇可不可信、做得好不好」，一個負責「這篇講了什麼、怎麼最快吸收」。由一位臨床醫師 為自己的 journal club 與臨床決策打造，再抽掉私人設定後對外分享。

English · 繁體中文

這是什麼

把論文讀好，其實是兩件不同的事，會讀的人會把它們分開：

兩者獨立，同一篇論文可以都跑。

這是一條 pipeline 的一端。 這兩個 skill 負責「讀」。負責「發現」的另一端，是一個個人文獻雷達： 每天抓幾十個期刊 RSS + PubMed，依你的興趣模型評分排序，把挑中的論文交棒出來評讀／整理，那就是 paper-radar 論文學習雷達。paper-radar 的 /paper-sync 會把你勾選的論文直接派給 /paper-review（🔬 品質）或 /paper-digest（📚 內容）。 可以一起用，也可以各自單獨用。

為什麼它不只是一段厲害的 prompt

大部分「AI 幫你看論文」的工具，都鬆散地宣稱兩件事：它能評證據等級、它抓得到 spin。這個專案把這兩個 宣稱用真正的確定性程式碼做成真的。核心理念就一句話：語言模型做語意判斷，程式做邏輯與計算。

grade_judge.py：把 GRADE 變成算術，不是憑感覺

模型只負責評五個面向（risk of bias、inconsistency、indirectness、imprecision、publication bias）， 每項給「不嚴重／嚴重／很嚴重」。接著一支純標準庫的程式，根據起始等級加總升降級、算出最終證據等級， 並 clamp 在 [Very low … High]。模型自報的等級只當參考，程式算出來的才是準的，兩者不一致時程式會警告。 它還會擋掉模型常記錯的 GRADE 規則，例如觀察性研究只要有任一面向被降級，就不准再升級。

argdown_lint.py：把結論的邏輯漏洞變成可檢查的 gate

模型負責把每個「支撐結論的發現」標上前提類型（直接 RCT 證據／相關性／替代指標／單一研究／次族群／ 次要 outcome／機轉／專家意見），程式再確定性地標出不合法的推論跳躍，有漏洞就以非零結束：

• 用替代指標的改善 → 宣稱對真正臨床終點有效
• 用相關性 → 宣稱因果
• 用單一研究 → 宣稱「一致地顯示」
• 只靠次族群／次要 outcome → 宣稱有療效（典型 spin）

CrossRef 存在性 gate

在做任何語意比對之前，先拿每篇被選中的引用去 CrossRef 即時查證，抓出假 DOI、以及「DOI 對但論文不對」 的張冠李戴。（未經稽核的 AI 引用正確率約四到八成，這是最便宜的一道防呆。）

委派 fan-out，失敗一律當缺口回報

深度評讀把「吃智力」的工作（讀論文本體一次、appraisal、GRADE）留在主脈絡，把扇出型的查詢 （作者側寫、引用查核、citation／PubPeer 掃描）委派給並行的子代理，讓原始搜尋結果不會塞爆主分析。 每一個查不到的項目都會明確標成缺口（「PubPeer 掃描：FAILED／無結果」），絕不默默丟掉，因為 「沒跑」不可以被當成「沒找到問題」。

依研究設計路由的偏差風險評估（不是一張萬用 checklist）

觀察性研究另外會對照 35 條內建的因果推論 doctrine（causal-appraisal.md，濃縮 Hernán & Robins 與 Users' Guides to the Medical Literature）。

快速驗證

cd paper-review
# GRADE：RCT 起始 High、兩項 serious → 算出 Low
echo '{"starting_level":"high","domains":[{"name":"risk_of_bias","rating":"serious"},{"name":"inconsistency","rating":"not_serious"},{"name":"indirectness","rating":"not_serious"},{"name":"imprecision","rating":"serious"},{"name":"publication_bias","rating":"not_serious"}]}' | python grade_judge.py -

# Argdown：替代指標前提 → 硬終點宣稱 → 標 1 個漏洞，exit 1
echo '{"claim":"Drug lowers fractures","claim_type":"hard_endpoint","premises":[{"id":"P1","type":"surrogate_outcome"}]}' | python argdown_lint.py - ; echo "exit=$?"

兩支腳本都是 Python 3 純標準庫，免安裝、零依賴、不連網、不碰任何金鑰。

安裝與設定

詳見 SETUP.md。簡單講：

1. 把 paper-review/ 與 paper-digest/ 放進 ~/.claude/skills/。
2. cp paper-review/config.example.yaml paper-review/config.yaml，填入你自己的值。
3. 所有選用功能（vault 路徑、全文解析器、複習卡網站、臨床 persona）沒設定就是關的；科學核心不設定也能跑。

然後在 Claude Code 裡：/paper-review <DOI> 或 /paper-digest <DOI>。

誠實的定位

這是一個 reference implementation（參考實作），以一次性分享的形式釋出、偶爾更新，不是一個持續維護的 產品。它長在某個人的 Obsidian + Zotero + 自架複習網站上，這些耦合現在都收進 config.yaml 了。

• 可移植、零依賴：grade_judge.py、argdown_lint.py、causal-appraisal.md、RoB 路由表、 CrossRef gate、三層整理法，對誰都能用。
• 要你自己填：vault 路徑、你所屬機構的全文解析器、選用的複習卡網站、你的臨床 persona。

這不是醫療建議，也不能取代你自己讀論文。 它是一個會拒絕讓「看起來有道理但其實錯了」的評讀過關的第二讀者。

專案結構

paper-review/
  SKILL.md                 評讀 skill
  fulltext-acquisition.md  共用的全文取得路徑階梯
  causal-appraisal.md      35 條內建因果推論 doctrine（無外部依賴）
  grade_judge.py           確定性 GRADE 重算（標準庫）
  argdown_lint.py          確定性推論漏洞 linter（標準庫）
  config.example.yaml      複製成 config.yaml 後填寫
  SETUP.md                 設定指南
  journal_cache.json       選用本地快取，避免重複查詢
  author_cache.json        選用本地快取
paper-digest/
  SKILL.md                 內容整理 skill（讀 paper-review/config.yaml）

config.yaml 已被 git 忽略，只有 config.example.yaml 會進版控。

致謝與授權

確定性 GRADE 與 CrossRef／論證 gate 的概念，移植並啟發自 htlin222/robust-lit-review。RoB 工具、GRADE、PRISMA 皆為標準實證醫學工具；因果 doctrine 濃縮自 Hernán & Robins 的 Causal Inference: What If 與 Guyatt 等人的 Users' Guides to the Medical Literature。

授權：MIT（見 LICENSE）。內建的實證醫學／因果內容為個人學習用途的方法學文獻摘要；學術引用時請引原始出處， 而非本 repo。

🧋 Support

If this tool saves you time, you can buy me a boba — it keeps the servers running 🧡

🌱 Start here if you're new to AI agents ／ AI agent 新手起點

This tool is one piece of my personal AI workflow. If you want to learn how to use AI agents like Claude Code from zero (no programming background needed), I wrote a beginner series (in Traditional Chinese):

這個工具是我個人 AI 工作流的一部分。想從零開始學怎麼用 Claude Code 這類 AI agent（不需要程式背景），可以從我的入門系列開始：

1. 從零開始：安裝、看懂 GitHub、跑起你的第一個工具
2. 怎麼跟 AI agent 講話：心法、元技能與規則檔
3. 自動化流程不是設計出來的，是長出來的

Full map of my tools and posts ／ 所有工具與文章的全貌 → drpwchen.com/map