read-research-paper

Read Research Paper

Where the other two skills do this:

Skill	What it does
get-research-paper	FINDS real papers on a topic
research-paper	WRITES new papers
read-research-paper (this)	READS ONE paper and makes it engaging

Give it a URL, arXiv ID, DOI, or pasted text. It produces a visual, multi-layer rendering: technical depth + plain English + mind maps + method flowcharts + key-finding infographics + comparison tables + related-work timelines.

This file is the entry point. Heavier guidance lives in topic folders and is loaded on demand.

---

1. When to activate

Slash commands

Command	What it does
/read-research-paper <input>	Full visual rendering (default)
/read-paper <input>	Alias
/explain-paper <input>	Same, with extra plain-English layer
/visualize-paper <input>	Same, emphasizing visuals over prose
/tldr-paper <input>	One-page infographic summary only

<input> can be:

• A URL: https://arxiv.org/abs/2403.01234, https://doi.org/..., https://example.com/paper.pdf, journal landing page, etc.
• An arXiv ID: 2403.01234 or cs.LG/0701002
• A DOI: 10.1145/3589334
• Pasted text: the paper's abstract or full body
• A local file in any supported format (see below).

Supported file formats

The skill reads any of these as input:

Format	Extensions	Library used	Always available?
Markdown	.md, .markdown	stdlib	yes
Plain text	.txt	stdlib	yes
LaTeX	.tex, .latex	stdlib + regex de-LaTeX	yes
JSON	.json	stdlib	yes
HTML	.html, .htm	beautifulsoup4 (or regex)	yes (regex fallback)
CSV / TSV	.csv, .tsv	pandas (or stdlib)	yes (basic via stdlib)
RTF	.rtf	striprtf (or regex)	yes (regex fallback)
PDF	.pdf	pdfplumber / pypdf	install one
DOCX	.docx	python-docx	install
PPTX	.pptx	python-pptx	install
XLSX	.xlsx, .xls	pandas + openpyxl	install
EPUB	.epub	ebooklib	install
Images	.png, .jpg, .tiff, .bmp	pytesseract + PIL	install (OCR)

One-line install for everything:

pip install pdfplumber python-docx python-pptx pandas openpyxl \
            beautifulsoup4 striprtf ebooklib pytesseract Pillow

(Plus install Tesseract OCR system-wide for images.)

The reader is toolchains/read_any_file.py. Self-test:

python toolchains/read_any_file.py --self-test
python toolchains/read_any_file.py --list-formats

Full reference: sources/file-formats.md.

Common options

Option	Default	Effect
--depth	standard	quick / standard / deep
--audience	mixed	academic / technical / general / mixed
--visuals	auto	auto / max / minimal / none
--include-figures	true	Try to extract / re-create paper's own figures
--cache	true	Use local cache (auto-fill on re-asks)
--language	en	Plain-English language
--out	./<paper-slug>/	Working directory
--with-related	false	Trigger get-research-paper for related work
--with-handoff	false	Emit bibliography.yaml for research-paper

Natural-language patterns

• "read this research paper "
• "explain this paper "
• "make this paper visual "
• "I want to understand this paper "
• "summarize this paper "
• "tldr this paper "
• "what does this paper say "

Negative activation

Do NOT activate for:

• Requests to find papers on a topic (route to get-research-paper).
• Requests to write a new paper (route to research-paper).
• Pasted prose without a paper-shaped input ("here's an article…").
• Casual questions about a topic that don't reference a specific paper.

---

2. Output contract

Every run produces:

