Papers Reading Skill for Codex

PaperReading Core Adapter

Workflow

• Establish the supplied-source boundary. Identify which title, author, journal, date, DOI, page, section, table, figure, equation, appendix, and full-text surfaces are actually available.
• For UTF-8 text or Markdown, run paperreading ingest <source> --output <document.json>. Use the resulting source, section, block, character-range, and hash metadata; do not invent locators.
• Read the abstract and introduction, theory or hypotheses, data and variables, research design, baseline results, mechanisms, heterogeneity, robustness or endogeneity checks, conclusion, and relevant appendix material.
• Build a v0.3 PaperPackage using references/paper-record.md. Keep GroundedPaperRecord, EvidenceSpan, and ResearchAnalysis conceptually and structurally separate.
• For an existing v0.2 record, run paperreading migrate <record.json> --output <package.json> rather than rewriting it manually. Preserve the resulting migration notes and unverified state.
• Run paperreading validate <package.json>. When a matching PaperDocument exists, also run paperreading verify <package.json> --document <document.json> --strict --output <verified.json>.
• Resolve every validation error before export. Keep partial or failed verification visible; never upgrade a package to verified by assertion.
• Produce only the user-selected output. Load references/reading-fields.md when reviewing the legacy 13-field projection or workbook style.

Evidence protocol

• Record a source claim only when the paper explicitly states it and bind it to at least one evidence ID.
• Record a finding only when supplied text, table, figure, equation, or appendix material supports it.
• Keep researcher or AI-assisted assessment outside the source-grounded record.
• Preserve null results, caveats, sample limits, identification limits, conflicts, and unresolved fields.
• Never fabricate a quotation, page, section, block, table, column, figure, equation, appendix, variable, model, test, ranking, or causal claim.
• Treat traceability as locator specificity, not truth, study quality, causal validity, or external validity.
• Treat source-content verification as a resolution check against the supplied document, not proof that the paper's methods or conclusions are correct.
• Do not translate one journal-ranking system into another. Record only independently verified labels with their source and version boundary.

Causal and analysis boundaries

• Use causal language only when an eligible design and an explicit identification strategy support it.
• Preserve stronger wording made by the paper as a source claim when necessary, but keep the PaperReading assessment and caveats separate.
• Put proposed research extensions in ResearchAnalysis; never present them as paper findings.
• Ground each extension in a reported limitation, evidence boundary, contradiction, or identification constraint, and include at least one executable design element.

CLI operations

Initialize a local project and ingest a supported source:

paperreading init
paperreading ingest source.md --output document.json

Migrate a v0.2 record:

paperreading migrate record.json --output package.json

Validate and, when the matching document exists, verify a v0.3 package:

paperreading validate package.json
paperreading verify package.json \
  --document document.json \
  --strict \
  --output verified-package.json

Review or export without changing a workbook:

paperreading project package.json
paperreading export package.json review.md --format markdown
paperreading export package.json package.normalized.json --format json

Append through the compatibility projection only after the user authorizes the workbook destination:

paperreading export package.json literature.xlsx --format excel --sheet 中文

The legacy scripts/append_paper_reading.py entry point remains a compatibility wrapper for existing 13-field JSON. Prefer the CLI for new workflows.

Current implementation boundary

• Core ingestion supports UTF-8 text and Markdown only.
• PDF parsing and provider-driven automatic extraction are roadmap capabilities, not current Core behavior.
• If the host can inspect another supplied format, record that review boundary honestly, but do not claim paperreading verify ran without a matching PaperDocument.
• Batch processing, SQLite search, cross-paper synthesis, gap discovery, and method-specific auditing are not implemented.

Mutation rules

• Produce draft, validation, or stdout output when no destination is explicitly provided.
• Do not overwrite JSON or Markdown unless the user requests replacement and --force is used.
• For Excel, require an explicit path or existing PAPER_READING_WORKBOOK configuration.
• Treat duplicate_skipped as a successful no-op and report the existing worksheet row.
• Treat schema mismatch, unresolved evidence, failed validation, locked workbook, or write error as a hard stop.
• After a successful Excel append, report the worksheet, appended row, and timestamped backup path.

If the paperreading command is unavailable, report that the Core package and any required exporter extra must be installed. Do not bypass the validator or reimplement workbook mutation ad hoc.