English · العربية · Español · Français · 日本語 · 한국어 · Tiếng Việt · 中文 (简体) · 中文（繁體） · Deutsch · Русский

Paper Revision Skill

Plan-gated manuscript revision for LaTeX papers, reviewer responses, redlines, and proof corrections.

Paper Revision Skill turns manuscript revision into a controlled agent workflow:

Plan first. Edit second. Verify from the PDF. Commit the work package.

It is designed for academic papers where uncontrolled agent edits are expensive: major revisions, response letters, Supplementary Material, figure and equation references, latexdiff redlines, proof corrections, and final submission packages.

Agent Compatibility

This repository is built to work across agent platforms while keeping SKILL.md as the single source of truth.

Platform	Status	Entry Point
AgInTiFlow	Highlighted target. Install as a SkillMesh skill for project-aware paper revision.	Tool: https://flow.lazying.art · Repo: https://github.com/lazyingart/AgInTiFlow · Instructions: HANDOFF.md
Codex	Install into $CODEX_HOME/skills/paper-revision-skill.	SKILL.md and AGENTS.md
Claude Code	Use the repo-local Claude instruction file.	CLAUDE.md
GitHub Copilot	Use repository instructions for Copilot Chat and coding assistance.	.github/copilot-instructions.md
Gemini CLI	Use the repo-local Gemini instruction file.	GEMINI.md

AgInTiFlow compatibility requires @lazyingart/agintiflow >= 0.20.191, which can import Codex-style name: skill frontmatter into SkillMesh by normalizing it to AgInTiFlow-native id: and label: metadata.

Companion Skill

Pair this repository with Paper Critique Skill:

Need	Use
Review, critique, score, challenge, or generate reviewer-style comments	Paper Critique Skill
Respond to critique, revise manuscript text, build PDFs, generate redlines, or prepare response letters	Paper Revision Skill

In short: critique reviews the paper; revision answers the critique and produces the response package.

Why This Exists

AI agents are strong at file editing, builds, search, and bookkeeping. They are less reliable when they must simultaneously decide the scientific strategy, rewrite text, update response letters, compile LaTeX, and infer what should not be touched.

This skill separates the workflow:

Phase	Purpose	Artifact
Think	Diagnose reviewer or editor intent	references/<task>_plan.md
Gate	Human reviews scope and reasoning	approved plan
Execute	Codex edits only within the plan	main.tex, sm.tex, response letter
Verify	Build, inspect PDF, generate redline	PDFs and redlined_*.tex
Record	Commit the completed work package	git commit

Workflow

Reviewer comment or proof query
              |
              v
       Draft response logic
              |
              v
  Save a markdown revision plan
              |
              v
       Human checks scope
              |
       +------+------+
       |             |
       v             v
   Plan OK       Split/refine
       |
       v
  Codex applies only the plan
       |
       v
 Build clean PDF and redline
       |
       v
 Inspect current PDF locations
       |
       v
 Update response or proof note
       |
       v
 Commit and push

Quick Start

Use the active skill:

Use $paper-revision-skill to revise this paper.
First create a plan in references/.
Do not edit outside the plan.
Build the manuscript and redline after execution.

For a manuscript repository, keep this convention when possible:

paper-project/
  Manuscript/
    main.tex                 # current latest main manuscript
    sm.tex                   # current latest Supplementary Material
    original_main.tex        # frozen previous baseline
    original_sm.tex          # frozen previous supplement baseline
    redlined_main.tex        # generated diff
    redlined_sm.tex          # generated diff
  ResponseLetter/
    response_letter.tex
  references/
    reviewer1_comment1_plan.md
  build_all.sh

What Is Included

Path	Use
SKILL.md	Active Codex skill instructions
HANDOFF.md	Short install and handoff note for collaborators
AGENTS.md	Agent-neutral repository instructions that point back to SKILL.md
CLAUDE.md	Claude Code handoff instructions
GEMINI.md	Gemini CLI-style handoff instructions
.github/copilot-instructions.md	GitHub Copilot repository instructions
i18n/SKILL.zh-Hans.md	Simplified Chinese version of the skill guide
references/plan-first-revision-method.md	Full method for plan-gated revision
references/latex-revision-file-map.md	File conventions for latest, original, and redlined versions
references/response-letter-proof-workflow.md	Response-letter and proof-correction patterns
references/origin-chat-plan-gated-revision.md	Cleaned origin conversation and teaching guide
docs/origin-chat.html	Visual chat guide with diagrams and practical tips
templates/revision_plan.md	Plan template before each substantial edit
templates/response_trace_audit.md	Response-letter verification template
templates/revision_task_index.md	Index for many plans
prompts/plan_prompt.md	Prompt for a strategist or reasoning agent
prompts/apply_prompt.md	Prompt for an execution agent
prompts/audit_prompt.md	Prompt for a PDF and response-letter auditor
scripts/build_all_revision_artifacts.sh	Generic all-artifacts build helper
scripts/build_revision_redlines.sh	Generic LaTeX manuscript and redline helper
scripts/pdf_location_audit.py	PDF-backed location search helper

Three Agent Roles

Role	Does	Avoids
Strategist	diagnoses comments, drafts response logic, writes the plan	direct TeX editing
Executor	applies approved plan, builds PDFs, generates redlines	changing scope or inventing claims
Auditor	checks PDFs, locations, references, and response fidelity	adding new manuscript content

Standard Codex Instruction

You are working on an academic manuscript revision.

First read the relevant plan in references/.
Do not edit anything outside the plan.
If the plan is too broad or vague, stop and propose a smaller plan.
Apply only the approved edits.
After editing, update the plan's Execution Notes.
Run the build command.
Inspect the generated PDF if available.
Update the response letter only with verified changes.
Generate the redlined version when a baseline is available.
Show git diff summary.
Commit and push this work package.

Build Helper

The all-artifacts helper compiles common manuscript, supplement, response-letter, cover-letter, and redline files when they exist:

./scripts/build_all_revision_artifacts.sh .

The redline helper compiles current files, generates redlines, and compiles the redlined TeX:

./scripts/build_revision_redlines.sh Manuscript

Override names when needed:

MAIN_BASELINE=major_revision_main.tex \
SM_BASELINE=major_revision_sm.tex \
REDLINED_MAIN=redlined_minor_main.tex \
REDLINED_SM=redlined_minor_sm.tex \
./scripts/build_revision_redlines.sh Manuscript

PDF Location Audit

Use the compiled PDF as the source of truth for response-letter locations. The helper below finds candidate page and paragraph anchors:

./scripts/pdf_location_audit.py Manuscript/main.pdf "paragraph beginning text" "Figure 2"

Treat extracted text line numbers as search aids, not journal line numbers. For final response letters, prefer page, section, figure/table/equation, visually confirmed column, and paragraph-beginning anchors.

Visual Origin Guide

Open the HTML guide locally or through GitHub Pages:

• Live guide on GitHub Pages
• Website language pages
• docs/origin-chat.html
• references/origin-chat-plan-gated-revision.md

GitHub README files cannot safely embed local HTML or iframes, so the visual chat is published as a separate GitHub Pages page and linked from this README.

The guide explains the original conversation behind the method, with the unrelated parts removed and the practical workflow expanded.

Support

Donate	PayPal	Stripe

Contact

Build less. Revise cleaner.