/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 files and updates .gitignore 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` — bundle index: what this is, the read-first order,

current status. Under ~50 lines.

• `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, one README

line each (file, dimensions, caption) with known defects — duplicates, missing diagrams — at the top.

• `paper/references.md` — every reference, annotated: role (dataset,

baseline, method), resolved link, and fetch priority.

• `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);

gitignored, its provenance tracked in `metadata.json`.

• `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:gauntlet`.

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. A `.git` file alone does not distinguish them from submodules. 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 detects a multi-repo workspace, ask which repo the paper work targets before writing anything — bundle, `.gitignore`, and README block all land there; when it finds no recognized structure, work in the current directory.

If a bundle already exists, apply **Re-running** before the first write: resolve the paper identity and bundle root, read its metadata and available evaluation records, and preserve any bar/source versions that would be replaced.

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` (wit