paper-reader

Paper Reader Skill

Read an AI/CS academic paper and produce a rigorous Chinese-language analysis report at senior PhD researcher level. Output both a Markdown (.md) file and an elegantly typeset LaTeX (.tex) file that compiles with XeLaTeX.

Skill Files Location

This skill's supporting files are located relative to this SKILL.md:

references/analysis-prompt.md — The full 10-section analysis prompt and writing guidelines
references/latex-guide.md — LaTeX template usage guide, xeCJK pitfalls, and code examples
assets/template.tex — The XeLaTeX template file
scripts/setup-tex.sh — One-time TeX package installer
scripts/extract_figures.py — Smart PDF figure extraction (uses PyMuPDF: caption detection + region rendering)
scripts/extract_text.py — PDF text layer extraction (uses PyMuPDF: page-delimited plain text for grep-based verification)
scripts/validate_figures.py — PDF-structure-based figure quality checks (default verifier; no extra deps)
scripts/verify_extraction.py — OCR-based deep diagnostics (optional; requires tesseract)

IMPORTANT: At the start of every invocation, read references/analysis-prompt.md to load the full analysis structure and guidelines. This is mandatory — do not rely on memory of the prompt.

Workflow

Step 1: Parse Input

Determine the input type from the user's message:

Local PDF file:

The user provides a file path (e.g., /path/to/paper.pdf)
Read the first 1-2 pages of the PDF to extract the title, then read the full paper
For large PDFs (50+ pages): read in chunks, prioritizing Abstract, Introduction, Method/System Design, Experiments, and Conclusion. Do NOT skip Appendices — they often contain critical training details (hyperparameters, compute, ablations) absent from main sections. The paper_text.txt (Step 1.3) covers all pages and enables grep-based lookup of appendix content without re-reading.

Arxiv link:

