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:

1. Sanitize the paper title: lowercase, replace spaces with underscores, remove special characters, truncate to 60 chars
2. 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>/
3. 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:

1. During writing (Step 2): grep to verify claims before writing them
2. 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:

1. 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.

2. 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.

3. Map figures to analysis sections using the output manifest:

   • Architecture/model diagrams → Section 5: 技术方法与系统架构
   • Result plots/charts → Section 6: 实验设计与评估分析
   • Comparison figures → Section 7: 批判性分析 or Section 3: 创新贡献与研究定位
   • Overview/pipeline figures → Section 2: 核心摘要与定性评估

   Do NOT review every figure individually unless extraction reported errors. Trust the script output and proceed to analysis.

4. 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「原文未明确提及」. 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., "（图~\ref{fig:foo} 的自动抽取存疑：{suspect_reason}，建议读者直接查阅原文图片）". Do not silently embed a suspect figure as if it were authoritative.

1. Read the full analysis prompt from references/analysis-prompt.md in this skill's directory

2. Read the LaTeX template from assets/template.tex and the guide from references/latex-guide.md

3. Use the output directory already created in Step 1 (the <sanitized_name>/ subfolder)

4. Analyze the paper following the 10-section structure defined in the prompt

5. Apply the adaptive depth guidelines based on paper type (systems/ML/theory/survey/empirical)

6. 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:

1. Read verification_report.txt
2. For NOT FOUND claims:
   • If the claim is a training config, parameter, or number: remove it or mark as「原文未明确提及」
   • If the claim is a reasonable paraphrase or derivation: keep but verify by re-reading the specific PDF page visually
3. 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
4. For systematic issues (e.g., many NOT FOUND in one section): re-read the relevant PDF pages and rewrite that section
5. If uncertain about a claim after review, add near-verbatim quotes: "（原文表述：'...'）"

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.

1. 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
   

2. 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.

3. 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