paper-revision

name

paper-revision

description

Revise academic paper text with colored markup tracking. Use when the user asks to "revise my paper", "address reviewer comments", "mark up changes", "do a revision pass", "prepare camera-ready with changes highlighted", or "self-revise the draft". Covers two revision modes: reviewer-requested revisions (wrapped in \rev for blue text) and self/agent-initiated revisions (wrapped in \selfrev for teal text). Use after the initial draft exists and changes need to be visible.

Paper Revision

Revise paper text with colored markup so every change is traceable. This skill applies after a draft already exists — you are modifying existing text, not writing from scratch.

Two Revision Modes

1. Reviewer-Requested Revision (\rev)

Use when addressing reviewer or meta-reviewer comments during a major revision round (journal revision, conference rebuttal, or shepherding). Wrap all changed text in \rev{...}, which renders in blue.

This lets reviewers quickly locate what changed in the revised manuscript. Many venues expect or encourage colored markup in revised submissions.

When to use:

• The user says "address reviewer comment", "fix what R2 asked", "revise per reviews", "major revision", or references specific reviewer feedback.
• Any text change that is a direct response to a reviewer's concern.

Example:

% Before
We train the model on ImageNet for 100 epochs.

% After (reviewer asked for training details)
We train the model on ImageNet for \rev{200 epochs with a cosine learning rate
schedule (initial lr = 0.001), following the protocol of Smith et al.~\cite{smith2023}}.

2. Self / Agent Revision (\selfrev)

Use when the author or the agent improves the text on their own initiative — not in direct response to a reviewer's request. Wrap changed text in \selfrev{...}, which renders in teal.

This distinguishes voluntary improvements from required changes, which is useful when co-authors review the revision or when the author wants to track what they changed beyond what reviewers asked for.

When to use:

• The user says "improve this paragraph", "polish the writing", "self-revise", or "do a revision pass" without referencing specific reviewer comments.
• The agent identifies unclear writing, weak claims, or style issues during a revision pass and proposes improvements.
• Co-author edits that are not tied to reviewer feedback.

Example:

% Before
Our method is better than the baseline.

% After (self-revision for precision)
Our method \selfrev{outperforms the baseline by 3.2 F1 points on the SQuAD
benchmark (Table~\ref{tab:main})}.

Required LaTeX Setup

Add these definitions to the preamble (or a shared .sty file). They require the xcolor package:

\usepackage[dvipsnames]{xcolor}

% Reviewer-requested revision markup (blue)
\newcommand{\rev}[1]{\textcolor{blue}{#1}}

% Self/agent revision markup (teal)
\newcommand{\selfrev}[1]{\textcolor{teal}{#1}}

Before making any edits, check whether \rev and \selfrev are already defined in the project's .sty files or preamble. If they exist, use the existing definitions. Do not redefine them.

Revision Workflow

Step 1: Identify the revision mode

Ask or infer from context:

• If the user provides reviewer comments or references a review → use \rev
• If the user asks for general improvement → use \selfrev
• If both apply (e.g., "address reviews and also polish the rest"), use \rev for reviewer-driven changes and \selfrev for everything else

Step 2: Make targeted edits

Revise the text in place. Wrap only the changed portions in the appropriate command — not entire paragraphs, unless the entire paragraph is rewritten.

Good — precise markup:

We propose a method that \rev{achieves state-of-the-art results on three
benchmarks (see Table~\ref{tab:results})} for code summarization.

Bad — wrapping unchanged text:

\rev{We propose a method that achieves state-of-the-art results on three
benchmarks (see Table~\ref{tab:results}) for code summarization.}

Step 3: Handle new content

For entirely new paragraphs, sentences, or sections added during revision, wrap the entire new block:

\rev{We additionally evaluate on the CodeXGLUE benchmark to address Reviewer 2's
concern about generalizability. Results in Table~\ref{tab:codexglue} show that
our method maintains its advantage across all four subtasks.}

Step 4: Handle deletions

When removing text, do not silently delete. If significant content is removed during reviewer-requested revision, mention it in the response letter or add a comment:

% Removed per R1's suggestion: [original text]

For self-revision deletions, simply remove the text — no markup needed since there is no reviewer to show the change to.

Stripping Markup After Acceptance

Once the paper is accepted and the camera-ready version is due, remove all colored markup by redefining both commands to pass through their argument:

\renewcommand{\rev}[1]{#1}
\renewcommand{\selfrev}[1]{#1}

This produces clean text with no color, no need to manually unwrap every instance. After verifying the output looks correct, the \renewcommand lines and all \rev{}/\selfrev{} wrappers can be fully cleaned up in the source if desired.

What This Skill Does NOT Do

• Does not write the initial draft (use research-paper-writing)
• Does not improve language quality independent of revision tracking (use paper-copy-editing)
• Does not compose rebuttal letters or response documents (use review2rebuttal)
• Does not handle LaTeX formatting issues (use latex-paper-formatting)