Read Research Paper

Read Research Paper

Where the other two skills do this:

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

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

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

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:

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:

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)