response-letter

name	response-letter
description	Helps organize reviewer comments and generate a standardized Word (.docx) response letter that maps each change to its exact location (page/paragraph/line). Use when revising a manuscript, replying to peer-review feedback, or preparing internal review responses.
license	MIT
author	AIPOCH

Source: https://github.com/aipoch/medical-research-skills

When to Use

• You received peer-review comments and need a point-by-point response letter for journal resubmission.
• You must clearly map every manuscript change to a specific location (page/paragraph/line) for reviewers or editors.
• You need a consistent, professional response structure across multiple reviewers and revision rounds.
• You are coordinating an internal review and want a standardized change log and execution checklist.
• You need a Word (.docx) deliverable rather than a table-based response format.

Key Features

• Consolidates, merges, and numbers reviewer comments across reviewers.
• Separates major vs. minor comments to prioritize revision work.
• Produces a fixed, repeatable response layout per comment:
  • Reviewer’s Comment
  • Response
  • Changes in Text
• Requires explicit change-location marking (page/paragraph/line) and version labeling.
• Supports quoting revised manuscript text (e.g., blockquotes) to make changes auditable.
• Generates a Word (.docx) response letter plus a modification/execution checklist.
• Adds an Overview for the Editor section summarizing major revisions at the beginning.
• Enforces a professional, polite tone throughout.

Dependencies

• Microsoft Word .docx output (Word-compatible document generation)
• Reference format guide: references/guide.md
• Response template: assets/review_response_template.docx

Example Usage

Input:
- Manuscript (tracked version or clean version + change notes)
- Reviewer comments (all reviewers, all rounds)
- Current manuscript pagination/line numbering scheme (if available)

Steps:
1) Organize comments
   - Merge all reviewer comments into a single list.
   - Number them sequentially (e.g., R1-1, R1-2…; R2-1…).
   - Tag each as Major or Minor.

2) Draft "Overview for the Editor"
   - Write one concise paragraph summarizing the major revisions and their rationale.

3) Write point-by-point responses
   For each numbered comment, output:
   - Reviewer’s Comment: (verbatim or lightly cleaned for clarity)
   - Response: (polite, direct, addresses the request)
   - Changes in Text: (what changed + where)

4) Mark locations and quote revised text
   - Provide page/paragraph/line for each change.
   - Specify additions/deletions.
   - Quote the revised paragraph when the main text is modified.

5) Generate deliverables
   - Export the full response letter as a Word document (.docx).
   - Produce a modification/execution checklist to verify all changes are applied.

Output (Word .docx structure):
- Title / Manuscript info (optional)
- Overview for the Editor
- Responses to Reviewer 1
  - R1-1
  - R1-2
  ...
- Responses to Reviewer 2
  ...
- Modification / Execution Checklist

Implementation Details

• Comment normalization and numbering
  • Merge comments from all sources; assign stable IDs (e.g., R{reviewer}-{index}) to preserve traceability across revision rounds.
• Major vs. minor classification
  • Major: requests affecting study design, analyses, interpretation, or core claims.
  • Minor: wording, formatting, clarifications, citations, typos.
• Per-comment fixed layout
  • Each response must include three labeled blocks: Reviewer’s Comment, Response, Changes in Text.
• Location marking
  • Use page/paragraph/line when available; otherwise use section/subsection headings plus paragraph index.
  • Always indicate whether text was added, deleted, or rewritten.
• Revised-text excerpting
  • When the manuscript body changes, include the updated paragraph as an indented blockquote under Changes in Text for auditability.
• Output constraints
  • Final deliverable is a Word document (.docx).
  • Do not use table format for the response letter.
• Formatting and checklists
  • Follow references/guide.md for required output formats, checklist items, and key writing points.

When Not to Use

• Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
• Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
• Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.

Required Inputs

Field	Required	Format/Source	Example	If Missing
User task description	Yes	Text	Research question, writing goal, analysis objective	Stop and ask user to provide
Primary input material	Depends on task	Text, file path, ID, table, or literature	PMID, PDF, CSV, DOCX, keywords, etc.	Specify which material type is missing
Output preference	No	Text	Language, format, target journal, template	Use skill default format

Output Contract

• Primary output: Structured result or target file aligned with this skill's objective.
• Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
• Format requirement: Unless the user specifies otherwise, prefer stable, reviewable Markdown or JSON; if the skill's bundled script requires a fixed format, use that format.
• If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.

Failure Handling

• Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
• Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
• Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.

User Checkpoints

Checkpoint 1: Before Drafting Overview

• After reading all reviewer comments, summarize the major revision themes and present them to the user.
• Ask: "Here are the main revision areas I identified. Do you want me to include all in the Editor Overview, or focus on specific points?"
• Wait for user confirmation before writing the Overview for the Editor.

Checkpoint 2: Before Generating DOCX

• After drafting all point-by-point responses, summarize the total number of responses, major vs minor split, and any potentially sensitive replies (e.g., politely disagreeing with a reviewer).
• Ask: "I have drafted N responses (X major, Y minor). Do you want me to proceed to generate the final DOCX, or would you like to review/edit any responses first?"
• Wait for user confirmation before generating the deliverable.

Checkpoint 3: Edge Case — Reviewer Comment is Incorrect or Based on a Misreading

• If a reviewer's comment appears to misunderstand the manuscript, do NOT skip it.
• Draft a polite response that:
  1. Thanks the reviewer for the comment
  2. Points to the relevant section (page/paragraph/line) where the information already exists
  3. Quotes the relevant passage as a blockquote
• Present this draft to the user for review before including in the final letter, as tone is critical here.

Checkpoint 4: Multiple Review Rounds

• If the user provides comments from multiple revision rounds (R1, R2, etc.), ask how they want to organize: separate sections per round, or a combined response.

Input Validation

This skill accepts requests that match the documented purpose of response-letter and include enough context to complete the workflow safely.

Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:

response-letter only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.

Quick Validation

• Check that key scripts, templates, or reference file paths this skill depends on exist.
• Check that the final output contains the core fields, sections, or files specified for this task.
• Check that results clearly mark assumptions, limitations, and incomplete items.