The user provides an arxiv URL (e.g., https://arxiv.org/abs/2401.12345 or https://arxiv.org/pdf/2401.12345)
Extract the paper ID from the URL
Download the PDF: curl -L -o /tmp/paper_<id>.pdf "https://arxiv.org/pdf/<id>.pdf"
Read the first 1-2 pages to extract the title, then read the full paper

Determine output directory early. After reading the title page, immediately:

Sanitize the paper title: lowercase, replace spaces with underscores, remove special characters, truncate to 60 chars
Create the output subfolder:
- If input is a local PDF: <pdf_directory>/<sanitized_name>/
- If input is an arxiv link: <current_working_directory>/<sanitized_name>/
Run mkdir -p <output_dir>/figures/

This must happen BEFORE Steps 1.3/1.5/1.7 so extraction scripts have a valid output directory.

CRITICAL: Factual accuracy. Author names, affiliations, venue, and year must be copied character-by-character from the PDF title page. Never guess or rely on model knowledge. If the PDF text is ambiguous, re-read the title page carefully. Getting author names or institutions wrong is unacceptable.

CRITICAL: Technical parameters must come from text, not figures. When describing system architecture, data formats, algorithms, or any quantitative design parameters (e.g., block sizes, dimensions, precision formats, scaling strategies), extract values exclusively from the paper's prose descriptions — never infer them from figures or diagrams. Figures often show simplified examples or specific instances that differ from the general specification. For example, a figure may illustrate a 16×32 matrix, but the actual block size might be 16 elements. Always cross-check: if a parameter appears in both text and figure, the text description takes precedence.

Do NOT pause to confirm with the user. Proceed directly to text/figure extraction and analysis generation. Only pause if the PDF cannot be read or downloaded.

Step 1.3 & 1.5: Extract Text and Figures (parallel)

Prerequisite: Ensure pymupdf is installed before running either extraction (one-time):

python3 -c "import fitz" 2>/dev/null || pip3 install pymupdf

Then run Steps 1.3 and 1.5 in parallel (they are independent):

Step 1.3: Extract Text

Extract the PDF's text layer as a searchable plain text file. This serves as the ground truth for verifying factual claims later:

python3 <skill-directory>/scripts/extract_text.py <pdf_path> <output_dir>/paper_text.txt

The output is page-delimited (=== PAGE N ===) plain text. This file is used in two ways:

During writing (Step 2): grep to verify claims before writing them
During verification (Step 2.5): haiku subagent cross-checks the generated .tex against this file

If the output is very small (<1000 chars), the PDF likely has no text layer (scanned document). In this case, rely more heavily on paper_figures_text.txt (Step 1.7) and visual PDF reading, and be extra cautious with factual claims.

Step 1.5: Extract Figures

Extract figures automatically — no manual review unless extraction fails:

Run the extraction script:
```
python3 <skill-directory>/scripts/extract_figures.py <pdf_path> <output_dir>/figures/
```
This automatically detects figure captions (supports Fig. N:, Figure N:, Figure N |, Figure N. formats), finds figure regions using image blocks + vector drawings, and renders at 300 DPI.
Only if extraction found 0 figures: check if the paper uses a non-standard caption format and fall back to rendering key pages with pdftoppm.
Map figures to analysis sections using the output manifest:
- Architecture/model diagrams → Section 5: Technical Methods and System Architecture
- Result plots/charts → Section 6: Experimental Design and Evaluation Analysis
- Comparison figures → Section 7: Critical Analysis or Section 3: Innovative Contributions and Research Positioning
- Overview/pipeline figures → Section 2: Core Summary and Qualitative Evaluation
Do NOT review every figure individually unless extraction reported errors. Trust the script output and proceed to analysis.
Manifest schema (figures_manifest.json): each entry has fig_num, filename, caption (full multi-line caption text, joined with spaces, ≤250 chars — much richer than just "Figure N:"), page, width, height, n_image_blocks, n_drawings, render_type, clip_rect, caption_bbox. When the extractor is uncertain about a region (no visual content + extreme aspect ratio, or the 70 %-page-height cap kicked in), it adds "suspect": true and "suspect_reason": "...". Use the caption field as authoritative figure description (avoid re-deriving from OCR), and treat suspect: true figures as low-confidence in the analysis.

Step 1.6: Validate Figure Extraction Quality

Depends on: Step 1.5 must complete first (needs figures/ directory and figures_manifest.json).

Run the structure-based validator on the extracted figures:

python3 <skill-directory>/scripts/validate_figures.py <output_dir>/

This is a fast, dependency-free check that reads the manifest and the source PDF and surfaces:

Body text leakage — prose paragraphs captured at the top or bottom of a figure
Page header artifacts — running headers / arXiv stamps included in the clip
Caption mismatch — in-text figure references mistaken for the real caption
Partial capture — missing subfigure panels (e.g., subfigure label "(c)" present but not rendered)
Aspect-ratio anomalies — extreme width or height suggesting a pseudo-figure
Numbering gaps — missing or duplicate fig_num in the manifest
Extractor suspect flags — figures where extract_figures.py itself flagged the rendered region as low-confidence (no visual elements + extreme aspect, or the 70 %-page-height cap was triggered)

Action based on results:

All clean → proceed to Step 1.7
MEDIUM issues → note them in the analysis, proceed
HIGH / CRITICAL issues → visually inspect the listed figures before continuing; record the limitation in the analysis report

Optional deeper OCR-based diagnostics are available via scripts/verify_extraction.py (requires tesseract-ocr and pytesseract). Use only when validate_figures.py flags something ambiguous.

Step 1.7: Extract Figure Text (via haiku)

Depends on: Step 1.5 must complete first (needs figures/ directory and figures_manifest.json).

Some information appears only in figures (e.g., training pipeline diagrams showing token counts, architecture diagrams with dimension labels) and is absent from the PDF text layer. Extract this text using a cheap model.

Launch a Task agent with model: "haiku" and subagent_type: "general-purpose". Include these exact instructions in the prompt:

Read each figure image in <output_dir>/figures/ using the Read tool (it supports PNG images).
Also read <output_dir>/figures/figures_manifest.json to get caption and page info for each figure.
The `caption` field in the manifest now contains the FULL multi-line caption text (joined with spaces, ≤250 chars), so you do not need to re-derive captions from the image — focus the OCR pass on labels and numbers that don't appear in the caption.

For each figure, write down ALL visible text: labels, numbers, annotations, flow chart box text,
axis labels, table cells, legend text. Be thorough — even small numbers matter.

Write the output to <output_dir>/paper_figures_text.txt in this format:

=== FIGURE N (page P): [caption from manifest] ===
[all visible text transcribed from the figure image]

(blank line between figures)

Replace <output_dir> with the actual path in the prompt.

This file is small (~500 tokens of labels/numbers) and serves as supplementary evidence alongside paper_text.txt. Token budget: ~15 images × ~1K tokens each ≈ ~15K haiku input tokens for images, plus the output file is tiny.

Step 2: Generate LaTeX Analysis (primary output)

Depends on: Steps 1.3 and 1.7 must both complete before starting (needs paper_text.txt and paper_figures_text.txt).

The .tex file is the source of truth. Write it directly — do NOT write Markdown first.

CRITICAL: Use extracted text as ground truth during writing. For any factual claim you write — especially training configuration (optimizer, learning rate, batch size, compute), system parameters (dimensions, layer counts), and experimental numbers — grep paper_text.txt first to verify the claim exists in the paper's prose. If the info is not found in paper_text.txt, check paper_figures_text.txt for figure-only info. If not found in either, do NOT write the claim — either omit it or explicitly mark as "not explicitly mentioned in the original text". The visual PDF reading provides understanding of structure, figures, and formulas; the extracted text files are the authoritative source for factual claims.

Flag suspect figures. If figures_manifest.json marks any figure as "suspect": true, mention it briefly in the analysis where the figure is embedded — e.g., "(the automatic extraction of Figure~\ref{fig:foo} is questionable: {suspect_reason}; readers are advised to consult the original image directly)". Do not silently embed a suspect figure as if it were authoritative.

Read the full analysis prompt from references/analysis-prompt.md in this skill's directory
Read the LaTeX template from assets/template.tex and the guide from references/latex-guide.md
Use the output directory already created in Step 1 (the <sanitized_name>/ subfolder)
Analyze the paper following the 10-section structure defined in the prompt
Apply the adaptive depth guidelines based on paper type (systems/ML/theory/survey/empirical)
Write the .tex file directly into the subfolder, using native LaTeX formatting throughout:
- Replace all template placeholders (%PAPER_TITLE%, %PAPER_AUTHORS%, etc.). For pdftitle in \hypersetup{}, strip or escape special LaTeX characters (%, #, &, _, ~, ^, {, }) since hyperref does not handle them gracefully.
- Use native LaTeX constructs — never think in Markdown then convert:
  - \section{}, \subsection{}, \subsubsection{} for headings
  - \paragraph{} for bold titled paragraphs (e.g., challenges, subsystem descriptions)
  - \textbf{} only for inline emphasis within a sentence
  - \begin{itemize} / \begin{enumerate} for lists
  - booktabs tables (\toprule, \midrule, \bottomrule)
  - \begin{equation} / $...$ for math
- Use the tcolorbox environments from the template:
  - keyinsight for TL;DR / core points
  - strengthbox for advantages
  - weaknessbox for limitations
  - mathbox for important formulas
  - infobox for metadata tables
- Follow all xeCJK rules from the LaTeX guide (especially: \text{} for Chinese in math, ~ spacing, ASCII-only labels)
- Embed extracted figures using \includegraphics inside figure environments:
```
\begin{figure}[htbp]
\centering
\includegraphics[width=0.85\textwidth]{figures/fig1_name.png}
\caption{中文图题描述}
\label{fig:name}
\end{figure}
```
- Use relative paths (figures/) — the .tex file and figures/ directory are in the same parent directory
- See references/latex-guide.md for single-figure, side-by-side, and full-width examples
- Reference figures in text with 如图~\ref{fig:name} 所示
Note: analysis-prompt.md uses Markdown syntax for figure embedding (![]()); translate these to LaTeX equivalents when writing.

Step 2.5: Two-Phase Factual Verification

After writing the .tex file, perform systematic verification using both automated checking and manual review. This step is mandatory — do not skip it.

Phase A: Haiku Mechanical Verification

Launch a Task agent with model: "haiku" and subagent_type: "general-purpose" to perform mechanical claim-vs-evidence checking:

Agent inputs (pass file paths in the prompt):

<output_dir>/paper_text.txt — primary evidence (PDF text layer)
<output_dir>/paper_figures_text.txt — supplementary evidence (figure OCR)
<output_dir>/<filename>.tex — the generated analysis (content sections only, skip LaTeX preamble)

Agent task: For every factual claim in the .tex file, search both evidence files for supporting text. Focus especially on:

All numerical values: percentages, counts, dimensions, sizes, token counts, speedups
Training configuration: optimizer, learning rate, batch size, compute resources, training duration
Parameter specifications: layer counts, head dimensions, expert counts, vocabulary size
Attribution claims: "this paper proposes X" vs "prior work proposes X"
Named entities: model names, method names, dataset names, framework names

For each claim, output one of:

VERIFIED: [claim] — found: "[exact quote from evidence]" (page N / figure N)
NOT FOUND: [claim] — no supporting text in paper_text.txt or paper_figures_text.txt
MISMATCH: [claim in tex] says X, but evidence says Y (page N)

Agent output: Write the verification report to <output_dir>/verification_report.txt.

Phase B: Opus Review and Fix

After receiving the haiku verification report, the main model reviews and acts on flagged items:

Read verification_report.txt
For NOT FOUND claims:
- If the claim is a training config, parameter, or number: remove it or mark as "not explicitly mentioned in the original text"
- If the claim is a reasonable paraphrase or derivation: keep but verify by re-reading the specific PDF page visually
For MISMATCH claims:
- Correct the .tex to match the paper's actual text
- If the mismatch is minor (wording difference, not factual): keep the paraphrase
For systematic issues (e.g., many NOT FOUND in one section): re-read the relevant PDF pages and rewrite that section
If uncertain about a claim after review, add near-verbatim quotes: "(original wording: '...')"

Step 3: Compile LaTeX

IMPORTANT: Shell commands (xelatex, ls, kpsewhich, curl, python3, etc.) are already in PATH via mise. Call them directly — do NOT prepend export PATH=... or use full paths. Just run xelatex ... directly.

Check TeX environment (first time only):
```
kpsewhich xeCJK.sty
```
If xeCJK is not found, run the setup script:
```
bash <skill-directory>/scripts/setup-tex.sh
```

Compile (from the output directory):

cd <output-directory>
xelatex -interaction=nonstopmode <filename>.tex
xelatex -interaction=nonstopmode <filename>.tex

Two passes are needed for table of contents and cross-references.

Handle compilation errors:
- Read the .log file to identify the error
- Common fixes are documented in references/latex-guide.md
- Fix the .tex file and recompile
- Maximum 3 retry attempts

Step 4: Derive Markdown from LaTeX

After the PDF compiles successfully, run the conversion script to produce the .md file:

python3 <skill-directory>/scripts/tex2md.py <output_dir>/<filename>.tex <output_dir>/<filename>.md

The script handles all environments from the template (sections, keyinsight/mathbox/infobox tcolorboxes, figure, table/tabular, itemize/enumerate, equation/align, lstlisting) and exits with code 1 if any \includegraphics in the .tex is missing from the output .md. If it exits 1, read the error output — it prints the missing figure paths — and investigate why those figure environments were not processed.

The script output looks like:

Written : /path/to/filename.md
Figures : 9 in .tex, 9 in .md

Do not derive the Markdown manually. The script is deterministic and will never drop figures.

Step 5: Report Results

Report output files and a pipeline diagnostic summary showing the status of each stage. For every stage, report whether it completed normally or triggered a fallback.

Analysis complete:
- PDF: /path/to/paper_analysis.pdf
- Markdown: /path/to/paper_analysis.md
- LaTeX source: /path/to/paper_analysis.tex
- Figures: /path/to/figures/ (N figures extracted)
- Verification: /path/to/verification_report.txt (N verified, N not found, N mismatch)

Pipeline summary:
| Stage | Status | Notes |
|-------|--------|-------|
| Step 1: PDF reading | OK | Read N pages |
| Step 1.3: Text extraction | OK / FALLBACK | Extracted N chars (FALLBACK: <1000 chars, scanned PDF) |
| Step 1.5: Figure extraction | OK / FALLBACK | N figures (FALLBACK: 0 figures, used pdftoppm) |
| Step 1.7: Figure text (haiku) | OK / FALLBACK / SKIPPED | N figures transcribed (FALLBACK: agent failed, skipped) |
| Step 2: LaTeX writing | OK | N grep verifications performed |
| Step 2.5A: Haiku verification | OK | N verified, N not found, N mismatch |
| Step 2.5B: Opus review | OK / REWROTE | N fixes applied (REWROTE: section X rewritten) |
| Step 3: LaTeX compilation | OK / RETRIED | Compiled in N passes (RETRIED: N retries needed) |
| Step 4: Markdown derivation | OK | |

Use OK when the stage completed normally with no fallbacks. Use FALLBACK, SKIPPED, RETRIED, or REWROTE when an alternative path was taken. Include brief notes explaining what happened.

This summary helps the user assess confidence in the analysis — stages with fallbacks may indicate areas where accuracy is lower.

Quality Requirements

LaTeX is the source of truth. Write .tex first; derive .md mechanically. Never write Markdown first then convert to LaTeX.
All analysis text must be in Chinese. Technical terms should appear as English in parentheses on first use, then English-only afterward.
Mathematical formulas are mandatory where the paper contains math. Use proper LaTeX notation.
Critical analysis section must contain genuine critique — not just a summary of the paper's claims. Identify real weaknesses, questionable assumptions, and missing experiments.
Data must be precise — cite specific numbers from the paper (accuracy percentages, speedup factors, etc.), not vague descriptions.
LaTeX must compile cleanly with zero errors on xelatex. Warnings are acceptable but errors are not.

Output File Naming Convention

Given a paper titled "Attention Is All You Need":

attention_is_all_you_need/              ← dedicated subfolder
  attention_is_all_you_need_analysis.md
  attention_is_all_you_need_analysis.tex
  attention_is_all_you_need_analysis.pdf
  paper_text.txt                        ← extracted PDF text (Step 1.3)
  paper_figures_text.txt                ← figure OCR text (Step 1.7)
  verification_report.txt               ← haiku verification output (Step 2.5)
  figures/
    fig1.png    ← auto-extracted by extract_figures.py
    fig2.png
    fig3.png
    figures_manifest.json

Troubleshooting

Issue	Solution
PDF too large to read at once	Read pages in batches: first pages 1-20, then 20-40, etc. Focus on key sections.
PDF password-protected or corrupted	Ask user to provide an unprotected version. `extract_figures.py` will print a clear error.
Figure extraction finds 0 figures	Paper may use non-standard caption format. Check with `grep -i "figure\|fig\." <pdf_text>` and fall back to `pdftoppm`.
Arxiv download blocked	Ask user to download the PDF manually and provide the local path.
XeLaTeX not found	TinyTeX should already be in PATH via mise. Just run `xelatex` directly. If truly missing, check `which xelatex` and ensure mise is configured.
Chinese fonts not found	Run `fc-list :lang=zh` to check available fonts. Adjust template font names if needed.
tcolorbox errors	Run `scripts/setup-tex.sh` to install missing packages.
Text extraction yields empty/tiny file	PDF is likely scanned (no text layer). Rely on `paper_figures_text.txt` and visual reading. Be extra cautious with factual claims — mark uncertain items as "not explicitly mentioned in the original text".
Haiku figure text agent fails	Proceed without `paper_figures_text.txt`. Note in verification that figure-only info was not cross-checked.
`paper_text.txt` has garbled characters	Some PDFs use custom fonts with broken Unicode mappings. Try `page.get_text("rawdict")` as fallback, or rely on visual reading.