paperconan

paperconan scans paper source-data tables and can register local image assets for external Agent review. Treat every hit as signal, not verdict: report locations and patterns, never intent or personal accusation. PaperConan does not manage model keys or provider SDKs and does not perform autonomous semantic judgment.

Tool repository: https://github.com/zixixr/paperconan Full unabridged skill text: references/full-skill.md

Core Workflow

0. Ensure the CLI is available: run paperconan --version; if missing, install it (see Install And Run). If Python/pip is unavailable, ask the user to install and run locally — never invent output.
1. Confirm what the user supplied:
   • Local source-data directory: run paperconan <input-dir>.
   • DOI or title: run paperconan fetch "<DOI or title>", choose a matched tabular dataset, download it, then scan the downloaded directory.
   • Only an existing audit: read audit/scan.json, use audit/report.html as the evidence browser to triage, then give an adjudicated answer. Do not hand the raw report.html over as "the result" (see Report Positioning).
2. Prefer the real CLI. Do not invent findings from eyeballing tables.
3. Read the scan in layers — start with paperconan overview, not by parsing the whole scan.json.
4. Open the original table before describing a serious finding as worth follow-up. If the original data is unavailable, say the finding is unverified.
5. Answer cautiously: explain the anomaly, plausible benign explanations, and what human context is needed.

Reading A Scan In Layers

One supplement routinely produces hundreds to thousands of findings; detectors deliberately run wide, and the narrowing happens in how you read.

paperconan overview audit/scan.json                    # which locations carry signal
paperconan drill    audit/scan.json 2                  # that location, grouped by kind
paperconan drill    audit/scan.json 2 --kind identical_column
paperconan explain  audit/scan.json seed:17942ad206854a66
paperconan explain  audit/scan.json seed:17942ad206854a66 --full

Add --json when you need structure. Work down and stop at the shallowest layer that answers the question: overview → drill → drill --kind → explain.

Rules that keep the reading honest:

• Evidence windows are bounded, and say so. A trimmed window states its scale (! this window is 20x30 of a 300x200 block). When exact cells matter, explain --full re-reads the source — and refuses with a reason if the source moved, was edited, or lost the covered rows/columns.
• detector=high displayed=low means a display profile down-weighted the finding, not that it is benign. explain prints the recorded reason; judge it yourself.
• Read the ! and scan: lines — every layer has them. They report what was not shown or examined: unread files, missing formula caches, detector candidate/finding/compute caps, report block limits. Any such line means scan_status is not complete and a quiet result is not evidence of a clean input. Re-run with the matching PAPERCONAN_* cap raised or on a narrowed input.
• A quiet overview is not a clean paper. It means these detectors found nothing at these thresholds in the data supplied.

Adaptive Image Review

When the user requests image review or figures accompany the numeric material: run paperconan <input-dir> --images. Read every image_assets entry; image_findings are optional hints, never the complete review set. If the current Agent cannot open local images, set image_review.status: unavailable_no_multimodal and say semantic image review was not completed. Record exactly one coverage outcome per asset (reviewed/unresolved/unreadable/deferred_asset_ids). Check labels, channels, processing, shared controls, insets and Methods before escalating a similarity signal. Cross-asset comparison is the external Agent's job; its conclusions go into verdict.json findings[] (finding_type: "image", with image_refs), then one unified paperconan report — never a second separate report.

Review Modes

Choose the lightest mode that satisfies the request: single-paper scan (concise adjudicated answer), formal review (adjudication-tiers + report-templates; Tier labels are review priority, never author-intent), batch review (batch-workflow; keep deterministic output separate from agent judgment, preserve DROP reasons), adversarial review (adversarial-review; for Tier 1/2, PubPeer drafts or filter changes, try to refute the concern before confirming it). Write the full eight-section report only for Tier 1/Tier 2 KEEP, PubPeer-style drafting, formal notes, or on explicit request.

Report Positioning

The pipeline is scan → agent triage/judgment → adjudicated report:

• audit/report.html from the bare CLI is a deterministic evidence browser — a false-positive-heavy triage worklist representing no judgment. Never present it as "the audit result".
• The user-facing deliverable is always agent-adjudicated: a short adjudicated summary, or the eight-section report (paperconan report scan.json --verdict verdict.json --out …) for Tier 1/Tier 2 KEEP and formal/public writing.

Tell plain-CLI users that raw findings still need human/agent triage before they mean anything.

Install And Run

pip install paperconan
pip install "paperconan[image]" # image assets, PDF page rendering, optional hints
pip install "paperconan[all]"   # includes PDF / Word table extraction
paperconan --version
paperconan <input-dir>          # writes <input-dir>/audit/{scan.json, report.html}

If pip install is rejected with a PEP 668 externally-managed-environment error (Homebrew/Debian Python), install into an isolated environment instead of forcing --break-system-packages:

uv tool install "paperconan[all]"   # or: pipx install "paperconan[all]"
# or: python3 -m venv ~/.venvs/paperconan && ~/.venvs/paperconan/bin/pip install "paperconan[all]"

Useful variants: --out DIR, --md, --no-html, --profile forensic, --images, --image-diagnostics, and paperconan report scan.json --verdict verdict.json --out adjudication.html.

If Python or package access is unavailable, tell the user to run the command locally; a manual look may be offered only as a clearly-labeled non-authoritative hint, never as paperconan output.

Fetching Data

Only when the user gives a DOI/title instead of local files (needs outbound network):

paperconan fetch "<DOI or title>"            # add --json for structure
paperconan fetch "<DOI>" --download <id> --out data/
paperconan fetch "<DOI or title>" --auto --images --out data/

Prefer candidates with doi_in_related: true. Repository search can return unrelated deposits, so report weak matches honestly; "no data found" never means "paper is clean". Do not bypass paywalls or scrape publisher sites.

Profiles

--profile {review,forensic,triage}: review (default) keeps likely false positives visible but may demote them to low; forensic preserves raw detector severity; triage hides likely false positives. When profile_action is demoted/hidden, use prefilter_reason, prefilter_flags and false_positive_context to judge whether the filter reason fits the table. Image hints bypass the numeric prefilter.

Reference Routing

Load references only when needed:

• references/output-schema.md: before parsing scan.json fields.
• references/detectors.md: detector kinds and their common false positives.
• references/judgment-rubric.md: ranking findings, PubPeer/integrity language.
• references/interpretation.md: final answers; requests to accuse or escalate.
• references/adjudication-tiers.md: before assigning Tier/KEEP/DROP/NEEDS_HUMAN.
• references/report-templates.md: formal reports, PubPeer drafts, verdict JSON.
• references/adversarial-review.md: before confirming Tier 1/2 or public claims.
• references/batch-workflow.md: multi-paper queues.
• references/case-patterns.md: synthetic calibration only, never real-case precedents.
• references/full-skill.md: the complete unabridged skill text.

Judgment Discipline

• Never convert severity or Tier 1/2/3 into an author-intent conclusion; they mean anomaly strength and follow-up priority.
• Inspect cross-sheet reuse and cross-column transforms before weaker single-column patterns.
• Prefer benign structural explanations first: shared controls, re-plots, unit conversions, formulas, indices, ratios, normalized values, model outputs, detection floors, bounded scales.
• Treat within_col_* findings as false-positive-heavy by default; do not strongly report n < 10, categorical labels, derived columns, fixed-denominator ratios, rounded grids, floors/ceilings, repeated fills.
• Use "needs human context" when row independence, raw-measurement status, formula generation, or Methods/legend meaning cannot be confirmed.
• For PubPeer-style writing, give concrete file/sheet/column evidence and questions for the authors; never accuse or state intent.

A normal scan summary includes: what was scanned and parse failures; highest-priority findings after triage, grouped by file; concrete evidence (kind, location, rule, n, value sample); plausible benign explanations; a pointer to report.html. If asked for an author-intent conclusion, answer that paperconan cannot determine that; the next step is verifying original data and, if concerns remain, clarification via PubPeer, the journal, or a research-integrity office.