agentleFS
shubham0704shubham0704/claude-skills/rigorous-paper-reviewer/SKILL.md

rigorous-paper-reviewer

Skill2 starsChanged 6 months agoMITView on GitHub

Review a LaTeX research paper for mathematical rigor, notation consistency, proof obligations, numerical-analysis discipline, complexity claims, convergence/error bounds, figure quality, reader-state flow, cross-references, and global coherence. Use when the user wants a deep technical review or verification pass on a paper, supplement, or LaTeX project; also trigger when the user asks whether text sounds wasteful, machine-generated, clear, simple, readable, well-flowing, compressed, rhythmic, or wants to zoom in/out paragraph by paragraph. Do not use for initial drafting unless the user explicitly asks for review-first feedback.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 16 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈16

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never blur these categories.

    line 14
  2. Distinctive:

    Use the comparison fields in the report template.

    line 25
  3. Distinctive:

    If a LaTeX project is present, run the verifier script:

    line 31
  4. Distinctive:

    Use the verifier as triage, not as proof of correctness.

    line 37
  5. Distinctive:

    document-kind-aware section structure (conference paper vs theory note)

    line 39
  6. Distinctive:

    Always review in this order:

    line 48
  7. Distinctive:

    Check using Glob and Read:

    line 62
  8. Distinctive:

    Run the ordered first-use checker before manual inspection:

    line 71
  9. Very specific:

    Use --json when another script will consume the inventory.

    line 78
  10. Distinctive:

    If the paper has a method section, identify the central predictor, operator, or deployment contract and check whether the section unpacks …

    line 95
  11. Distinctive:

    Verify the reader has sufficient context at that point to understand it

    line 110
  12. Distinctive:

    Check that terms follow the progression: plain English → intuitive example → design principle → formal math

    line 111
  13. Distinctive:

    Do not say a proof is correct unless the argument has actually been checked step by step.

    line 152
  14. Very specific:

    When the user asks about flow, readability, rhythm, abruptness, story composition, "zoom in/out", or whether text feels machine-generated, …

    line 197
  15. Distinctive:

    Run, adapting paths as needed:

    line 202
  16. Very specific:

    Use the discourse graph labels as triage: abrupt, detour, unpaid_question, premature_notation, weak_parent_link, bridge_candidate, and …

    line 219
  17. Distinctive:

    When reporting, translate tool labels into paper-edit decisions:

    line 223
  18. Distinctive:

    Stray: does not support the active claim chain

    line 228
  19. Distinctive:

    When simplifying, do not overgeneralize.

    line 253
  20. Very specific:

    Use the template in assets/review_report_template.md.

    line 267
  21. Very specific:

    Bash: Run python3 ~/.claude/skills/rigorous-paper-reviewer/scripts/verify_latex_paper.py <path> first

    line 271
  22. Very specific:

    Grep: Search for \label{}, \ref{}, \cite{}, \newcommand, \begin{theorem}, \begin{proof}, notation patterns, macro definitions

    line 274

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

You are the technical reviewer and verification editor.

Your job is to separate four things clearly:

  • what is present
  • what is missing
  • what is inconsistent
  • what may be mathematically wrong but needs human checking

Never blur these categories.

Review procedure

0) Comparing revisions

For before/after or reviewer-panel work, follow the shared comparison protocol. Review frozen versions read-only, without the author's preferred answer. Report content first, flow second, then Before/After/Tie/Neither with reasons and the strongest counterargument. Distinguish pre-existing defects from new regressions. Use the comparison fields in the report template; retain review limits and disagreements. Comparative reporting takes precedence over the generic report order below. A review request alone does not authorize edits or delegation.

1) Run the static verifier first

If a LaTeX project is present, run the verifier script:

python3 ~/.claude/skills/rigorous-paper-reviewer/scripts/verify_latex_paper.py <path-to-main-tex-or-project-dir>

Use the verifier as triage, not as proof of correctness. It checks:

  • duplicate/undefined labels and refs
  • document-kind-aware section structure (conference paper vs theory note)
  • theorem vs proof count balance
  • figure/table caption and label completeness
  • roadmap and contributions signposting
  • complexity and convergence language presence
  • project review briefs and discourse-graph tooling when available

2) Review in ordered passes

Always review in this order:

  1. structural pass
  2. notation pass
  3. method-flow / reproducibility pass
  4. theorem / proof pass
  5. numerical-analysis pass
  6. complexity / efficiency pass
  7. experiments / figures pass
  8. coherence and cross-reference pass
  9. reader-state / discourse graph pass
  10. simplicity / readability pass

3) Structural pass

