1
Think first
Use a reasoning model to diagnose the reviewer concern and write a plan.
Plan-Gated Paper Revision Skill
A cleaned and lightly dramatized origin chat that explains how to make AI-assisted manuscript revision controlled, traceable, and less chaotic.
The idea in one sentence
Do not let an AI agent think, edit, verify, and explain all at once. First force the reasoning into a Markdown plan, then let the editing agent execute only that approved plan.
2
Gate edits
No plan, no manuscript changes. The plan is the edit boundary.
3
Verify truth
Compile, inspect the PDF, then update the response letter with verified locations.
4
Commit history
Each accepted work package becomes a clean Git step that can be reviewed or rolled back.
Cleaned origin chat
This is a readable, translated, and lightly elaborated version of the original chat between Chen Miao and Feifei Robbie. Unrelated historical banter was removed. The funny analogy was kept because it captures the architecture: strategist, executor, and human commander.
Chen Miao
I used to have a workflow for revising papers with AI. The key is to keep the process linear, otherwise the whole revision becomes messy.
First, keep the submitted version as original_main.tex. The working file is still called main.tex. Then let the agent generate redlined_main.tex. Even if the redline is not submitted, it is extremely useful for checking what changed.
C
R
Feifei Robbie
So the baseline is frozen, the current manuscript keeps the same filename, and the redline is generated automatically?
Chen Miao
Exactly. Then ask AI to draft the response letter first. Go reviewer comment by reviewer comment. First understand the response logic, then ask AI to make a manuscript revision plan, save it as Markdown, check it, and only then execute it.
Loop through all comments this way. Also write a build script that automatically compiles the latest manuscript, latest response letter, and redline version.
C
Design note: the response letter is not an afterthought. It is the logical map of the revision. If the response cannot be defended, the manuscript edit is probably not ready.
Chen Miao
Before every meaningful edit, create a Markdown plan. Put it under references/. Later, when you wonder why something was changed, the reason is there. The agent can also read those files and understand the history.
Without a plan, you only have the result, not the thinking process.
C
R
Feifei Robbie
Do you mean one Markdown file per reviewer issue, or one file that keeps appending the whole process?
Chen Miao
Usually many files. Each file corresponds to the current revision package. For example: reviewer1_comment1_revision1.md, figure4_caption_shorten_plan.md, or main_text_shorten_plan.md.
The size is dynamic. A plan can cover one small paragraph, one figure caption, one reviewer comment, or a global shortening pass. But plan and execution should correspond one-to-one.
C
R
Feifei Robbie
So the “round” you mean is not every tiny Codex message. It is the moment when we actually let Codex execute a work package?
Chen Miao
Yes. It is the exact package you hand to Codex and say: apply this.
If the plan feels easy for the agent, let it execute. If it looks too difficult, split the plan into smaller plans. You can often tell from the plan quality whether the agent is struggling.
C
Practical rule: if the plan sounds vague, the edit will probably become vague. Split before execution, not after the manuscript is damaged.
R
Feifei Robbie
Does the plan come from you, from ChatGPT, or from Codex itself?
Chen Miao
Any of them can produce it, but the final plan must be something I approve. Codex is good at editing files, fixing LaTeX, and compiling. But it is weaker at deciding why and how to revise the science and wording.
So I often ask ChatGPT for the revision strategy, save that as Markdown, and then let Codex apply it.
Knowledge: ChatGPT. Technical execution: Codex.
C
R
Feifei Robbie
What if the plan is executed but the result is not ideal and needs small tuning? Do you create a new Markdown file for every tiny adjustment?
Chen Miao
Not necessary. The important thing is not to record every tiny chat message. The important thing is that the final executed plan is a good plan.
If the plan is not good, revise it, overwrite it, or ask another model to improve it. But the agent should be constrained by the final plan. The core is controlling the edit scope.
C
Chen Miao
I discovered that when the agent is not strong at a task, it starts to edit randomly. The more it edits, the more chaotic it becomes. But once I use a plan before editing, the process becomes controllable.
It reduces the burden. The agent does not need to think about what to change and how to edit the files at the same time.
C
R
Feifei Robbie
So you are like Zhuge Liang setting up the strategy, and Codex is Zhao Yun going to the battlefield?
Chen Miao
Exactly. Divide and conquer. Let the strategist focus on strategy and the executor focus on execution.
C
Final translation: the human is still the commander. The agent can plan, edit, audit, and compile, but it should not silently decide the scientific direction.
The workflow as an operating system
The method works because it converts a messy revision into a sequence of small, verifiable transactions.
0
Freeze the baseline
Keep original_main.tex unchanged. Work on main.tex. Generate redline automatically.
1
Draft the response logic
Understand the reviewer’s real concern before touching the manuscript.
2
Create a plan under references/
The plan defines allowed files, allowed locations, forbidden changes, rationale, and verification.
3
Human approves or splits
If the plan is too broad, split it. If it is clear, execute it.
4
Executor applies only the plan
Codex edits the allowed files and records execution notes.
5
Build and inspect PDF
Compile manuscript and response letter. Check the actual PDF before claiming page or line locations.
6
Synchronize response letter
The response letter must reflect real manuscript changes, not planned or imagined changes.
7
Commit and push
Every accepted work package becomes a clean Git checkpoint.
reviewer comment
→ response logic
→ references/reviewer1_comment1_revision1.md
→ human approval
→ edit main.tex only within the plan
→ compile main.pdf + response_letter.pdf
→ verify PDF locations
→ update response letter
→ generate redline
→ git commit + pushAgent roles
A single agent can perform all roles, but the workflow is clearer when the roles are separated.
Strategist Agent
Diagnoses reviewer concerns, writes the plan, controls tone, and decides whether to split the task. It should not directly edit the manuscript.
Executor Agent
Reads the approved plan, edits files, compiles LaTeX, generates redline, and records what was done. It should not freely reinterpret the science.
Auditor Agent
Checks the PDF, verifies page/line references, checks response-letter truthfulness, and ensures the edit did not exceed the plan.
Human Commander
Approves the plan, decides task granularity, judges scientific direction, and accepts or rejects the final revision.
Cognitive load split
A rough conceptual chart: the workflow moves the hard reasoning out of the file-editing moment.
Tables for quick understanding
Problem → Skill mechanism
| Common failure | Plan-gated solution | Practical rule |
|---|---|---|
| Agent changes too much | The plan defines exact allowed files and locations. | If it is not in the plan, do not edit it. |
| Response letter overclaims | Location claims are added only after PDF inspection. | Never write “we revised” before the manuscript is actually revised. |
| Revision history becomes unclear | Each work package has a plan and Git commit. | One plan, one execution, one commit. |
| Large tasks overload the agent | Broad plans are split before execution. | Vague plan → split plan. |
| New sessions lose context | The references/ directory acts as external memory. | Let the agent read relevant plans before editing. |
Plan file checklist
| Plan section | What it should answer |
|---|---|
| Source comment | Which reviewer/editor comment or internal goal triggered this? |
| Diagnosis | What is the real concern behind the comment? |
| Scope | Which files and locations may be changed? |
| Forbidden changes | What should the agent explicitly avoid? |
| Proposed edits | What exact changes should be made? |
| Acceptance criteria | How do we know the edit is complete? |
| Verification | How will the manuscript, response letter, references, and redline be checked? |
Two revision modes compared
Standard Codex instruction
This prompt turns the chat philosophy into an executable agent 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 redlined_main.tex when original_main.tex is available.
Show git diff summary.
Commit and push this work package.Do not say
“Revise the paper according to the reviewer comments.”
This is too broad and invites uncontrolled editing.
Say instead
“Read references/reviewer2_comment6_reanalysis_plan.md. Apply only the approved edits. Stop if anything is out of scope.”
This gives the agent a boundary and a verification path.
How to use this page in a GitHub repository
This HTML page can serve two roles: the origin story of the skill and the visual tutorial for new users.
paper-revision-agent-skill/
README.md
SKILL.md
docs/
origin-chat.html
templates/
revision_plan.md
response_trace_audit.md
revision_task_index.md
prompts/
plan_prompt.md
apply_prompt.md
audit_prompt.mdSuggested README link
## Origin and tutorial
The workflow was derived from a real paper-revision discussion.
For a readable visual explanation, see:
- [Origin chat and guide](docs/origin-chat.html)Publishing note
This page is intentionally written as a cleaned and translated origin narrative, not a raw private transcript. It keeps the technical method, the useful humor, and the design lessons, while removing unrelated discussion.