sci-paper

A Claude Code plugin for writing and reviewing scientific papers at the ApJ / MNRAS / PRD / JCAP / Nature-Physics level.

What it ships

Skill	Purpose
paper	Loads paper-writing standards (formula conventions, citation rules, anti-AI-ism hard rules, key references). Invoke before drafting.
paper-review	Forced source-traceable review pipeline. No memory, no keyword-grep-as-evidence, no guessing. Runs to convergence (0 red / 0 yellow).
figure-review	Renders compiled PDF at 150 DPI and reviews each figure as a human reader would actually see it (axis font sizes, legend readability, float placement).
paper-style	Loads a distilled style profile extracted from your curated corpus (top journals + mentor papers + high-value references) plus retrieves section-typed exemplar paragraphs. Constrains writing/rewriting to match observed human-academic patterns.
brainstorm	NEW (v0.4). Fully-automated radial research-direction explorer. Generates a "phylogenetic-tree" of ideas using 12 framings (first-principles / inversion / cross-disciplinary / adversarial / constraint-shift / scale extrapolation / substitution / office-hours / contrarian / failure-driven / high-risk-high-reward / meta-self-audit), derives each branch rigorously (math + literature + falsifiability), recurses on PROMISING leaves until convergence. Default --rounds conv runs until exhausted; cc-enslaver evidence rules enforced throughout.

Quick start

# 1. Install Python deps (numpy + pymupdf + sentence-transformers + sklearn)
pip install -r requirements.txt

# 2. Drop corpus papers into the field tier dirs:
#       style-corpus/wgl/tier-1-top/        ← top-journal .tex / .pdf
#       style-corpus/wgl/tier-2-mentor/     ← mentor's papers
#       style-corpus/wgl/tier-3-reference/  ← other high-value references

# 3. Build the profile end-to-end (extract → train classifier → warm cache).
#    First run downloads the sentence-transformers model (~80 MB; ~30 s).
python tools/build_profile.py

# 4. Register the plugin in your Claude Code session
claude --plugin-dir D:/Projects/sci-paper

# 5. Use it
#    - skill (Claude does the work)        :  /sci-paper:paper-style discussion
#    - manual exemplar retrieval           :  python tools/retrieve_exemplars.py --section method --topic "..."
#    - lint a draft (regex + ML classifier):  python tools/ai_ism_lint.py draft.tex --ai-classifier --summary

Why paper-style instead of "fine-tuning a model"

Fine-tuning Claude is not offered by Anthropic; LoRA-ing an OSS model on a small (~10–100 paper) corpus produces a writer strictly worse than Claude raw. The realistic path is explicit style extraction + retrieval-augmented exemplars:

1. Parse the corpus → quantitative features (section-conditional sentence-length distributions, transition-word inventory, em-dash vs en-dash counts, passive ratio per section, formula:text density, hedge-word frequency, opening patterns).
2. Compress to a style_dossier.md (~2k tokens) loaded into Claude's context when the skill is invoked.
3. Index representative paragraphs by section type (abstract / intro / method / results / discussion / conclusion); retrieve top-K at write time as positive anchors.
4. Extend the existing hand-written anti-AI-ism blacklist with data-driven evidence (words/phrases the corpus actually never uses).

This gives you what fine-tuning would, except: it's transparent (every rule traces to a corpus paper), editable (drop in new papers, re-extract), and small-data-friendly (RAG dominates fine-tuning at this corpus size).

See EVALUATION.md for the full feasibility analysis.

Project structure

The plugin is field-aware: a "field" is one subfolder under style-corpus/<field>/ and a corresponding style-profile/<field>/. v0.1 ships only wgl (weak gravitational lensing); add fields by creating new subdirs alongside it (e.g. cosmology/, ml-methods/). When only one field exists, all tools and skills auto-detect it; with multiple, pass --field <name> explicitly.

.
├── .claude-plugin/plugin.json    # plugin manifest
├── skills/
│   ├── paper/SKILL.md
│   ├── paper-review/SKILL.md
│   ├── figure-review/SKILL.md
│   ├── paper-style/SKILL.md      # --field aware
│   ├── brainstorm/SKILL.md       # v0.5; radial idea/problem tree with width × depth
│   ├── mainline/SKILL.md         # v0.8; structural spine reinforcer + cold-read sub-agent
│   ├── paper-attack-tree/SKILL.md # v0.9; brainstorm methodology applied to paper critique
│   └── final-review/SKILL.md     # v0.10; 5-skill orchestrator with per-skill isolation + stable-convergence loop
├── style-corpus/                  # user-populated; gitignored content
│   └── wgl/                       # current default field
│       ├── tier-1-top/            # top-journal exemplars
│       ├── tier-2-mentor/         # mentor's high-quality WGL papers
│       └── tier-3-reference/      # high-value WGL references
├── style-profile/                 # generated by tools/extract_style.py
│   └── wgl/
│       ├── lexicon.json
│       ├── sentence_stats.json
│       ├── transition_inventory.json
│       ├── exemplar_paragraphs.jsonl
│       └── style_dossier.md
└── tools/
    ├── build_profile.py           # one-shot orchestrator: extract → train → warm
    ├── extract_style.py           # corpus → dossier + JSONL exemplar bank
    ├── retrieve_exemplars.py      # cosine retrieval (sentence-transformers)
    ├── ai_ism_lint.py             # tier-graded regex + opt-in ML classifier
    ├── train_ai_ism_classifier.py # logistic regression on word 1–2 grams
    ├── extract_md_negatives.py    # harvest LLM-drafted prose for negatives
    └── ai_ism_negatives_handcrafted.txt

Installation (development)

From this repo:

claude --plugin-dir D:/Projects/sci-paper

