Paper Review Helper

Guide user through structured paper review, logging issues and generating formal review response.

Phase 1: Setup

1. Locate paper from $ARGUMENTS:

- If PDF file: create <paper-name>-review/ folder, copy PDF into it - If folder: search for .tex first (prioritize over PDF) - No paper found → AskUserQuestion: "No paper detected. Please provide path to paper."

1. Convert PDF → LaTeX (if no .tex exists):

``bash # Check credentials [ -n "$MATHPIXAPPID" ] && [ -n "$MATHPIXAPIKEY" ] && echo "OK" || echo "MISSING" ``

- If MISSING → notify user: "Set MATHPIXAPPID and MATHPIXAPIKEY for PDF→LaTeX. Proceeding with direct PDF (figures not extractable)." - If OK → run conversion:

``bash python ~/.claude/plugins/science-skill/skills/paper-review-helper/scripts/pdf2tex.py "<pdf_path>" "<paper-folder>" ``

Output structure: <paper-folder>/<pdfid>/<pdfid>.tex with images/ subfolder for figures.

1. Initialize workspace:

<paper-folder>/
├── <pdf_id>/                 # Mathpix output (if converted)
│   ├── <pdf_id>.tex          # Converted LaTeX
│   └── images/               # Extracted figures
├── artifact/
│   ├── review-log.md         # Conversation log
│   ├── issues-major.md       # Major issues
│   ├── issues-minor.md       # Minor issues
│   └── programs/             # Math verification scripts
└── original.pdf              # Source PDF (if applicable)

Phase 2: Section-by-Section Review

Parse LaTeX structure: \section, \subsection, \begin{abstract}. For each section:

1. Chunk appropriately:

- Section ≤5 paragraphs: review whole - Section >5 paragraphs: split by \subsection or paragraph groups

1. Present section with:

1. Section text - save the partial tex to markdown format. 2. Inline markers for issues (see Grammar Check Markers) in the markdown file. 3. and provide the user with a path link to the file in the workspace. 4. Figure refs: [Figure X: images/<filename> - <caption>] with a path link to the file in the workspace.

1. Ask user via AskUserQuestion:

- "Questions about this section?" - "Any concerns or unclear points?" - "Rate clarity: clear / somewhat unclear / confusing"

1. Respond to requests:

- Citations: WebSearch for DOI, author names, paper titles - Background: WebSearch, WebFetch for concepts - Math check: write script to artifact/programs/, run with Python/SymPy - Figures: read from images/ folder, describe or use /vision skill

1. Log to artifact/review-log.md:

## [Section Name] - [Timestamp]
### User Questions
- Q: ...
- A: ...
### Issues Identified
- [MAJOR] ...
- [MINOR] ...
### Tools Used
- WebSearch: "query" → finding

1. Classify issues:

- Major → issues-major.md: methodology flaws, unsupported claims, logical errors - Minor → issues-minor.md: grammar, typos, unclear wording

Skip Supplementary/Appendix unless user requests.

Phase 3: Review Generation

1. Gather context via AskUserQuestion:

- "Overall impression? (accept / minor revision / major revision / reject)" - "Editor's specific questions?" - "Journal level? (top-tier / mid-tier / specialized)"

1. Generate review to artifact/REVIEW.md:

# Review of [Paper Title]

## Summary
[1-2 sentences]

## Overall Recommendation
[User's decision + justification]

## Major Issues
1. **Issue**: [description]
   - **Location**: Section X, paragraph Y / Equation N
   - **Impact**: [why this matters]
   - **Suggestion**: [fix or note if unfixable]

## Minor Issues
[Grouped by type: grammar, clarity, formatting]

## User Misunderstandings Analysis
[If user had confusion during review:]
- **Confusion**: [what]
- **Cause**: paper vagueness / reader knowledge gap
- **Recommendation**: [should paper clarify?]

## Constructive Feedback
[Positives + specific improvements]

## Editor Questions Response
[If provided]

Grammar Check Markers

Inline markers when presenting text:

• [G: ...] - grammar error
• [C: ...] - clarity issue
• [?] - ambiguous/unsupported claim
• [REF?] - missing or questionable citation
• [EQ?] - equation to verify