oprogramadorreal/optimus-claude/paper-init

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, affected target IDs, scope revision), and local_files — every acquired source file mapped to its role, SHA-256, and exact acquisition record (URL or command, and date; for a file the user supplied, the path it came from). Do not hash the metadata file into itself. Include clarifications and supplementary sources. Add any further bibliographic fields the source offers. The test: a fresh clone can re-acquire every publicly fetchable file from this record alone.

3. Working forms

Extract a short paper inline. Otherwise delegate substantial, independent source sections to readers launched as Agent tool calls in a single message, each given explicit sources, required provenance, and absolute paths; reconcile conflicts and coverage yourself before writing the final bundle.

• paper/paper.md — a complete transcription, not a summary: mirrored

section headings, math in LaTeX, figures as local relative links with their captions, tables inline (escape hatch: a separate tables.md when tables are numerous or large, linked both ways). Open with a provenance header naming the source of record. Its length is the paper's own.

• paper/spec.md — only what the sources state, each fact tagged with its

source and section: data and preprocessing, architecture, training procedure (including stated hardware, time, scale, and seed/repeat policy), evaluation and metric definition, baselines, ablations, and reported results. Architecture/training/eval tables carry a "defined enough to implement?" column. Anything inferred, chosen, or assumed is labeled as ours or moves to open-questions.md — never present our choices as the paper's. End with a short "reported targets" section: externally meaningful results (numbers, and figures where the claim is qualitative), with metric, data, protocol, and spread the paper reports, plus the cheaper checks the paper states along the way (dataset counts, parameter counts, a loss reached) that let part of the implementation be judged before a full run exists. A target the bundle cannot yet measure — data not on disk, a scorer or protocol undefined — says what is missing. Give targets stable IDs and preserve the original values even when the project selects reduced scope. Link empirical targets to acceptance.md; for a non-empirical paper they are the standalone bar, and a differing selected scope gets a labeled Selected targets section below them. Keep the file under ~200 lines; link detailed method tables when needed, never omit implementation-critical facts just to meet the length guide.

• paper/references.md — every reference the paper cites, annotated: role

(dataset, baseline, method), resolved link, fetch priority.

• paper/open-questions.md — everything undefined, ordered by how much it

blocks work: missing hyperparameters, ambiguous procedures, figure/table defects (ledgered in figures/README.md — point there, don't duplicate), credibility issues, and a suggested framing for the implementation, tech stack included (drawn from the paper and the project's existing stack if one exists). An open point with a defensible default says so and where it comes from (reference code, a cited work, common practice), so an unattended implementation run proceeds instead of stalling on it. Give questions stable IDs, status (unresolved, assumed, resolved, superseded), affected target IDs, evidence, and the decision's rationale and consequences. Keep resolved choices and deviations as a durable decision history, linking scope decisions to their authoritative record in metadata.json. Mark a finding [verified] only when checked against local files during preparation — never for inference or empirical reproduction. Open with that legend. Settle what the sources can settle now: no verifiable-now TODO leaks into implementation. Keep it under ~150 lines, moving resolved history to linked overflow when necessary.

For a paper with empirical claims, read references/empirical-reproduction.md now and prepare acceptance.md using its contract. For a survey or proof without empirical claims, skip it.

When the paper defers load-bearing content to a citation — an inherited architecture, a borrowed training procedure, a dataset defined there — the bundle's contract covers that content too: fetch each such cited work's sources now, as in step 2, into paper/cited/<slug>/, and record each in a cited_works array in metadata.json (title, identifier, source revision, slug, license, acquired-file hashes, and the acquisition record — URL and date, or the path it came from for a user-supplied file). Pull the specific facts it needs from it into spec.md or open-questions.md, tagged with provenance, and note in references.md why it was fetched — a work the paper itself never cites gets its own entry there. Apply the same test to each fetched work: when it defers content the implementation still needs to a further work, fetch that one too. Sources and targeted extraction only — no bundle per cited work. Expect a handful of works, not a bibliography crawl: the test is dependence, not relevance. An inaccessible cited work stays a visible gap — record what is deferred to it in open-questions.md and report it in the final message so the user can supply a copy.

If producing the bundle took mechanical extraction work a fresh session could not trivially redo (pulling rasters out of a PDF, dumping text from an EPUB), leave one small regenerator script that reproduces those derived artifacts from paper/source/ offline (placement follows project conventions; when the project has none, paper/). Stamp only script-produced files with a do-not-hand-edit header — the model-authored files (paper.md, spec.md, and the rest) stay hand-editable, and a re-run updates them in place. When you leave one, ensure .gitattributes pins the script's outputs — eol=lf for generated text, binary for extracted rasters — so regeneration stays diff-clean on any platform.

4. Reference code