Reload after edits:

/reload-plugins

Once invoked, skills appear as /sci-paper:paper, /sci-paper:paper-review, /sci-paper:figure-review, /sci-paper:paper-style (Claude Code namespaces plugin skills by plugin name to prevent conflicts).

Build the style profile (one-time + on corpus change)

1. Drop papers into style-corpus/wgl/tier-{1,2,3}-*/ (PDF or .tex source — .tex is preferred because parsing is exact, but PDF works via text extraction).
2. Run:

   python tools/extract_style.py --field wgl
   # (or just `python tools/extract_style.py` while wgl is the only field —
   # tools auto-detect single-field corpora.)

3. Inspect style-profile/wgl/style_dossier.md and edit by hand if any extracted pattern looks wrong. The dossier is the file that actually enters Claude's context, so it's worth a manual pass.

Add a new field later

mkdir -p style-corpus/<new-field>/{tier-1-top,tier-2-mentor,tier-3-reference}
# drop papers
python tools/extract_style.py --field <new-field>

After this, all tools/skills require explicit --field <name> because multiple fields are present.

Status

v0.10 — new final-review orchestrator (5-skill loop with per-skill isolated worktree sub-agents, stable-convergence required); paper-review extended with dimensions P (internal/draft language) and Q (reference precision via WebFetch).

• Skills (8): paper (writing standards + tier-graded anti-AI-isms with corpus-empirical frequency caps), paper-review (forced-source-traceable review across A–O dimensions, see v0.7 entry below), figure-review (150-DPI render), paper-style (dossier + exemplar retrieval + Tier-table policy pairing), brainstorm (radial 12-framing idea/problem tree with phylogenetic-tree width × depth model and no-defer enforcement, v0.5), mainline v1 (structural narrative-spine reinforcer; mandatory full-read with no grep-only / no memory / no guessing; audits along 7 positive dimensions — spine sharpening / language compression / narrative architecture / isolated readability / derivation completeness / logical soundness / chaining — and 8 negative dimensions — vague definitions / scattered spine / volume-over-precision / disconnected sections / unclear structure / missing academic narrative / context drift / low-information adjectives; explicit brainstorm-divergence consolidation pass; forbids transitional-phrase suturing of logical jumps; mandatory isolated-context cold-read 7-question readability check by an isolation: worktree sub-agent; zero-issue convergence hard loop), paper-attack-tree v0.9 (brainstorm's radial phylogenetic-tree methodology applied to paper critique: each node is one critique attacked via 12 framing passes — first-principles / inversion / cross-disciplinary reviewer / adversarial red-team / constraint variation / scale extrapolation / substitution / office-hours / contrarian / failure-driven / high-risk-fatal / meta; every leaf resolved to CONFIRMED with file:line + proposed_fix / REFUTED with file:line of paper's defense / MARGINAL for author judgment; hard ban on NEEDS-MORE-INFO defer; complements paper-review by covering open-ended adversarial angles a static checklist misses). Complements paper-review at multiple layers: paper-review covers per-claim correctness (predefined checklist), mainline covers structural spine, paper-attack-tree covers open-ended divergent critique), final-review v0.10 (5-skill orchestrator for pre-submission final pass: runs paper / paper-review / figure-review / mainline / paper-attack-tree each in its own isolation: worktree sub-agent every round, merges all issues, applies fixes, and loops until consecutive N rounds — default 2 — show 0 issues across all 5 skills; ITER_BUDGET 10 rounds by default with BREAK_WITH_USER_DECISION on cap hit; no silent skipping or premature completion allowed). First four skills ported from WGL with [WGL] markers; remove or replace those anchors when generalizing to other fields.

• paper-review v3.2 (v0.10 update): forced-source-traceable review across A–Q dimensions — A–J (math / physics / logic / language / AI-isms / structure / citations / data / interfaces / redundancy / reproducibility), K (host-level modern-physics-review M1–M9 merged in-process), L (systemic inconsistency / cross-section context discontinuity), M (mathematical / physical adversarial 3-pass), N (deep stale/wrong/redundant/drift sweep across 6 content types + residual-markup grep), O (process-artifact removal with update-not-accumulate hard constraint), P (internal development / research / draft language sweep — 4-class grep for placeholders / draft colloquialisms / experiment-log style / internal codenames, replaced with general academic language), Q (reference completeness + citation precision — missing-key-reference detection via WebSearch + per-\cite{} WebFetch verification that the cited paper actually supports the citing sentence, with CORRECT/WEAK/MISUSED/UNVERIFIABLE judgment); zero-issue convergence hard loop with new P=0 / Q-MISUSED=0 / Q-missing-key-ref=0 / Q-UNVERIFIABLE=0 added to the criteria table; mandatory isolated-context modern-physics-review final verification via isolation: worktree sub-agent.

• Tools (6): extract_style.py (.tex + .pdf via pymupdf blocks), retrieve_exemplars.py (sentence-transformers cosine + .npy cache + keyword fallback), ai_ism_lint.py (tier-graded regex + --ai-classifier

  • --summary), train_ai_ism_classifier.py (LR on word 1–2 grams; CV F1 ≈ 0.88 on wgl), extract_md_negatives.py (harvest negatives from your doc tree), build_profile.py (one-shot orchestration).

• Field-aware: auto-detect single field, require --field <name> when multiple. v0.3 ships only wgl populated.

See tools/README.md for the per-tool roadmap and EVALUATION.md for the design rationale.

License

MIT — covers the code, skills, documentation, and tooling authored in this repository. The style-corpus/ directory is user-populated and git-ignored (.gitignore blanket-denies style-corpus/**/tier-*/**), so no third-party papers or copyrighted materials are bundled or distributed with this plugin.