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.