/paper-init

description: >-
  Prepares durable context for implementing and reproducing a paper from a
  URL, PDF, DOI, or arXiv id: sources, source-linked requirements, empirical
  acceptance criteria, uncertainties, scope, and data provenance under
  paper/. Downloads sources and datasets (into data/) and updates .gitignore,
  .gitattributes, and README routing. Context only: writes no implementation
  code and sets up no project stack.
disable-model-invocation: true
argument-hint: "<paper URL, PDF path, DOI, or arXiv id> [scope and resource constraints]"

Paper Init

Build the local context bundle a later session needs to implement a research paper: the paper itself, its figures and references, what it specifies, what it leaves open, and its data. Context only — no implementation code, no stack setup. Everything the implementer needs must end up on disk; nothing may depend on this conversation's context.

The bundle

One `paper/` directory at the project root holds everything paper-derived:

• `paper/README.md` — the bundle index (step 8).
• `paper/source/` — pristine originals only: the PDF (supplementary

material included) plus the best machine-readable form available (EPUB, HTML, XML, arXiv LaTeX source), exactly as acquired. Derived files (text dumps, extracted markup) never live here.

• `paper/source/metadata.json` — the provenance record (step 2).
• `paper/paper.md` — the faithful working transcription (step 3).
• `paper/tables.md` — overflow tables, only when the transcription takes its

escape hatch (step 3).

• `paper/figures/` + `paper/figures/README.md` — every figure and its

ledger (step 2).

• `paper/references.md` — every reference, annotated (step 3).
• `paper/cited/` — pristine sources of the works the paper, or a fetched

work in turn, defers load-bearing content to (step 3), when any were fetched. Nothing derived lives here.

• `paper/spec.md` — what the paper actually specifies (step 3), including

its original reported targets with stable identifiers.

• `paper/acceptance.md` — for empirical papers: selected scope, source-linked

requirements, experiment protocols, acceptance criteria, and the evidence a later implementation must produce. Prepared in step 3, reconciled in step 8.

• `paper/open-questions.md` — what the paper leaves open (step 3).
• `paper/dataset.md` — dataset provenance and re-acquisition, when the paper

uses datasets (step 6).

• `paper/reference-code/` — vendored existing code, when it exists (step 4).
• `data/` — the datasets themselves, gitignored, when any were acquired

(step 6).

Keep generated workflow framing tool-agnostic: "a fresh session", "the implementing agent", without `/optimus:*` commands. Preserve product/model names that occur in the paper or its evidence; faithful transcription takes precedence. The final chat message may name `/optimus:*` commands.

1. Resolve the paper

The invocation argument is a URL, a local PDF path, a DOI, or an arXiv id; if none was given, ask for one. Resolve DOIs and arXiv ids to the source of record. If the paper is inaccessible (paywall, dead link), say so plainly and either stop or proceed from a file the user supplies.

Use any supplied scope, resource budget, and reference-code restrictions; retain earlier authorized decisions without asking again. An unspecified budget does not authorize paid compute or services, or large downloads.

When `git rev-parse --is-inside-work-tree` returns `true`, resolve its `--show-toplevel` and proceed in that working tree, including linked worktrees. Otherwise read `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` and apply it: the bundle goes inside the target repo, not above it. When it finds one or more child repos, ask which one the paper work targets (confirm a lone one instead of suggesting `cd`) before writing anything — bundle, `.gitignore`, and README block all land there; when it finds none, work in the current directory.

If `paper/` or a `papers/*/` directory already holds a bundle, read `references/re-running.md` and apply it before the first write.

2. Acquire sources

Download into `paper/source/`, redundantly: the PDF whenever one exists (an HTML-only paper's publisher full text is the primary source), any supplementary material, plus the cleanest structured full text the publisher offers — the transcription cross-checks formats against each other. For arXiv papers, also pull the e-print source bundle (`https://arxiv.org/e-print/<id>`) when offered: the LaTeX source makes math transcription near-mechanical and ships figures at native resolution. Pull figure rasters into `paper/figures/` from whichever source has the best resolution (PDF-embedded usually beats web-served); keep native formats, never re-encode, and write `paper/figures/README.md` as they land — one line per figure (file, dimensions, caption from the paper text), known defects (duplicates, missing diagrams) at the top. Installing transient fetch or extraction tooling along the way (a PDF library, gdown, pandoc) is fine — that is not the project stack — but install it isolated (pipx, a scratch venv, `pip install --target` into a temp dir), never into the project's own environment.

Acquire public author clarifications, errata, and addenda that affect the method or results, recording their source and date. Do not contact authors without explicit authorization. Distinguish the paper version from later clarifications and keep conflicts visible until resolved.

`metadata.json` records at minimum: `title`, `authors`, `venue`, `published`, `doi`, `url`, `license`, `downloaded` (date), `code_available` (with the paper's own availability sentence when it states one), `dataset_referenced` (name, URL, whether the paper redistributes it — full provenance and re-acquisition live in `paper/dataset.md`), `source_revision` (version or publication revision), `scope_decisions` (every scope decision, supplied at invocation or taken in step 5: decision, rationale,