{"id":"2f80b88c-a38a-4684-bd55-524d57fcb954","slug":"paper-review-and-digest","kind":"skill","name":"paper-review-and-digest","summary":"Two Claude Code skills for reading one academic paper: /paper-review (journal-club appraisal, deterministic GRADE + CrossRef gate) and /paper-digest (fast content absorption). Reading end of a pipelin","owner":"drpwchen","repoUrl":"https://github.com/drpwchen/paper-review-and-digest","license":"MIT","licenseTier":"permissive","trust":"community","stars":42,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T05:55:19.029Z","logoUrl":"https://avatars.githubusercontent.com/u/55537221?u=885675b3a0e00cfba6586c04b61d3fe264d765dc&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","browser-web","data-analytics"],"tags":["academic-papers","claude-code","critical-appraisal","evidence-based-medicine","grade","pubmed"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T06:47:09.279Z","sample":false,"url":"https://conduits.dev/tools/paper-review-and-digest","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# paper-review + paper-digest\n\nTwo [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills for reading a single\nacademic paper *properly* — one appraises whether it can be trusted, the other absorbs what it says.\nBuilt by a practising physician for real journal-club and clinical use, then generalized for sharing.\n\n🔭 **Discovery** [paper-radar](https://github.com/drpwchen/paper-radar) ｜ ⬇️ **Download** [paper-fetch](https://github.com/drpwchen/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.\n\n> **English** · [繁體中文](#繁體中文)\n\n---\n\n## What this is\n\nReading a paper well is really two different jobs, and good readers keep them separate:\n\n| Skill | Answers | What it does |\n|---|---|---|\n| **`/paper-review`** | *Can I trust this? Is it done well?* | Journal-club-grade appraisal: journal credibility, author track record, **reference verification with a live CrossRef existence gate**, design-routed risk-of-bias, spin / argument-structure audit, **deterministic GRADE**, citation-impact analysis. |\n| **`/paper-digest`** | *What does it say? How do I absorb it fastest?* | A teaching-style content digest in three progressive-disclosure layers, structure routed by paper type, ending in active-recall self-test cards. Hard-stops without full text (no abstract-only fake digests). |\n\nThey are independent and can both run on one paper.\n\n> **Part of a pipeline.** These skills are the *reading* end. The *discovery* end — a personal\n> literature radar that pulls dozens of journal feeds + PubMed searches, ranks them by your interest\n> model, and hands the picks off for appraisal/digest — is\n> [**paper-radar**](https://github.com/drpwchen/paper-radar). paper-radar's `/paper-sync` dispatches\n> a picked paper straight into `/paper-review` (🔬 quality) or `/paper-digest` (📚 content). Use them\n> together, or either alone.\n\n## Why it isn't just a clever prompt\n\nMost \"AI paper review\" tools make two claims loosely — that they grade the evidence and that they\ncatch spin. Here those claims are made **true by real, deterministic code**. The split is the whole\npoint: **the language model does semantic judgement; a program does the logic and the arithmetic.**\n\n### `grade_judge.py` — GRADE as arithmetic, not vibes\nThe model rates the five GRADE domains (risk of bias, inconsistency, indirectness, imprecision,\npublication bias) as *not serious / serious / very serious*. A pure-stdlib script then **recomputes\nthe final certainty** from the starting level and the summed downgrades/upgrades, clamped to\n[Very low … High]. The model's self-reported grade is advisory only; the script's number is\nauthoritative, and it warns when the two disagree. It also **enforces GRADE rules the model tends to\nforget** — e.g. observational evidence can't be upgraded once any domain is downgraded.\n\n### `argdown_lint.py` — inference gaps as a real gate\nThe model tags each supporting finding by premise type (`direct_rct`, `association`,\n`surrogate_outcome`, `single_study`, `subgroup`, `secondary_outcome`, `mechanistic`,\n`expert_opinion`). A stdlib script then **deterministically flags the illicit jumps** and exits\nnonzero:\n- surrogate outcome → hard-endpoint / causal benefit claim\n- association → causal claim\n- single study → \"consistently shown\"\n- subgroup / secondary outcome only → benefit claim (classic spin)\n\n### CrossRef existence gate\nBefore any semantic citation comparison, each selected reference is checked against the live CrossRef\nAPI — catching fabricated DOIs and \"right DOI, wrong paper\" swaps that a purely semantic read misses.\n(Unaudited LLM-written citations run ~40–80% accuracy; this is the cheap deterministic guard.)\n\n### Delegated fan-out, and failures reported as gaps\nThe deep review keeps the intelligence-bound work (reading the paper once, appraisal, GRADE) in the\nmain context and **delegates the fan-out lookups** — author profiling, reference verification,\ncitation / PubPeer sweeps — to parallel subagents, so raw search dumps never bloat the analysis.\nEvery lookup that fails is **reported as an explicit gap** (\"PubPeer sweep: FAILED / no hits\"), never\nsilently dropped — an unrun check must not read as \"nothing found\".\n\n### Design-routed risk of bias (not one checklist)\n| Study type | Tool |\n|---|---|\n| RCT | Cochrane RoB 2 |\n| Cohort / case-control / cross-sectional | ROBINS-I / Newcastle-Ottawa |\n| Systematic review / meta-analysis | AMSTAR-2 + GRADE per outcome (+ PRISMA 2020 reporting check) |\n| Diagnostic accuracy | QUADAS-2 |\n| Prediction model | PROBAST |\n| Guideline | AGREE II |\n| Narrative review | SANRA + cherry-picking check |\n| Case series / report | JBI checklist |\n\nObservational studies additionally get checked against 35 bundled causal-inference doctrines\n(`causal-appraisal.md`, digesting Hernán & Robins and the *Users' Guides to the Medical Literature*).\n\n## Quick sanity check\n\n```bash\ncd paper-review\n# GRADE: RCT starting High, two 'serious' domains → Low\necho '{\"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 -\n\n# Argdown: surrogate premise → hard-endpoint claim → 1 gap flagged, exit 1\necho '{\"claim\":\"Drug lowers fractures\",\"claim_type\":\"hard_endpoint\",\"premises\":[{\"id\":\"P1\",\"type\":\"surrogate_outcome\"}]}' | python argdown_lint.py - ; echo \"exit=$?\"\n```\n\nBoth scripts are Python 3 stdlib only — no install, no dependencies, no network, no secrets.\n\n## Install & configure\n\nSee **[SETUP.md](paper-review/SETUP.md)**. In short:\n\n1. Drop `paper-review/` and `paper-digest/` into `~/.claude/skills/`.\n2. `cp paper-review/config.example.yaml paper-review/config.yaml` and fill in your values.\n3. Everything optional (vault paths, full-text resolvers, review-card site, clinical persona) is\n   **off until you configure it**. The science core works with nothing configured.\n\nThen in Claude Code: `/paper-review <DOI>` or `/paper-digest <DOI>`.\n\n## Honest scope\n\nThis is a **reference implementation**, published as a one-time share and updated occasionally — not\na maintained product. It grew inside one person's Obsidian + Zotero + self-hosted review-site setup;\nthose couplings now live behind `config.yaml`.\n\n- **Portable and dependency-free:** `grade_judge.py`, `argdown_lint.py`, `causal-appraisal.md`, the\n  RoB routing table, the CrossRef gate, and the three-layer digest method work for anyone.\n- **Yours to fill in:** vault paths, your library's full-text resolver, an optional review-card\n  site, your clinical persona.\n\n**Not medical advice; not a replacement for reading the paper.** It is a structured second reader\nthat refuses to let a plausible-but-wrong appraisal stand.\n\n## Repository layout\n\n```\npaper-review/\n  SKILL.md                 the appraisal skill\n  fulltext-acquisition.md  shared full-text route ladder\n  causal-appraisal.md      35 bundled causal-inference doctrines (no external dependency)\n  grade_judge.py           deterministic GRADE recompute (stdlib)\n  argdown_lint.py          deterministic inference-gap linter (stdlib)\n  config.example.yaml      copy → config.yaml, fill in\n  SETUP.md                 setup guide\n  journal_cache.json       optional local cache to avoid repeat lookups\n  author_cache.json        optional local cache\npaper-digest/\n  SKILL.md                 the content-digest skill (reads paper-review/config.yaml)\n```\n\n`config.yaml` is git-ignored — only `config.example.yaml` ships.\n\n## Credits & licence\n\nDeterministic GRADE and the CrossRef / argument-gate ideas are ported from and inspired by\n[htlin222/robust-lit-review](https://github.com/htlin222/robust-lit-review). RoB tools, GRADE, and\nPRISMA are the standard EBM instruments; the causal doctrines digest Hernán & Robins, *Causal\nInference: What If* and Guyatt et al., *Users' Guides to the Medical Literature*.\n\nLicence: MIT (see `LICENSE`). The bundled EBM/causal content summarizes published methodological\nliterature for personal study use; cite the primary sources, not this repo, in academic work.\n\n---\n\n<a name=\"繁體中文\"></a>\n\n# 繁體中文\n\n兩個 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill，用來把一篇論文「好好讀完」。\n一個負責評「這篇可不可信、做得好不好」，一個負責「這篇講了什麼、怎麼最快吸收」。由一位臨床醫師\n為自己的 journal club 與臨床決策打造，再抽掉私人設定後對外分享。\n\n> [English](#paper-review--paper-digest) · **繁體中文**\n\n## 這是什麼\n\n把論文讀好，其實是兩件不同的事，會讀的人會把它們分開：\n\n| Skill | 回答 | 做什麼 |\n|---|---|---|\n| **`/paper-review`** | *這篇可不可信、做得好不好？* | journal club 等級的評讀：期刊可信度、作者背景、**用 CrossRef 即時查證每篇引用是否存在**、依研究設計路由的偏差風險評估、spin／論證結構稽核、**確定性 GRADE**、被引用影響力分析。 |\n| **`/paper-digest`** | *這篇講了什麼、我怎麼最快吸收？* | 教學式的內容整理，三層漸進揭露，依論文類型換骨架，最後生出主動回憶的自我測驗卡。**拿不到全文就硬停**（不做只靠摘要的假整理）。 |\n\n兩者獨立，同一篇論文可以都跑。\n\n> **這是一條 pipeline 的一端。** 這兩個 skill 負責「讀」。負責「發現」的另一端，是一個個人文獻雷達：\n> 每天抓幾十個期刊 RSS + PubMed，依你的興趣模型評分排序，把挑中的論文交棒出來評讀／整理，那就是\n> [**paper-radar 論文學習雷達**](https://github.com/drpwchen/paper-radar)。paper-radar 的\n> `/paper-sync` 會把你勾選的論文直接派給 `/paper-review`（🔬 品質）或 `/paper-digest`（📚 內容）。\n> 可以一起用，也可以各自單獨用。\n\n## 為什麼它不只是一段厲害的 prompt\n\n大部分「AI 幫你看論文」的工具，都鬆散地宣稱兩件事：它能評證據等級、它抓得到 spin。這個專案把這兩個\n宣稱用**真正的確定性程式碼**做成真的。核心理念就一句話：**語言模型做語意判斷，程式做邏輯與計算。**\n\n### `grade_judge.py`：把 GRADE 變成算術，不是憑感覺\n模型只負責評五個面向（risk of bias、inconsistency、indirectness、imprecision、publication bias），\n每項給「不嚴重／嚴重／很嚴重」。接著一支純標準庫的程式，**根據起始等級加總升降級、算出最終證據等級**，\n並 clamp 在 [Very low … High]。模型自報的等級只當參考，程式算出來的才是準的，兩者不一致時程式會警告。\n它還會**擋掉模型常記錯的 GRADE 規則**，例如觀察性研究只要有任一面向被降級，就不准再升級。\n\n### `argdown_lint.py`：把結論的邏輯漏洞變成可檢查的 gate\n模型負責把每個「支撐結論的發現」標上前提類型（直接 RCT 證據／相關性／替代指標／單一研究／次族群／\n次要 outcome／機轉／專家意見），程式再**確定性地標出不合法的推論跳躍**，有漏洞就以非零結束：\n- 用替代指標的改善 → 宣稱對真正臨床終點有效\n- 用相關性 → 宣稱因果\n- 用單一研究 → 宣稱「一致地顯示」\n- 只靠次族群／次要 outcome → 宣稱有療效（典型 spin）\n\n### CrossRef 存在性 gate\n在做任何語意比對之前，先拿每篇被選中的引用去 CrossRef 即時查證，抓出假 DOI、以及「DOI 對但論文不對」\n的張冠李戴。（未經稽核的 AI 引用正確率約四到八成，這是最便宜的一道防呆。）\n\n### 委派 fan-out，失敗一律當缺口回報\n深度評讀把「吃智力」的工作（讀論文本體一次、appraisal、GRADE）留在主脈絡，把**扇出型的查詢**\n（作者側寫、引用查核、citation／PubPeer 掃描）**委派給並行的子代理**，讓原始搜尋結果不會塞爆主分析。\n每一個查不到的項目都會**明確標成缺口**（「PubPeer 掃描：FAILED／無結果」），絕不默默丟掉，因為\n「沒跑」不可以被當成「沒找到問題」。\n\n### 依研究設計路由的偏差風險評估（不是一張萬用 checklist）\n| 研究類型 | 工具 |\n|---|---|\n| 隨機對照試驗 | Cochrane RoB 2 |\n| 世代／病例對照／橫斷 | ROBINS-I／Newcastle-Ottawa |\n| 系統性回顧／統合分析 | AMSTAR-2 + 逐 outcome GRADE（+ PRISMA 2020 報告完整性檢查） |\n| 診斷準確度 | QUADAS-2 |\n| 預測模型 | PROBAST |\n| 臨床指引 | AGREE II |\n| 敘事型回顧 | SANRA + cherry-picking 檢查 |\n| 病例系列／報告 | JBI checklist |\n\n觀察性研究另外會對照 35 條內建的因果推論 doctrine（`causal-appraisal.md`，濃縮 Hernán & Robins 與\n*Users' Guides to the Medical Literature*）。\n\n## 快速驗證\n\n```bash\ncd paper-review\n# GRADE：RCT 起始 High、兩項 serious → 算出 Low\necho '{\"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 -\n\n# Argdown：替代指標前提 → 硬終點宣稱 → 標 1 個漏洞，exit 1\necho '{\"claim\":\"Drug lowers fractures\",\"claim_type\":\"hard_endpoint\",\"premises\":[{\"id\":\"P1\",\"type\":\"surrogate_outcome\"}]}' | python argdown_lint.py - ; echo \"exit=$?\"\n```\n\n兩支腳本都是 Python 3 純標準庫，免安裝、零依賴、不連網、不碰任何金鑰。\n\n## 安裝與設定\n\n詳見 **[SETUP.md](paper-review/SETUP.md)**。簡單講：\n\n1. 把 `paper-review/` 與 `paper-digest/` 放進 `~/.claude/skills/`。\n2. `cp paper-review/config.example.yaml paper-review/config.yaml`，填入你自己的值。\n3. 所有選用功能（vault 路徑、全文解析器、複習卡網站、臨床 persona）**沒設定就是關的**；科學核心不設定也能跑。\n\n然後在 Claude Code 裡：`/paper-review <DOI>` 或 `/paper-digest <DOI>`。\n\n## 誠實的定位\n\n這是一個 **reference implementation（參考實作）**，以一次性分享的形式釋出、偶爾更新，不是一個持續維護的\n產品。它長在某個人的 Obsidian + Zotero + 自架複習網站上，這些耦合現在都收進 `config.yaml` 了。\n\n- **可移植、零依賴**：`grade_judge.py`、`argdown_lint.py`、`causal-appraisal.md`、RoB 路由表、\n  CrossRef gate、三層整理法，對誰都能用。\n- **要你自己填**：vault 路徑、你所屬機構的全文解析器、選用的複習卡網站、你的臨床 persona。\n\n**這不是醫療建議，也不能取代你自己讀論文。** 它是一個會拒絕讓「看起來有道理但其實錯了」的評讀過關的第二讀者。\n\n## 專案結構\n\n```\npaper-review/\n  SKILL.md                 評讀 skill\n  fulltext-acquisition.md  共用的全文取得路徑階梯\n  causal-appraisal.md      35 條內建因果推論 doctrine（無外部依賴）\n  grade_judge.py           確定性 GRADE 重算（標準庫）\n  argdown_lint.py          確定性推論漏洞 linter（標準庫）\n  config.example.yaml      複製成 config.yaml 後填寫\n  SETUP.md                 設定指南\n  journal_cache.json       選用本地快取，避免重複查詢\n  author_cache.json        選用本地快取\npaper-digest/\n  SKILL.md                 內容整理 skill（讀 paper-review/config.yaml）\n```\n\n`config.yaml` 已被 git 忽略，只有 `config.example.yaml` 會進版控。\n\n## 致謝與授權\n\n確定性 GRADE 與 CrossRef／論證 gate 的概念，移植並啟發自\n[htlin222/robust-lit-review](https://github.com/htlin222/robust-lit-review)。RoB 工具、GRADE、PRISMA\n皆為標準實證醫學工具；因果 doctrine 濃縮自 Hernán & Robins 的 *Causal Inference: What If* 與 Guyatt 等人的\n*Users' Guides to the Medical Literature*。\n\n授權：MIT（見 `LICENSE`）。內建的實證醫學／因果內容為個人學習用途的方法學文獻摘要；學術引用時請引原始出處，\n而非本 repo。\n\n## 🧋 Support\n\nIf this tool saves you time, you can buy me a boba — it keeps the servers running 🧡\n\n<a href=\"https://drpwchen.bobaboba.me\"><img src=\"https://s3.ap-southeast-1.amazonaws.com/media.anyonelab.com/images/boba/boba-embed-icon.png\" height=\"36\" alt=\"boba icon\" align=\"middle\"> <img src=\"https://img.shields.io/badge/BUY_ME_A_BOBA-F8E0BE?style=for-the-badge\" height=\"36\" alt=\"BUY ME A BOBA\" align=\"middle\"></a>\n\n---\n\n## 🌱 Start here if you're new to AI agents ／ AI agent 新手起點\n\nThis 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):\n\n這個工具是我個人 AI 工作流的一部分。想從零開始學怎麼用 Claude Code 這類 AI agent（不需要程式背景），可以從我的入門系列開始：\n\n1. [從零開始：安裝、看懂 GitHub、跑起你的第一個工具](https://drpwchen.com/posts/getting-started/)\n2. [怎麼跟 AI agent 講話：心法、元技能與規則檔](https://drpwchen.com/posts/talking-to-agents/)\n3. [自動化流程不是設計出來的，是長出來的](https://drpwchen.com/posts/growing-your-workflow/)\n\nFull map of my tools and posts ／ 所有工具與文章的全貌 → [drpwchen.com/map](https://drpwchen.com/map/)\n"}