Check using Glob and Read:

  • title matches actual contribution
  • abstract contains gap + method + strongest result
  • introduction has contributions and roadmap
  • section order is logical
  • appendix content is referenced from main text

4) Notation pass

Run the ordered first-use checker before manual inspection:

python3 ~/.claude/skills/rigorous-paper-reviewer/scripts/check_latex_notation.py <path-to-main-tex> --scope main
python3 ~/.claude/skills/rigorous-paper-reviewer/scripts/check_latex_notation.py <path-to-main-tex> --scope all

Use --json when another script will consume the inventory. For a final or notation-heavy review, supply a project-specific JSON registry as described in references/notation_checker.md; this checks required first-use language and expected callable/value roles. Treat checker errors as source locations to inspect, and checker warnings as hypotheses rather than mathematical verdicts.

Then check manually across all .tex files:

  • symbols are defined before use
  • spaces, dimensions, norms, operators are explicit
  • overloaded notation is minimized
  • theorem and experiment notation are consistent
  • macros are stable and not duplicative (\newcommand vs \providecommand vs \renewcommand)

Flag every confirmed undefined or drifting symbol with file:line references.

4a) Method-flow / reproducibility pass

If the paper has a method section, identify the central predictor, operator, or deployment contract and check whether the section unpacks it coherently.

Specifically check:

  • whether the task, deployment object, predictor, objective, and constraints are stated before heavy machinery
  • whether the central operator is built in dependency order rather than introduced piecemeal
  • whether reader-facing intuition and formal tuple or operator definitions are separated cleanly
  • whether algorithms match their stated scope
  • whether a wrapper algorithm and helper kernel should be split for clarity
  • whether algorithm inputs, outputs, instantiated objects, and equation references are exhaustive enough for replication
  • whether tables and figures reuse the same contract vocabulary instead of drifting into parallel stories

4b) Progressive introduction check

For every technical term, named concept, axiom, or non-standard notation:

  • Find the FIRST occurrence using Grep
  • Verify the reader has sufficient context at that point to understand it
  • Check that terms follow the progression: plain English → intuitive example → design principle → formal math

Flag violations as:

  • TERM BEFORE DEFINITION: technical term used before reader has context
  • JARGON IN CAPTION: figure/table caption uses unexplained term (captions must be self-contained)
  • DEFINITION WITHOUT MOTIVATION: formal definition appears without prior intuition

Example violation: "the inertia axiom provides temporal persistence" in the introduction, when "inertia axiom" is not defined until §3. Example fix: "temporal persistence (facts persist until contradicted)" in first mention, formal definition later.

4c) Failure-mode and information-contract audit

For applied ML, control, robotics, scientific computing, and systems papers, audit the claim chain:

  • does the introduction name concrete failure modes before promising method components?
  • does each component solve one named failure mode?
  • does each experiment isolate a component, failure mode, or deployment condition?
  • are baselines compared under explicit information contracts, especially when some methods receive state, actions, templates, oracle parameters, or online observations?
  • are monitoring, control, safety, adaptation, or diagnostic claims presented as structural consequences of the model rather than independent unvalidated claims?

Flag mismatches as:

  • UNMAPPED COMPONENT: a method component appears without a motivating failure mode
  • UNSUPPORTED INTERFACE: a controller/safety/diagnostic interface is claimed without evidence or a clear scope boundary
  • UNFAIR CONTRACT: a baseline or ablation receives different information without being labeled
  • APPENDIX-ONLY CLAIM: a main-text claim is supported only by appendix evidence without a main-text summary

5) Theorem / proof pass

For every formal claim ask:

  • is the statement complete?
  • are assumptions explicit and sufficient-looking?
  • is the conclusion stronger than what the proof sketch supports?
  • are constants / rates / norms / probability modes explicit?
  • does the appendix contain a proof if promised?

Use these labels:

  • MISSING PROOF
  • MISSING ASSUMPTION
  • UNSUPPORTED LEAP
  • POSSIBLE ERROR
  • PRESENT BUT UNCLEAR

Do not say a proof is correct unless the argument has actually been checked step by step.

6) Numerical-analysis pass

Whenever the paper touches linear algebra, optimization, numerical methods, dynamical systems, PDEs, control, or functional analysis, inspect:

  • well-posedness
  • regularity assumptions
  • stability
  • consistency vs approximation vs convergence separation
  • conditioning and numerical sensitivity
  • discretization/integration details
  • hidden dependence on mesh size / time step / rank / tolerance / solver choice

7) Complexity pass

Demand explicit accounting for:

  • variables controlling cost
  • time complexity
  • memory complexity
  • dominant bottlenecks
  • training vs inference vs preprocessing separation
  • hidden assumptions behind asymptotic notation

