response-letter

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

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.