# Revision Workflow > 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. Use when this capability is needed. - Skill: `tomevault-io/revision-workflow` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/revision-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/revision-workflow/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/revision-workflow --- # 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](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](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](RESPONSE_TEMPLATES.md) for fill-in templates. ## Revision Process Checklist ### Before Starting - [ ] Read all reviews completely before responding - [ ] Identify patterns across reviewers - [ ] Prioritize major vs. minor concerns - [ ] Assess feasibility of each request - [ ] Plan revision strategy ### During Revision - [ ] Address one comment at a time - [ ] Make changes in manuscript immediately - [ ] Record page/line numbers as you go - [ ] Keep track changes on - [ ] Note any substantive additions for cover letter ### Before Submitting - [ ] Every comment has a response - [ ] Every "Changes made" entry has location - [ ] Response letter matches manuscript changes - [ ] Clean copy and marked copy are consistent - [ ] Cover letter summarizes major changes - [ ] All file naming follows journal guidelines ## Related Files - [RESPONSE_TEMPLATES.md](RESPONSE_TEMPLATES.md) - Templates for common response types - [CHANGE_TRACKING.md](CHANGE_TRACKING.md) - Version control and tracking - [COMMON_REVIEWER_CONCERNS.md](COMMON_REVIEWER_CONCERNS.md) - Pre-written strategies --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/shandley) — claim your Tome and manage your conversions.