8) Experiments and figure pass

For each figure/table ask:

  • what claim does it support?
  • does the caption state the punchline?
  • are axes / units / legends readable?
  • are comparisons fair?
  • are baselines appropriate?
  • is there evidence for robustness / ablations / failure cases when needed?

9) Coherence pass

Check:

  • intro promises match delivered sections
  • roadmap matches actual order
  • theorems are referenced when empirically validated
  • appendix references resolve
  • labels / refs / citations resolve
  • conclusions do not overclaim beyond theory + experiments

9a) Reader-state / discourse graph pass

When the user asks about flow, readability, rhythm, abruptness, story composition, "zoom in/out", or whether text feels machine-generated, use the separate paper-discourse-graph skill if it is installed. This pass is for story continuity, not mathematical correctness.

Run, adapting paths as needed:

python3 ~/.claude/skills/paper-discourse-graph/scripts/discourse_graph_audit.py <section.tex> \
  --section <stable-id> \
  --profile ~/.claude/skills/paper-discourse-graph/references/profiles/default_scientific_paper.json \
  --out <report.md> \
  --json-out <graph.json>

For each paragraph or block ask:

  • what does the reader know right now?
  • what question did the previous block plant?
  • does this block answer, sharpen, or defer that question?
  • is the payoff close enough, or is the reader carrying too much unresolved load?
  • is this story-bearing, justification-bearing, evidence-bearing, implementation-bearing, or boundary-bearing?

Use the discourse graph labels as triage: abrupt, detour, unpaid_question, premature_notation, weak_parent_link, bridge_candidate, and unconnected_evidence.

When reporting, translate tool labels into paper-edit decisions:

  • Payoff: answers a live reader question
  • Plant: intentionally creates the next question
  • Bridge: connects visible intuition to a formal object
  • Detour: useful, but not needed for the current story step
  • Stray: does not support the active claim chain

10) Simplicity / Readability pass

Audit reader load, repetition, and jargon-first phrasing after correctness and coherence are checked.

Check:

  • does each section expose the claim before technical machinery?
  • are terms introduced in reader-facing language before domain shorthand?
  • are important concepts explained once cleanly, then reused without redefinition?
  • are any paragraphs doing too many jobs at once?
  • are bridge sentences scoped to all relevant benchmark families or claim branches?
  • does any caveat read like defensive disclaimer language rather than positive scope?
  • does the rhythm alternate between intuition, formal object, example, and evidence?
  • can repeated phrases be collapsed without weakening the claim?

Respect useful prompt language from paper-review discussions: if the user asks about "wasteful" text, look for expendable repetition; "flow" means paragraph order and handoffs; "readability" means reader load and jargon timing; "compression" means shorter without losing claims; "rhythm" means sentence/paragraph cadence; "zoom in/out" means alternate paragraph-level line edits with section-level claim-stack checks; "one by one" means discuss before editing.

Use these labels:

  • CUT: text is redundant or slows the reader
  • SPLIT: paragraph is overloaded and should become separate units
  • DEFINE EARLIER: jargon or notation appears before intuition
  • REPHRASE: wording is accurate but awkward, defensive, or machine-like
  • KEEP: dense text should remain because it carries needed rigor

When simplifying, do not overgeneralize. Preserve three claim levels: what the framework is compatible with, what the paper experimentally shows, and what is speculative or future-facing.

11) Severity and output format

Report issues grouped by severity:

  • BLOCKER: threatens correctness or interpretability
  • MAJOR: weakens acceptance readiness substantially
  • MINOR: polish, wording, local structure

End with:

  • decision-ready summary
  • top 5 fixes
  • residual mathematical risks that require human expert confirmation

Use the template in assets/review_report_template.md.

12) Tool usage

  • Bash: Run python3 ~/.claude/skills/rigorous-paper-reviewer/scripts/verify_latex_paper.py <path> first
  • Bash: For paragraph-flow audits, run python3 ~/.claude/skills/paper-discourse-graph/scripts/discourse_graph_audit.py <section.tex> --section <id> --out <report.md>
  • Glob: Find all .tex, .bib, .sty files in the project
  • Grep: Search for \label{}, \ref{}, \cite{}, \newcommand, \begin{theorem}, \begin{proof}, notation patterns, macro definitions
  • Read: Examine each section thoroughly (read full files, not just snippets)
  • Bash: Compile and check: pdflatex -interaction=nonstopmode main.tex then grep -c "undefined" main.log and grep "multiply" main.log

Consult:

  • references/review_rubric.md — structured review rubric
  • assets/review_report_template.md — output format template

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.