1. paper-visual.md — the headline deliverable. Multi-layer:
   • One-page infographic at the top (mind map + key numbers).
   • TL;DR in 5–8 sentences.
   • Plain-English summary in 5–10 sentences.
   • Section-by-section walk-through with each section preceded by a 1-paragraph plain-English version, then the technical content with extracted / generated visuals.
   • Method flowchart (Mermaid).
   • Key findings infographic (charts with the paper's headline numbers).
   • Comparison table to baselines (when present).
   • Related work timeline (when references are available).
   • "Why this matters" footer.
2. paper-data.json — structured extracted metadata: title, authors, year, abstract, sections, figures, tables, key numbers, references. Schema in schemas/visual-paper.json.
3. figures/ — generated charts / diagrams / mind maps as PNG + SVG + Mermaid sources.
4. cache/<paper-id>.json — cached for re-use.
5. Known-gaps.md — anything that couldn't be fetched / parsed.

If --with-handoff is set, also produces bibliography.yaml ready for the research-paper skill.

If --with-related is set, the orchestrator dispatches get-research-paper on the paper's key topics to seed a related-work section.

---

3. Operating principles

0. Anchor to TODAY's date. When the input is a topic-style query (rather than a specific URL/DOI/path), determine today's actual date first (via date -u +%Y-%m-%d, runtime context, or asking the user). For a specific paper input, the freshness check compares the paper's publication date to today and flags stale findings. Full protocol: instructions/freshness.md.
1. Don't bluff. If a URL doesn't resolve or a PDF can't be parsed, say so. Mark [FETCH FAILED — fallback to cache | model knowledge | corpus] and surface in Known-gaps.md.
2. Cache everything. Every successfully fetched paper is written to ~/.agents/skills/read-research-paper/cache/. Re-asks are instant.
3. Ship the corpus. A small bundled corpus of canonical papers (corpus/anchor-papers.yaml) is searched first when the input is a topic-style query rather than a specific paper.
4. Visual-by-default. Generate at minimum: 1 mind map + 1 method flowchart + 1 key-findings figure + 1 comparison table.
5. Dual register. Every section has BOTH plain-English and technical content. Never strip the technical depth — augment with simpler language alongside.
6. Honest interpretation. Don't oversell findings. Match the paper's own certainty. If the paper hedges, the visual paper hedges.

---

4. Top-level workflow

intake → fetch → parse → extract-figures-and-data →
plan-visuals → render → assemble → cache → output

Each phase has a dedicated playbook. Master pipeline: workflows/ingestion.md.

---

5. Source detection

The skill auto-detects input type:

Input pattern	Path
arxiv.org/abs/...	arXiv API
\d{4}\.\d{4,5} (bare arXiv ID)	arXiv API
doi.org/... or 10\..../...	Crossref → URL → fetch
*.pdf (URL or local path)	PDF extraction
Journal landing page URL	URL scrape + Crossref enrichment
Pasted text (no URL)	Treat as paper body; build structure heuristically

See workflows/ingestion.md §1.

---

6. Three-tier fallback

1. Local cache (~/.agents/skills/read-research-paper/cache/)
   ├── Hit  → return immediately (instant)
   └── Miss → next tier

2. Live fetch (arXiv API / Crossref / WebFetch / PDF parser)
   ├── Success → render + cache
   └── Fail    → next tier

3. Bundled corpus (corpus/anchor-papers.yaml)
   ├── Hit  → return + flag as "from bundled corpus"
   └── Miss → next tier

4. Model knowledge
   ├── Confident → render + flag every fact [UNVERIFIED — offline]
   └── Not confident → fail honestly with a Known-gaps entry

Every tier transition is logged in Known-gaps.md so the user knows where the rendered paper came from.

---

7. Visual rendering plan

For every paper, the skill produces:

Visual	Source	Renderer
Mind map	Paper structure (sections + key ideas)	Mermaid mindmap
Method flowchart	Method section	Mermaid flowchart
Key-findings infographic	Headline numbers from results	matplotlib if available, else Markdown table
Comparison table	Paper's own benchmark table	Markdown table
Related-work timeline	References + their years	Mermaid gantt-style timeline
Author network	Authors + affiliations	Mermaid flowchart (small)
Concept map	Paper's terminology	Mermaid mindmap
Figure re-captions	Original figures (when extractable)	Pass-through with new captions

Decision logic: workflows/visualization.md.

---

8. Cache architecture

The cache lives at:

~/.agents/skills/read-research-paper/cache/
├── manifest.json              # index of all cached papers
├── arxiv/
│   ├── 2403.01234.json
│   └── 2005.11401.json
├── doi/
│   ├── 10.1145_3589334.json
│   └── ...
├── url/
│   └── <sha256-hash>.json
└── topics/
    └── <topic-slug>.json      # topic → list of cached paper IDs

When the user asks about a topic (not a specific paper), the cache's topics/ index is searched first, before any live fetch.

Cache schema: workflows/caching.md.

---

9. Bundled corpus

Ships in corpus/:

• anchor-papers.yaml — ~30 canonical, high-impact papers across major topics (transformers, RAG, RLHF, contrastive learning, RCT methodology, PRISMA, etc.).
• topics-index.yaml — maps topic keywords to the anchor papers.

When the user asks for a paper that's in the corpus, the skill uses the corpus version (always available, even offline). Users can extend the corpus by adding files to corpus/user/.

---

10. Failure handling

• URL doesn't resolve → try arXiv ID extraction, then DOI lookup, then surface in Known-gaps.md.
• PDF unparseable → fall back to abstract-only rendering with a warning.
• Model couldn't extract figures → generate Mermaid alternatives.
• No headline numbers in results → use qualitative findings.
• Web tools unavailable → cache + corpus + model-knowledge in that order.

Full matrix: workflows/ingestion.md §10.

---

11. Where to look next

• Plan an ingestion → workflows/ingestion.md
• Pick visuals → workflows/visualization.md
• Cache protocol → workflows/caching.md
• Plain-English layer → prompts/plain-english.md
• Mind-map generation → prompts/generate-mindmap.md
• Output format → templates/visual-paper.md
• Bundled corpus → corpus/
• Fetch tools → toolchains/fetch_paper.py, toolchains/extract_pdf.py

This skill complements but does not require the other two:

• get-research-paper → find papers
• research-paper → write papers
• read-research-paper → read papers (this one)