Source: https://github.com/aipoch/medical-research-skills
Response Tone Polisher
Polishes response letters to peer reviewers by softening harsh or defensive language while preserving the author's position and scientific integrity.
Quick Check
Use this command to verify that the packaged script entry point can be parsed before deeper execution.
python -m py_compile scripts/main.py
Audit-Ready Commands
Use these concrete commands for validation. They are intentionally self-contained and avoid placeholder paths.
python -m py_compile scripts/main.py
python scripts/main.py --help
Overview
This skill analyzes author draft responses to reviewer comments and transforms confrontational or defensive phrasing into professional, diplomatic academic language. It helps researchers maintain positive relationships with reviewers while standing firm on scientifically justified positions.
Key Features
- Tone Analysis: Identifies defensive, confrontational, or overly direct language
- Polite Transformation: Converts harsh statements into courteous academic prose
- Position Preservation: Maintains the author's scientific stance while improving delivery
- Context Awareness: Adapts based on response type (acceptance, partial acceptance, respectful decline)
- Academic Expression Library: Built-in collection of polished academic phrasings
When to Use
- Use this skill when the task needs Polishes response letters by transforming defensive or harsh language.
- Use this skill for academic writing tasks that require explicit assumptions, bounded scope, and a reproducible output format.
- Use this skill when you need a documented fallback path for missing inputs, execution errors, or partial evidence.
Usage Examples
Basic Usage
Input:
Reviewer: The sample size is too small for meaningful conclusions.
Draft Response: I disagree. Our sample size is standard in this field.
Output:
We appreciate the reviewer's concern regarding sample size. While we acknowledge
that larger samples provide greater statistical power, our sample size is consistent
with established conventions in this field and meets the requirements for adequate
power analysis (as detailed in the Methods section).
Defensive Language Transformation
| Original (Defensive) |
Polished (Professional) |
| "I will not change this." |
"We have carefully considered this suggestion and respectfully maintain our original approach because..." |
| "The reviewer is wrong." |
"We respectfully offer a different interpretation..." |
| "This is unnecessary." |
"We appreciate this suggestion; however, we believe the current presentation adequately addresses this point." |
| "We already explained this." |
"We have expanded our explanation to enhance clarity (Page X, Lines Y-Z)." |
| "That's not our fault." |
"We acknowledge this limitation and have added appropriate caveats to the Discussion." |
Input Parameters
| Parameter |
Type |
Required |
Description |
reviewer_comment |
str |
Yes |
The reviewer's original comment or criticism |
draft_response |
str |
Yes |
Author's initial draft response (may contain harsh/defensive language) |
response_type |
str |
No |
One of: accept, partial, decline (default: auto-detect) |
polish_level |
str |
No |
light, moderate, heavy (default: moderate) |
preserve_meaning |
bool |
No |
Ensure scientific position is preserved (default: true) |
Output Format
{
"polished_response": "string",
"original_tone_score": "float (0-1, higher = more defensive)",
"improvements": [
{
"original_phrase": "string",
"polished_phrase": "string",
"issue_type": "string"
}
],
"suggestions": ["string"],
"politeness_score": "float (0-1)"
}
Tone Patterns Detected
The skill identifies and transforms:
1. Direct Refusals
- "No" / "We won't" → "We respectfully decline to..."
- "We can't" → "We are unable to..."
2. Defensive Statements
- "But we already..." → "We have now clarified..."
- "This is not correct" → "We respectfully note that..."
3. Blame Shifting
- "The reviewer misunderstood" → "We apologize for the lack of clarity; we have revised..."
- "This is standard" → "This approach aligns with established conventions..."
4. Emotional Language
- "Unfortunately" (overused) → [removed or softened]
- "Obviously" → [removed]
- "Clearly" → [removed or context-dependent]
Polite Academic Expressions
Acknowledging Reviewers
- "We thank the reviewer for this insightful observation."
- "We appreciate the reviewer's careful attention to this detail."
- "We are grateful for this constructive feedback."
- "This is an excellent point."
Expressing Disagreement Diplomatically
- "We respectfully offer an alternative interpretation..."
- "Upon careful reconsideration, we believe..."
- "While we appreciate this perspective, we note that..."
- "We respectfully maintain our position that..."
Explaining Limitations
- "We acknowledge this limitation and have addressed it by..."
- "This constraint reflects the trade-off between..."
- "We have added appropriate caveats regarding this limitation."
Describing Changes
- "We have revised the manuscript to clarify..."
- "We have expanded the relevant section to include..."
- "We have incorporated this suggestion by..."
Workflow
- Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.
- Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.
- Use the packaged script path or the documented reasoning path with only the inputs that are actually available.
- Return a structured result that separates assumptions, deliverables, risks, and unresolved items.
- If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
Command Line Usage
# Interactive mode
python scripts/main.py --interactive
# File-based
python scripts/main.py \
--reviewer-comment "comment.txt" \
--draft-response "draft.txt" \
--output "polished.txt"
# Direct input
python scripts/main.py \
--reviewer "The data is insufficient." \
--draft "You are wrong. We have enough data." \
--polish-level heavy
Python API
from scripts.main import TonePolisher
polisher = TonePolisher()
result = polisher.polish(
reviewer_comment="The methodology is flawed.",
draft_response="No it's not. We did it right.",
response_type="decline",
polish_level="moderate"
)
print(result["polished_response"])
References
references/polite_expressions.json - Curated library of academic polite expressions
references/tone_patterns.md - Common defensive patterns and their transformations
references/examples/ - Before/after polishing examples
Limitations
- Does not verify scientific accuracy of responses
- Requires human review for complex nuanced disagreements
- May over-soften; authors should verify position is still clear
- Best for English-language responses
Quality Checklist
After polishing, verify:
Risk Assessment
| Risk Indicator |
Assessment |
Level |
| Code Execution |
Python/R scripts executed locally |
Medium |
| Network Access |
No external API calls |
Low |
| File System Access |
Read input files, write output files |
Medium |
| Instruction Tampering |
Standard prompt guidelines |
Low |
| Data Exposure |
Output files saved to workspace |
Low |
Security Checklist
Prerequisites
# Python dependencies
pip install -r requirements.txt
Evaluation Criteria
Success Metrics
Test Cases
- Basic Functionality: Standard input → Expected output
- Edge Case: Invalid input → Graceful error handling
- Performance: Large dataset → Acceptable processing time
Lifecycle Status
- Current Stage: Draft
- Next Review Date: 2026-03-06
- Known Issues: None
- Planned Improvements:
- Performance optimization
- Additional feature support
Output Requirements
Every final response should make these items explicit when they are relevant:
- Objective or requested deliverable
- Inputs used and assumptions introduced
- Workflow or decision path
- Core result, recommendation, or artifact
- Constraints, risks, caveats, or validation needs
- Unresolved items and next-step checks
Error Handling
- If required inputs are missing, state exactly which fields are missing and request only the minimum additional information.
- If the task goes outside the documented scope, stop instead of guessing or silently widening the assignment.
- If
scripts/main.py fails, report the failure point, summarize what still can be completed safely, and provide a manual fallback.
- Do not fabricate files, citations, data, search results, or execution outcomes.
Input Validation
This skill accepts requests that match the documented purpose of response-tone-polisher 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-tone-polisher only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.
Response Template
Use the following fixed structure for non-trivial requests:
- Objective
- Inputs Received
- Assumptions
- Workflow
- Deliverable
- Risks and Limits
- Next Checks
If the request is simple, you may compress the structure, but still keep assumptions and limits explicit when they affect correctness.
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
- Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
- Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.
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.
1---
2name: response-tone-polisher
3description: Polish reviewer-response letters by softening defensive language, preserving factual meaning, and keeping responses professional, concise, and publication-appropriate.
4license: MIT
5author: AIPOCH
6metadata:
7 source: https://skillmd.com/skills/aipoch/response-tone-polisher
8---
9
10> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
11
12# Response Tone Polisher
13
14Polishes response letters to peer reviewers by softening harsh or defensive language while preserving the author's position and scientific integrity.
15
16## Quick Check
17
18Use this command to verify that the packaged script entry point can be parsed before deeper execution.
19
20```bash
21python -m py_compile scripts/main.py
22```
23
24## Audit-Ready Commands
25
26Use these concrete commands for validation. They are intentionally self-contained and avoid placeholder paths.
27
28```bash
29python -m py_compile scripts/main.py
30python scripts/main.py --help
31```
32
33## Overview
34
35This skill analyzes author draft responses to reviewer comments and transforms confrontational or defensive phrasing into professional, diplomatic academic language. It helps researchers maintain positive relationships with reviewers while standing firm on scientifically justified positions.
36
37## Key Features
38
39- **Tone Analysis**: Identifies defensive, confrontational, or overly direct language
40- **Polite Transformation**: Converts harsh statements into courteous academic prose
41- **Position Preservation**: Maintains the author's scientific stance while improving delivery
42- **Context Awareness**: Adapts based on response type (acceptance, partial acceptance, respectful decline)
43- **Academic Expression Library**: Built-in collection of polished academic phrasings
44
45## When to Use
46
47- Use this skill when the task needs Polishes response letters by transforming defensive or harsh language.
48- Use this skill for academic writing tasks that require explicit assumptions, bounded scope, and a reproducible output format.
49- Use this skill when you need a documented fallback path for missing inputs, execution errors, or partial evidence.
50
51## Usage Examples
52
53### Basic Usage
54
55```
56Input:
57Reviewer: The sample size is too small for meaningful conclusions.
58Draft Response: I disagree. Our sample size is standard in this field.
59
60Output:
61We appreciate the reviewer's concern regarding sample size. While we acknowledge
62that larger samples provide greater statistical power, our sample size is consistent
63with established conventions in this field and meets the requirements for adequate
64power analysis (as detailed in the Methods section).
65```
66
67### Defensive Language Transformation
68
69| Original (Defensive) | Polished (Professional) |
70|---------------------|------------------------|
71| "I will not change this." | "We have carefully considered this suggestion and respectfully maintain our original approach because..." |
72| "The reviewer is wrong." | "We respectfully offer a different interpretation..." |
73| "This is unnecessary." | "We appreciate this suggestion; however, we believe the current presentation adequately addresses this point." |
74| "We already explained this." | "We have expanded our explanation to enhance clarity (Page X, Lines Y-Z)." |
75| "That's not our fault." | "We acknowledge this limitation and have added appropriate caveats to the Discussion." |
76
77## Input Parameters
78
79| Parameter | Type | Required | Description |
80|-----------|------|----------|-------------|
81| `reviewer_comment` | str | Yes | The reviewer's original comment or criticism |
82| `draft_response` | str | Yes | Author's initial draft response (may contain harsh/defensive language) |
83| `response_type` | str | No | One of: `accept`, `partial`, `decline` (default: auto-detect) |
84| `polish_level` | str | No | `light`, `moderate`, `heavy` (default: moderate) |
85| `preserve_meaning` | bool | No | Ensure scientific position is preserved (default: true) |
86
87## Output Format
88
89```json
90{
91 "polished_response": "string",
92 "original_tone_score": "float (0-1, higher = more defensive)",
93 "improvements": [
94 {
95 "original_phrase": "string",
96 "polished_phrase": "string",
97 "issue_type": "string"
98 }
99 ],
100 "suggestions": ["string"],
101 "politeness_score": "float (0-1)"
102}
103```
104
105## Tone Patterns Detected
106
107The skill identifies and transforms:
108
109### 1. Direct Refusals
110- "No" / "We won't" → "We respectfully decline to..."
111- "We can't" → "We are unable to..."
112
113### 2. Defensive Statements
114- "But we already..." → "We have now clarified..."
115- "This is not correct" → "We respectfully note that..."
116
117### 3. Blame Shifting
118- "The reviewer misunderstood" → "We apologize for the lack of clarity; we have revised..."
119- "This is standard" → "This approach aligns with established conventions..."
120
121### 4. Emotional Language
122- "Unfortunately" (overused) → [removed or softened]
123- "Obviously" → [removed]
124- "Clearly" → [removed or context-dependent]
125
126## Polite Academic Expressions
127
128### Acknowledging Reviewers
129- "We thank the reviewer for this insightful observation."
130- "We appreciate the reviewer's careful attention to this detail."
131- "We are grateful for this constructive feedback."
132- "This is an excellent point."
133
134### Expressing Disagreement Diplomatically
135- "We respectfully offer an alternative interpretation..."
136- "Upon careful reconsideration, we believe..."
137- "While we appreciate this perspective, we note that..."
138- "We respectfully maintain our position that..."
139
140### Explaining Limitations
141- "We acknowledge this limitation and have addressed it by..."
142- "This constraint reflects the trade-off between..."
143- "We have added appropriate caveats regarding this limitation."
144
145### Describing Changes
146- "We have revised the manuscript to clarify..."
147- "We have expanded the relevant section to include..."
148- "We have incorporated this suggestion by..."
149
150## Workflow
151
1521. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.
1532. Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.
1543. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.
1554. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.
1565. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.
157
158## Command Line Usage
159
160```text
161# Interactive mode
162python scripts/main.py --interactive
163
164# File-based
165python scripts/main.py \
166 --reviewer-comment "comment.txt" \
167 --draft-response "draft.txt" \
168 --output "polished.txt"
169
170# Direct input
171python scripts/main.py \
172 --reviewer "The data is insufficient." \
173 --draft "You are wrong. We have enough data." \
174 --polish-level heavy
175```
176
177## Python API
178
179```python
180from scripts.main import TonePolisher
181
182polisher = TonePolisher()
183result = polisher.polish(
184 reviewer_comment="The methodology is flawed.",
185 draft_response="No it's not. We did it right.",
186 response_type="decline",
187 polish_level="moderate"
188)
189
190print(result["polished_response"])
191```
192
193## References
194
195- `references/polite_expressions.json` - Curated library of academic polite expressions
196- `references/tone_patterns.md` - Common defensive patterns and their transformations
197- `references/examples/` - Before/after polishing examples
198
199## Limitations
200
201- Does not verify scientific accuracy of responses
202- Requires human review for complex nuanced disagreements
203- May over-soften; authors should verify position is still clear
204- Best for English-language responses
205
206## Quality Checklist
207
208After polishing, verify:
209- [ ] Original scientific position is preserved
210- [ ] No confrontational language remains
211- [ ] Professional tone throughout
212- [ ] Clear acknowledgment of reviewer's effort
213- [ ] Specific changes are still referenced
214- [ ] Response directly addresses the comment
215
216## Risk Assessment
217
218| Risk Indicator | Assessment | Level |
219|----------------|------------|-------|
220| Code Execution | Python/R scripts executed locally | Medium |
221| Network Access | No external API calls | Low |
222| File System Access | Read input files, write output files | Medium |
223| Instruction Tampering | Standard prompt guidelines | Low |
224| Data Exposure | Output files saved to workspace | Low |
225
226## Security Checklist
227
228- [ ] No hardcoded credentials or API keys
229- [ ] No unauthorized file system access (../)
230- [ ] Output does not expose sensitive information
231- [ ] Prompt injection protections in place
232- [ ] Input file paths validated (no ../ traversal)
233- [ ] Output directory restricted to workspace
234- [ ] Script execution in sandboxed environment
235- [ ] Error messages sanitized (no stack traces exposed)
236- [ ] Dependencies audited
237
238## Prerequisites
239
240```text
241# Python dependencies
242pip install -r requirements.txt
243```
244
245## Evaluation Criteria
246
247### Success Metrics
248- [ ] Successfully executes main functionality
249- [ ] Output meets quality standards
250- [ ] Handles edge cases gracefully
251- [ ] Performance is acceptable
252
253### Test Cases
2541. **Basic Functionality**: Standard input → Expected output
2552. **Edge Case**: Invalid input → Graceful error handling
2563. **Performance**: Large dataset → Acceptable processing time
257
258## Lifecycle Status
259
260- **Current Stage**: Draft
261- **Next Review Date**: 2026-03-06
262- **Known Issues**: None
263- **Planned Improvements**:
264 - Performance optimization
265 - Additional feature support
266
267## Output Requirements
268
269Every final response should make these items explicit when they are relevant:
270
271- Objective or requested deliverable
272- Inputs used and assumptions introduced
273- Workflow or decision path
274- Core result, recommendation, or artifact
275- Constraints, risks, caveats, or validation needs
276- Unresolved items and next-step checks
277
278## Error Handling
279
280- If required inputs are missing, state exactly which fields are missing and request only the minimum additional information.
281- If the task goes outside the documented scope, stop instead of guessing or silently widening the assignment.
282- If `scripts/main.py` fails, report the failure point, summarize what still can be completed safely, and provide a manual fallback.
283- Do not fabricate files, citations, data, search results, or execution outcomes.
284
285## Input Validation
286
287This skill accepts requests that match the documented purpose of `response-tone-polisher` and include enough context to complete the workflow safely.
288
289Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:
290
291> `response-tone-polisher` only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.
292
293## Response Template
294
295Use the following fixed structure for non-trivial requests:
296
2971. Objective
2982. Inputs Received
2993. Assumptions
3004. Workflow
3015. Deliverable
3026. Risks and Limits
3037. Next Checks
304
305If the request is simple, you may compress the structure, but still keep assumptions and limits explicit when they affect correctness.
306
307## When Not to Use
308
309- Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
310- Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
311- Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.
312
313## Required Inputs
314
315| Field | Required | Format/Source | Example | If Missing |
316|---|---|---|---|---|
317| User task description | Yes | Text | Research question, writing goal, analysis objective | Stop and ask user to provide |
318| 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 |
319| Output preference | No | Text | Language, format, target journal, template | Use skill default format |
320
321## Output Contract
322
323- Primary output: Structured result or target file aligned with this skill's objective.
324- Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
325- 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.
326- If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.
327
328## Failure Handling
329
330- Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
331- Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
332- Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.
333
334## User Checkpoints
335
336- Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
337- Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.
338
339## Quick Validation
340
341- Check that key scripts, templates, or reference file paths this skill depends on exist.
342- Check that the final output contains the core fields, sections, or files specified for this task.
343- Check that results clearly mark assumptions, limitations, and incomplete items.