Imported from jiangyouxiang/ssci-editor (ssci-editor/SKILL.md). Install upstream with npx skills add jiangyouxiang/ssci-editor --skill ssci-editor. Copyright stays with the author.

SSCI Editor

Overview

SSCI Editor edits English academic manuscripts in the social sciences with controlled scope. It can work in two modes: Minimal Mode for conservative grammar/mechanics correction, and Polishing Mode for clearer academic expression. In both modes, preserve the author's meaning, claims, statistical results, terminology, field structures, and document integrity.

For .docx files, use the bundled scripts in scripts/docx_revision_tool.py for text extraction, candidate-ledger application, tracked-change insertion, and structural verification. Do not delegate the core revision task to a separate document workflow unless the bundled scripts fail or the user explicitly asks for a different workflow.

Scope

Use this skill for:

• SSCI and social-science manuscripts, supplements, appendices, response letters, cover letters, and reviewer-requested grammar correction
• psychology, education, psychometrics, measurement, sociology, communication, management, organizational behavior, public health, political science, and related empirical or methods papers
• DOCX language editing with tracked changes
• minimal correction where the author wants meaning preserved
• polishing where the author explicitly wants more fluent academic English

Do not use this skill for:

• developmental editing, theory rebuilding, argument redesign, or journal-style rewriting unless the user explicitly asks
• plagiarism rewriting, claim strengthening, or changing results
• citation discovery, reference verification, or literature review unless paired with a separate citation/search workflow

Mode Selection

Choose the mode before editing.

• Select Minimal Mode automatically if the user says minimal, grammar only, minimum changes, minimal corrections, no sentence rewriting, tracked changes only, or if the reviewer only requested grammar correction.
• Select Polishing Mode automatically if the user says polish, polishing, 润色, improve academic English, make it more fluent, or 提升表达.
• If the request is ambiguous, such as "edit this manuscript" or "revise the language," ask the user to choose Minimal Mode or Polishing Mode before editing.

Both modes must follow the DOCX safety rules, candidate ledger, protected-content rules, tracked-vs-clean output distinction, and field/formula safeguards.

Minimal Mode

Use this mode for conservative correction. Make only local grammar, punctuation, tense, article, preposition, agreement, spelling, typography, word-form, typo, and sentence-mechanics corrections. Do not rewrite a sentence unless it remains ungrammatical or unintelligible after smaller local edits.

Minimal Mode decision ladder:

1. Leave unchanged if the sentence is grammatical and the issue is only style, elegance, variety, concision, or personal preference.
2. Make a local correction if a word-level or phrase-level edit fixes a clear language or mechanics error.
3. Add a comment or ledger note if the sentence is ambiguous, technically uncertain, or may require author judgment.
4. Rewrite minimally only if the sentence remains ungrammatical or unintelligible after local edits.

Polishing Mode

Use this mode only when selected explicitly. Polishing Mode may improve fluency, reduce obvious repetition, clarify awkward local phrasing, and make academic English smoother. It may use limited sentence-level restructuring, but only when the original meaning, claim strength, technical terminology, statistical interpretation, and emphasis remain unchanged.

Polishing Mode decision ladder:

1. Leave unchanged if the sentence is already clear, idiomatic enough, and technically precise.
2. Make a local correction for grammar or mechanics errors.
3. Make a low-risk polishing edit if it improves clarity or flow without changing meaning, scope, evidence strength, causal language, or terminology.
4. Add a comment or ledger note if the improvement would require interpretation, substantive judgment, or author preference.
5. Use sentence-level restructuring only when the sentence is clearly awkward or hard to follow and the revision stays close to the original logic.

Polishing Mode is not permission to strengthen conclusions, simplify technical constructs, change methods/results language, reorganize paragraphs, or make the paper sound like a different author.

Full-Document Review Workflow

Use this workflow before editing a DOCX manuscript:

1. Extract text with the embedded DOCX tool:

   python scripts/docx_revision_tool.py extract --docx "input.docx" --output "extracted-text.json"

2. Candidate discovery pass: read the extracted visible text and build a candidate ledger across the full document. Do not patch while discovering candidates.

3. Decision pass: evaluate each candidate with the selected mode's decision ladder and the Candidate Quality Gate. Drop candidates that are technically uncertain, generated by field/formula artifacts, likely to alter meaning, or outside the selected mode.

4. Tracked-change patch pass: apply only accepted candidates as true DOCX tracked changes:

   python scripts/docx_revision_tool.py apply-ledger --docx "input.docx" --ledger "ledger.json" --output "tracked.docx"

5. Verification pass: structurally verify the DOCX, confirm tracked changes are present, preserve package parts and relationships, and report revision counts:

   python scripts/docx_revision_tool.py verify --docx "tracked.docx" --baseline "input.docx" --output "verification.json"

If rendering through Word/LibreOffice is available, render and visually inspect the output. Treat tracked-change rendering as a review check, not as a clean submission-layout check: visible insertions/deletions can disrupt line breaks, titles, tables, and equations. Generate or inspect a clean accepted-changes version only when the user explicitly asks for it or when visual layout, not revision visibility, is the target.

The candidate ledger should include:

