| name | revision-workflow |
| description | Respond to peer review comments and manage manuscript revisions. Use when drafting response letters, tracking changes across versions, or addressing reviewer concerns. Works well with scientific-style and human-writing skills. |
| argument-hint | ["reviewer comment or revision task"] |
Revision Workflow Guide
This guide covers responding to peer review and managing the revision process.
When to Use This Skill
- Drafting response letters to reviewers
- Organizing and tracking manuscript changes
- Addressing specific reviewer concerns
- Planning revision strategy
Combine with: scientific-style for appropriate hedging, human-writing for clear prose.
Response Letter Structure
Header
Response to Reviewers
Manuscript ID: [ID]
Title: [Title]
Authors: [Authors]
We thank the editor and reviewers for their constructive feedback.
We have carefully considered each comment and revised the manuscript
accordingly. Our point-by-point responses are below.
Page and line numbers refer to the revised manuscript with track changes.
For Each Reviewer
REVIEWER 1
Comment 1.1: [Quote or paraphrase the comment]
Response: [Your response]
Changes made: [Specific changes with page/line numbers, or "No changes made"]
---
Comment 1.2: [Next comment]
...
Closing
We believe these revisions have substantially improved the manuscript
and hope it is now suitable for publication in [Journal].
Sincerely,
[Corresponding author]
Response Strategies by Comment Type
| Comment Type | Strategy |
|---|
| Minor correction | Thank, agree, fix, cite location |
| Clarification request | Thank, explain, add text if needed |
| Additional analysis | Agree if feasible, explain if not, provide results |
| Methodological concern | Address directly, explain rationale, add detail |
| Interpretation disagreement | Acknowledge perspective, explain reasoning, modify if warranted |
| Literature gap | Thank, add citations, discuss relevance |
| Impossible request | Explain why, offer alternative |
Tone Guidelines
Do:
- Thank reviewers for specific suggestions
- Acknowledge valid concerns directly
- Explain your reasoning clearly
- Be professional and respectful
- Separate agreement from action (you can agree something is unclear without agreeing with the proposed fix)
Don't:
- Be defensive or argumentative
- Dismiss concerns without explanation
- Over-apologize or be obsequious
- Make promises you can't keep
- Ignore any comment (respond to everything)
Language Calibration
| Instead of | Use |
|---|
| "The reviewer is wrong" | "We respectfully disagree because..." |
| "We already said this" | "We have clarified this point by..." |
| "This is beyond scope" | "While this is an important question, it is beyond the scope of the current study because..." |
| "We can't do this" | "Unfortunately, [reason]. As an alternative, we have..." |
Handling Specific Situations
When You Agree
We thank the reviewer for this suggestion. We have [made change] as
recommended. See page X, lines Y-Z.
When You Partially Agree
We appreciate this comment. While we agree that [aspect], we believe
[other aspect] because [reasoning]. We have addressed this by [action].
When You Disagree
We thank the reviewer for raising this point. We respectfully disagree
because [clear reasoning with evidence]. However, we have [action to
address underlying concern] to clarify our position.
When You Cannot Comply
We appreciate this suggestion. Unfortunately, [specific reason why not
feasible: data not available, beyond scope, etc.]. As an alternative,
we have [what you did instead]. We have also added this as a limitation
in the Discussion (page X, lines Y-Z).
Version Management
See CHANGE_TRACKING.md for detailed guidance on:
- File naming conventions
- Track changes best practices
- Creating clean vs. marked copies
Common Reviewer Concerns
See COMMON_REVIEWER_CONCERNS.md for pre-written strategies for:
- Sample size concerns
- Statistical issues
- Generalizability
- Missing controls
- Literature gaps
Response Letter Templates
See RESPONSE_TEMPLATES.md for fill-in templates.
Revision Process Checklist
Before Starting
During Revision
Before Submitting
Related Files
