reviewing-my-paper

Reviewing My Paper

Overview

A multi-lens review pipeline for the user's own academic paper that ends in an annotated PDF (highlights + sticky notes), not just prose feedback. It layers five independent lenses and — critically — adversarially verifies its own findings before presenting them, because a single review pass overstates claims and misses whole categories (citation existence, English discourse flow, copy-edit).

Core principle: every finding must be located (page + anchor) and verified before it reaches the PDF. Findings you can't substantiate get dropped or downgraded.

When to Use

• "Review / critique / give feedback on my paper", "mark up my PDF", "proofread my manuscript".
• The artifact is the user's own paper (be a constructive reviewer, not a gatekeeper).
• NOT for reviewing someone else's paper for a venue (use academic-research-skills:academic-paper-reviewer directly) or writing a new paper (academic-research-skills:academic-paper).

Pipeline

Run these in order. Lenses 3–6 are independent → dispatch them as parallel subagents, each writing its results to a file so the annotation step can consume them.

#	Phase	How
0	Extract text	PyMuPDF (see Environment). Save to paper_text.txt with page markers. Large PDFs: don't try to Read all pages.
1	Field analysis	Identify discipline, method type, and target venue to calibrate standards.
2	Multi-perspective review	Invoke academic-research-skills:academic-paper-reviewer (EIC + 3 reviewers + Devil's Advocate + synthesis).
3	Citation hallucination check	Fan out parallel agents over every reference (~8 each). Each verifies existence + metadata via WebSearch against DOI / ACL Anthology / OpenReview / proceedings — never from memory. Classify VERIFIED / SUSPECT / NOT_FOUND with the 5-type taxonomy (TF/PAC/IH/PH/SH). Mirrors academic-research-skills:academic-pipeline integrity_verification_agent.
4	Argument / logical flow	Motivation→method→claim chain, claim-evidence alignment, overclaims, non-sequiturs.
5	Academic-English discourse flow	Conventions: general→specific (summary then specification), topic-sentence-first paragraphs, given-before-new cohesion, CARS intro moves, section-opener signposting, cross-section consistency. (Baseline reviewers skip this — it is the highest-value differentiator.)
6	Grammar / copy-edit	Genuine prose errors only. Tell the agent to ignore PDF-extraction artifacts (mid-word hyphenation, mangled math/symbols, spaced numerals like "15 696").
7	Adversarial self-verification	Before finalizing: re-check substantive claims, especially external facts (SOTA numbers, prior-art priority, "missing baseline X"), with refute-style subagents. Downgrade or drop anything you can't substantiate. Check disclosed caveats before calling a number an "inconsistency".
8	Annotate the PDF	Build a findings JSON, run annotate_pdf.py (see Tool). Color = severity.
9	Deliver	Send the annotated PDF + a short summary. Offer a consolidated P0/P1/P2 revision plan.

Environment

PDF tooling is often missing. If pdftoppm/pymupdf are absent:

python3 -m venv /tmp/pdfvenv && /tmp/pdfvenv/bin/pip install pymupdf

Extract text:

import fitz; doc = fitz.open("paper.pdf")
open("paper_text.txt","w").write("".join(
    f"\n===== PAGE {i+1} =====\n"+p.get_text() for i,p in enumerate(doc)))

Tool: annotate_pdf.py

Findings JSON = list of {"page": <1-based>, "anchor": "<short unique text>", "severity": "<critical|major|minor|strength|copyedit|clarify>", "note": "<comment>"}.

/tmp/pdfvenv/bin/python annotate_pdf.py --src paper.pdf --findings findings.json

It highlights the anchor, attaches the note as a popup + comment icon, color-codes by severity, auto-versions the output filename, and prints FOUND/MISSED. Anchor rules: short and unique (a number, heading, or 2–4 words); avoid the first word after a drop-cap; multi-line phrases often miss.

Annotation conventions

• Color = severity: 🔴 critical · 🟠 major · 🔵 minor/clarify · 🟢 strength · 🟣 copy-edit. Always include strengths — balanced feedback.
• Tag each note with its lens, e.g. [R2 - MAJOR], [EN-Flow - MAJOR], [Copy-edit], [Integrity - STRENGTH].
• Versioned output filename every iteration (_v2, _v3…) — same-named files get cached by PDF viewers and the user sees stale comments.

Common Mistakes

• Skipping lenses 5–6. A general review covers correctness and citations but silently drops discourse-flow and copy-edit. Run all six.
• Trusting your own findings. This session's review overstated SOTA gaps and flagged a disclosed caveat as a "critical inconsistency." Always run lens 7 and refute external-fact claims before presenting.
• Citation check that only re-checks the reviewer's claims. Verify every reference for existence, not just the ones a reviewer questioned.
• Flagging extraction artifacts as grammar errors. Warn the grammar agent explicitly.
• Overwriting the same output PDF. Version it, or the user reports "it didn't update."
• Editing the manuscript. Reviewers produce reports/annotations; never rewrite the author's file.

Cross-references

• REQUIRED SUB-SKILL: academic-research-skills:academic-paper-reviewer (phase 2).
• REQUIRED REFERENCE: academic-research-skills:academic-pipeline integrity_verification_agent (phase 3 model).
• Related: academic-research-skills:academic-paper (revision mode) to act on the findings.