peer-review-response - SKILL.md Agent Skill

name: peer-review-response description: Systematic workflow for incorporating peer review feedback into policy documents, research reports, and academic manuscripts with tracked changes, explanatory comments, and structured response memos. Use when you have a document that has undergone peer review and need to systematically implement changes with proper documentation. Trigger when user asks to respond to peer reviews, action peer review comments, implement reviewer feedback, or create response memos for reviewers.

Peer Review Response Handler

Systematically respond to peer review feedback on policy/research documents by implementing changes with tracked changes, creating response memos, and providing clear guidance for manual completion.

Workflow

Phase 1: Intake and Understanding (5-10 min)

First Response:

Confirm you found the document and review memo(s)
Ask required questions:
- "What is the document's primary audience?" (policymakers/researchers/public)
- "Are there sections that must remain unchanged?" (e.g., boilerplate)
- "How much editorial discretion should I use?" (conservative/balanced/aggressive)
- "Are there project-specific standards to follow?" (check CLAUDE.md)

Then: 3. Read the document to understand structure and content 4. Read all review memos thoroughly 5. Summarize findings:

Number of reviewers and recommendations
Major themes in feedback
Any conflicts between reviewers

Phase 2: Categorization and Planning (10-15 min)

Create three lists and present to user for approval:

A. Implement Automatically (with tracked changes):

Factual corrections (errors, inconsistencies)
Terminology standardization
Clarification of ambiguous language
Editorial improvements (grammar, style)
Adding clearly missing information

For each: note location, quote reviewer, draft specific change

B. Implement Manually (too complex for automation):

Structural reorganization
Multi-location coordinated changes
Complex formatting requirements
Text spanning fragmented XML

For each: provide exact location, step-by-step instructions, comment text

C. Do Not Implement (explain in response memo):

Conflicts with project standards
Requires new analysis beyond scope
User wants section preserved
Contradicts other feedback
Infeasible constraints

For each: document reviewer's request, draft explanation

Present categorization to user:

Show all three lists
Highlight conflicts needing resolution
Ask for approval before proceeding

Phase 3: Implementation (20-30 min)

For Automated Changes:

Use a document editing library (e.g., python-docx or OOXML tools) to apply tracked changes:

# Example pattern for tracked changes with comments
# Adapt to your specific document library

# For each change:
# 1. Locate the text to change
# 2. Apply as tracked change (deletion + insertion)
# 3. Add comment citing reviewer and page number
# 4. Handle errors gracefully — if change fails, add to manual review list

Handle errors gracefully: if change fails, add to manual review list and continue.

For Manual Changes:

Create detailed guide with:

Location (section name, page number)
Exact text to find
New text to insert
Track change instructions (delete X, insert Y)
Comment text citing reviewer
Rationale for the change

See references/implementation-patterns.md for detailed examples and error handling

Phase 4: Response Memos (15-20 min)

For each reviewer, create structured response:

# RESPONSE MEMO

**TO:** [Reviewer Name]
**FROM:** [Document Authors]
**DATE:** [Current Date]
**RE:** Response to Review of [Document Title]

---

Thank you for your [adjective] review of our [document type].
Your expertise in [domain] has improved the document.
Below we address each of your recommendations.

---

## [Group recommendations by theme or section]

### [Recommendation Topic]

**Your Recommendation:** *[Quote or paraphrase]*

**Change Made:** [What was done with tracked changes]

**Rationale:** [Why this improves clarity/accuracy/etc.]

---

### [Another Recommendation]

**Your Suggestion:** *[Quote or paraphrase]*

**Decision:** We have **not implemented** this recommendation.

**Rationale:** [Clear explanation - standards, scope, etc.]

---

## Conclusion

Thank you again for your valuable feedback. We have implemented [X] of [Y]
recommendations. All changes are marked with tracked changes and include
comments citing your review memo. We welcome any follow-up discussion.

See references/response-memo-templates.md for additional formats

Phase 5: Quality Check and Delivery (5-10 min)

Verify deliverables:

Revised document:
- Opens without errors
- All tracked changes have comments
- Comments cite reviewer + page/section
- Formatting preserved
Response memos:
- One per reviewer
- Addresses every recommendation
- Clear rationale for decisions
Manual review guide:
- Clear locations
- Step-by-step instructions
- Comment text provided

Create summary:

# Peer Review Response Summary

## Successfully Implemented (X changes)
- [Change 1] - [Location] - [Reviewer]
...

## Requires Manual Completion (Y items)
- [Item 1] - [Location] - See Manual Review Guide
...

## Not Implemented (Z items)
- [Item 1] - [Rationale] - See Response Memo
...

## Next Steps
1. Review tracked changes in revised document
2. Complete manual items from guide
3. Review response memos before sending

Editorial Judgment Framework

Always Implement (No Discussion Needed)

Factual errors:

Mathematical errors
Data inconsistencies
Incorrect citations
Typos and spelling

Clarity improvements:

Ambiguous language with clear intent
Terminology consistency
Grammar/style fixes

Ask User First

Structural changes:

Reorganizing sections
Moving content between sections
Changing document flow

Scope changes:

Adding new analysis
Removing substantial content
Changing argument structure

Conflicts:

Reviewers disagree
Conflicts with stated standards
Unclear intent

Explain But Don't Implement

Beyond scope:

Requires new research/analysis
Would change document purpose
Outside review timeframe

Standards conflicts:

Contradicts project guidelines
User wants section preserved
Format/style requirements

Key Technical Notes

Text Spanning Multiple XML Runs:

Use broader search terms if exact text not found
Search by line number range
Flag for manual review with clear instructions

Document Corruption Prevention:

Use validate=False during development
Test packing after each batch
Work from clean copy if corruption occurs

RSID Management:

Use consistent RSID for all changes in a session
Properly link comments to tracked changes

Resources

references/implementation-patterns.md

Detailed examples of common implementation patterns, error handling strategies, and solutions to technical challenges like fragmented XML text.

references/response-memo-templates.md

Additional response memo formats for different scenarios (journal submissions, multi-reviewer conflicts, substantial scope disagreements).

references/editorial-guidelines.md

Comprehensive guidance on making editorial judgments, handling edge cases, and resolving reviewer conflicts.

Configuration Options

Users can specify preferences:

Editorial approach:

Conservative: Implement only factual corrections, ask about everything else
Balanced: Use judgment for clarity improvements, ask about structural changes
Aggressive: Implement all reasonable suggestions, explain declined items

Preserve sections:

Methodology: true/false
Boilerplate: true/false
References: true/false

Response memo format:

Markdown
Word
Structured replies (add responses below each reviewer point)

Comment style:

Detailed: Explain rationale + cite reviewer
Concise: Cite reviewer + brief reason

Success Metrics

Good implementation should achieve:

80%+ of straightforward changes automated
All recommendations addressed (implemented or explained)
Zero document corruption issues
Clear manual instructions requiring <15 min to complete
Response memos acceptable without revision
2-3 hour time savings vs. manual process