revise-applied-paper

A Claude Code skill that referees an applied economics paper (PDF) against the writing standards in Marc F. Bellemare’s Doing Economics (MIT Press, 2022) and against empirical readability norms for the field. Think of it as an AI referee panel: three cold referees each write a report, a synthesis shows where they agree, and a readability report scores every section. It is read-only — it never edits your manuscript.

What sets it apart from other AI writing tools: its standard of reference. Instead of improvising what “good academic writing” means, every comment is anchored to a published, widely cited authority in applied economics — Bellemare’s book — not to a model’s private taste.

[!IMPORTANT] This is a writing-craft tool, not scientific peer review. It checks the manuscript against Bellemare’s recommendations on structure, exposition, and presentation — does the introduction follow Head’s formula, is the data section complete, are the tables self-explanatory, does the abstract read for a general audience. The referee reports are about how the paper is written, not about whether the economics is correct. It does not judge the validity of your identification, the soundness of your model, the correctness of your results, or the merit of your contribution. That judgment remains yours and your actual referees’.

What it does

Applied papers get rejected for avoidable writing reasons — a buried research question, a thin data section, an introduction that overpromises, tables a reader can’t reconstruct. Bellemare wrote down the unspoken norms that prevent this. This skill turns those norms into a repeatable, multi-referee check on your own draft.

How it compares

• revise-applied-paper (open · free · yours) is anchored to a citable authority, runs locally so your unpublished draft never leaves your machine, costs $0 on top of Claude, and is open to fork and adapt. Several independent referees let you see which comments are robust — a 3/3 finding is a different thing from a 1/3 one.
• Hosted alternatives (paid · hosted · deep compute) trade those for raw horsepower — whole-argument stress tests, deep proof-chasing, a polished shareable report — at the cost of uploading your unpublished work to someone else’s servers.

How it works

[1 mechanical]   PDF → local marker → blocks → chunks.json + paper.md + figures   (Python, no LLM)
[2 referees]     N identical cold referees → referee_1..N.md → synthesis.md
[3 readability]  score.py on paper.md → readability.md                  (parallel with stage 2)

1. Ingest — marker parses the PDF locally into ordered blocks. Tables stay as HTML (multi-level headers survive), equations become LaTeX, reference lists are unnumbered and merged across page breaks, page headers and footers are dropped. A parse guard fails loudly on a malformed or scanned PDF.
2. Referees — N fresh subagents (default 3) each read only the chunks, the figures, and the ~80-item checklist distilled from Bellemare — no conversation context, no readability scores — and each writes a full referee report: summary, numbered major comments (identification, structure, provenance, overclaiming) and minor comments (tense, notation, tables, abstract polish), and three acid tests. The orchestrator, which never read the paper, then writes a synthesis: every finding labelled 3/3, 2/3, or 1/3, sorted by severity, with contradictions between referees surfaced rather than resolved.
3. Readability — a stdlib scorer measures each section (abstract, introduction, methods, results, conclusion) on Flesch Reading Ease, Gunning Fog, lexical variety (MATTR) and the share of over-long sentences against pass marks from a corpus of published Ag Econ papers; one agent interprets the numbers and quotes the sentences that drag a section under.

Everything lands in a dated folder next to the paper:

referee//
├── blocks.json, chunks.json, paper.md, _images/   # stage 1
├── referee_1.md … referee_N.md                          # stage 2, all kept
├── synthesis.md                                         # stage 2, omitted when N = 1
└── readability.md                                       # stage 3

Usage

/revise-applied-paper paper.pdf                    # 3 referees + synthesis + readability
/revise-applied-paper paper.pdf --referees 1       # one report, no synthesis
/revise-applied-paper paper.pdf --no-readability   # skip stage 3

It also triggers when you ask things like “referee this PDF” or “check this draft against applied-econ norms.” Input is PDF only — born-digital with a text layer; scans are not handled.

Requirements

• uv. Stage 1 runs with uv run from PEP 723 inline metadata — no venv, no pyproject.toml, no global install; the first run installs marker-pdf, chonkie, markdownify into uv’s cache and marker downloads ~2GB of model weights.
• python3 for stage 3 (stdlib only).

Cost

Each referee re-reads the whole paper and the checklist, so a 3-referee run is roughly three times a single review. --referees 1 gives one report at a third of the cost; the synthesis is what you pay the extra for — it tells you which comments three independent readers agree on.

Installation

The skill must live in ~/.claude/skills/ to be active. Clone it there, or clone anywhere and symlink:

git clone [email protected]:noejn2/revise-applied-paper.git
ln -s "$(pwd)/revise-applied-paper" ~/.claude/skills/revise-applied-paper

Then /revise-applied-paper in any project.

Repo layout

revise-applied-paper/
├── SKILL.md                       # the skill: three stages, arguments, prompts
├── scripts/
│   ├── ingest.py                  # stage 1: PDF → blocks/chunks/paper.md (uv run, PEP 723)
│   ├── score.py                   # stage 3: readability scorer, stdlib only
│   ├── test_ingest.py             # tests: stage 1, plus the ingest → score seam
│   ├── test_score.py              # tests: the readability scorer
│   └── test_contract.py           # tests: SKILL.md ↔ checklist ↔ templates stay in sync
├── references/
│   ├── bellemare-checklist.md     # the ~80-item audit, §1–§11
│   ├── bellemare-fulltext.txt     # full text, for when original wording is needed
│   ├── uw-abstract-guide.md       # abstract criteria from the UW–Madison Writing Center
│   └── thresholds.json            # readability pass marks per section
└── assets/
    ├── referee-report-template.md # fixed report format
    ├── synthesis-template.md      # fixed synthesis format
    └── venn.png

Credit

All of the substance here is Marc F. Bellemare’s. The checklist distills the chapter on writing applied papers from his book Doing Economics (MIT Press, 2022). For the real thing, read the book and his blog on academic writing — and Keith Head’s Introduction Formula, which it relies on. The abstract criteria in references/uw-abstract-guide.md are distilled from the University of Wisconsin–Madison Writing Center’s Writing an Abstract for Your Research Paper. PDF ingestion is built on marker and chonkie; the readability scorer and its thresholds come from the companion skill plain-language-it.