• part: DOCX part, usually word/document.xml
• paragraph_index: zero-based paragraph index from the extraction JSON
• original: exact original phrase
• replacement: exact replacement phrase
• mode: minimal or polishing
• category: article, agreement, tense, preposition, word form, punctuation, typo, duplicated word, sentence boundary, fluency, clarity, ambiguity, or other
• decision: apply, skip, or comment
• reason: short rationale
• optional risk: low, medium, or high

Apply only candidates with decision: "apply".

Candidate Quality Gate

Rule-based scans are only a recall tool. Before adding an edit to the ledger, confirm all of the following:

1. The issue is visible prose, not a byproduct of hidden Word fields, Zotero fields, cross-references, formulas, variables, captions, or table/figure numbering.
2. The original phrase is exact, local, and can be replaced within one paragraph without flattening citations, equations, embedded objects, or complex formatting.
3. The replacement fits the selected mode: Minimal Mode candidates must fix clear language/mechanics errors; Polishing Mode candidates may improve fluency or clarity but must be marked as mode: polishing and remain low-risk.
4. The replacement does not change a statistical value, construct, model, variable, claim strength, causal interpretation, limitation, or scope statement.
5. The edit remains useful when reviewed in tracked-change form; if tracked changes would make a title, formula, or table visually confusing, prefer a note or defer to author review.

If a full-document review yields only a few high-confidence corrections, apply only those few. Do not add low-confidence or stylistic edits to make the output look more substantial.

Embedded DOCX Revision Rules

The bundled tool is the default implementation path for DOCX work.

• Prefer exact phrase replacements anchored by part and paragraph_index.
• Do not use broad search-and-replace unless every occurrence has been reviewed or the pattern is mechanically safe.
• Preserve the original file by writing to a new output path.
• Preserve existing tracked changes. Add a fresh layer with non-colliding revision IDs.
• Do not accept, reject, flatten, or normalize existing revisions unless the user explicitly requests it.
• Preserve package parts, styles, media, notes, tables, captions, citations, cross-references, and relationships.
• Treat hidden Word field instructions, Zotero fields, cross-reference fields, equations, drawings, embedded objects, footnote/endnote markers, and comment anchors as protected structural content.
• Do not directly patch paragraphs containing protected structural content unless the edit is mechanically safe and has been explicitly reviewed in context. The bundled tool skips many of these paragraphs by default to avoid damaging citations, formulas, and references.
• If a candidate cannot be located exactly, leave it unapplied and report it in the apply report.

Read references/docx-tracked-changes.md when implementing or debugging tracked-change DOCX edits.

Protected Content

Do not change these unless the user explicitly asks and the correction is clearly required:

• Numbers, p-values, confidence intervals, fit indices, loadings, thresholds, cutoffs, sample sizes, degrees of freedom, dates, percentages, and table values.
• Model names, construct labels, factor labels, item names, scale names, measure names, condition names, group labels, software names, package names, citations, references, table or figure callouts, and appendix labels.
• Direction or strength of findings, causal language, limitation statements, hypotheses, research questions, and conclusions.
• Terms of art in the manuscript's discipline, including psychometric, statistical, sociological, educational, psychological, policy, and public-health terminology.
• Section headings, questionnaire item wording, instrument names, author-provided labels, equations, and statistical notation.

Section-Aware Safeguards

• Abstract and introduction: do not make the contribution sound broader, stronger, more novel, or more causal.
• Theory and literature review: do not change theoretical constructs, author attributions, disciplinary framing, or the strength of prior-work claims.
• Methods: do not change design labels, sampling procedures, measures, instruments, item wording, variables, model names, software, or analysis sequence.
• Results: do not change numbers, statistical notation, thresholds, interpretation direction, significance language, or uncertainty.
• Discussion: do not strengthen implications, policy recommendations, causal claims, limitations, or generalizability.
• Reviewer-response materials: do not claim that a revision was made unless it is visible in the manuscript or explicitly supplied by the author.

Read references/social-science-language-editing.md for broader social-science safeguards. Read references/psychometrics-language-editing.md for measurement, scale, CFA/EFA/IRT/SEM/DIF, and validity terminology.

External Skill Lessons Incorporated

This skill borrows design patterns, not writing style, from external science-writing skill sets:

• From Nature-style skill organization: keep task context explicit, use section-aware rules, and load deep references only when needed.
• From scientific skill bundles: put repeatable and fragile file operations into scripts, write outputs to files, and verify results structurally.

Do not import the Nature-style goal of making prose sound like Nature unless the user explicitly asks for that kind of style. The default is controlled SSCI manuscript editing.

Output Modes

Choose the narrowest output that satisfies the request:

• Tracked revised DOCX: default for both Minimal Mode and Polishing Mode. This is for author review, not final layout judgment.
• Candidate ledger: use internally; share only if the user asks or if uncertain edits need review.
• Verification report: summarize revision counts, package integrity, and any unapplied candidates.
• Clean accepted-changes DOCX or PDF preview: only when the user asks for a clean version, accepted changes, or submission-layout QA. Do not silently replace the tracked file with a clean file.
• Tracked-change PDF preview: useful to confirm rendering succeeds and revisions are visible, but do not treat line breaks around insertions/deletions as final clean-layout evidence.
• Brief edit summary: summarize categories of corrections, not every tiny edit.
• Reviewer-response wording: provide concise wording such as, "We revised the manuscript for grammar, punctuation, and sentence mechanics while preserving the original meaning."

Common Mistakes