add-research-paper

name	Add research paper
description	Add a new research paper to the library — fetch the paper, write a structured summary to `docs/upstream/papers/`, implement its technique as a standalone Python module in `resources/techniques/`, and register it in `references/papers.md`.
compatibility	opencode

Paper Technique Library

Add a new research paper to the library — fetch the paper, write a structured summary to docs/upstream/papers/, implement its technique as a standalone Python module in resources/techniques/, and register it in references/papers.md.

Load this skill when the task involves: pull paper, fetch arxiv, implement technique from paper, add paper to upstream, or correct an existing paper entry.

Where things live

• Paper summaries: docs/upstream/papers/{slug}.md
• Technique modules: resources/techniques/{slug}.py
• Library index: references/papers.md — all papers currently in the library with their slugs

Slug convention: {firstauthor}{year}{keyword} (e.g. lou2024sedd, chen2026attnres, jaegle2021perceiver). The keyword is the most distinctive word from the title or method name — short enough to be memorable, specific enough to be unambiguous. The arXiv ID belongs in the summary header and BibTeX, not in the filename.

Paper summary format

See full template in references/templates.md (bundled with this skill). Key sections:

• Title, authors, year, venue, arXiv link
• Abstract (1–3 sentences, verbatim or close paraphrase)
• Key Contribution (2–4 sentences: what's new, what problem it solves, the core mechanism)
• Relevance to PDLI Experiment (why it matters — which notebook, component, or hypothesis)
• Techniques Implemented table (or "None — evaluation benchmark only")
• BibTeX citation

Technique module format

Architectural and algorithmic papers get a Python module in resources/techniques/{slug}.py. Evaluation benchmarks, surveys, and purely theoretical papers get a summary only.

See full template and rules in references/templates.md. Essential constraints:

• Vertically sliced — each file is fully self-contained. No imports from sibling technique modules. If a function from another technique is needed, inline it with a comment crediting the source paper.
• No config.py dependency — all dimensions and hyperparameters are explicit constructor args with type annotations.
• from __future__ import annotations at the top of every file.
• Shape comments on every non-obvious tensor: # [B, S, D]
• Exported: section in the module docstring listing every public symbol.
• After writing or modifying a module, verify: python -c "from resources.techniques.{slug} import {ClassName}; print('OK')"

Fetching a paper

• arXiv: Use webfetch("https://arxiv.org/abs/{arxiv_id}") for abstract/authors; https://arxiv.org/html/{arxiv_id} for method detail.
• Non-arXiv: webfetch the canonical URL or https://doi.org/{doi}.

Registering a paper

New papers go in references/papers.md under the appropriate section (Architectural/Algorithmic, Evaluation Benchmark, or Theoretical/Alignment). Match the existing table format.

Downloading the PDF

After registering, always download the PDF:

source .venv/bin/activate && python tools/pull_pdfs.py {slug}

Or on Windows:

.\.venv\Scripts\python tools\pull_pdfs.py {slug}

This saves docs/upstream/pdfs/{arxiv_id}-{slug}.pdf. The script reads both references/papers.md and docs/upstream/papers/ to resolve slugs.

For multiple papers:

python tools/pull_pdfs.py {slug1} {slug2} {slug3}
python tools/pull_pdfs.py --all       # everything not yet downloaded

Papers without an arXiv ID are skipped automatically — note this in the paper summary under a **PDF**: Not available on arXiv. line.