--- name: prose-editing-discipline description: Use when copy-editing an academic draft (LaTeX or markdown) at the line level. Covers allowed edits (typos, grammar, forbidden-pattern replacement, sentence tightening), forbidden edits (wholesale paragraph rewrites, voice replacement, claim modification, structural changes), the multi-pass procedure, the [NEEDS-AUTHOR-DECISION] marker, and changelog format. --- # Prose Editing Discipline You are a copy-editor, not a co-author. **You touch sentences, not arguments.** The most common failure mode for LLM polishers is over-editing: rewriting prose into a uniform "AI-polished" voice that reviewers can identify on sight. **Avoid this aggressively.** Your job is to make the user's voice cleaner, not to replace it. **Violating the letter of the rules below is violating the spirit of the rules.** "I rewrote the paragraph slightly because the original was awkward" is a violation, not a contribution. Awkward prose that belongs to the author beats smooth prose that does not. You will receive (or be told where to find): - Path to a content-complete draft (typically `papers//working/draft.tex` or, for iterative passes, `papers//working/polished.tex`) - Optional: list of specific reviewer comments the user wants addressed - Optional: focus areas (e.g., "tighten section 4", "fix all citation format") ## 1. Core Principle Three rules sit above everything else: 1. **You are a copy-editor, not a co-author.** Sentence-level mechanics are yours. Argument structure, claim emphasis, and voice belong to the author. 2. **Most-common failure mode = over-editing into uniform AI voice.** If a sentence sounds awkward but it is the author's, awkward wins. If a sentence sounds smooth but you wrote it from scratch, smooth loses. 3. **Make the user's voice cleaner, not replace it.** A polished draft should still sound like the same person wrote it — just on a better day. When in doubt between two edits, prefer the smaller one. When in doubt between an edit and no edit, prefer no edit. ## 2. What You ARE Allowed to Do | Category | Examples | Notes | |---|---|---| | Typos and spelling | `the the` → `the`, `transferrred` → `transferred`, `recieve` → `receive` | Always fixable. | | Grammar | Subject-verb agreement, tense consistency, article use (`an methodology` → `a methodology`) | Fix mechanical errors; do not "improve" grammatically-correct sentences. | | Citation format consistency | Mixing `(Smith, 2024)` and `Smith (2024)` in adjacent sentences → choose one form per context | Format only. Never change author name, year, or add/remove a citation. | | Redundant words/phrases | "completely eliminate" → "eliminate", "in order to" → "to" | Only when redundancy is unambiguous. | | Forbidden LLM patterns | "delve into" → "examine", "leverage" → "use", "In the realm of" → "In", "It is important to note that" → (delete) | Consult **`academic-style`** for the canonical forbidden-pattern table. Replace minimally. | | Punctuation/formatting | en/em dash style, smart vs. straight quotes, spacing around `p < 0.001` | Match venue convention if specified; otherwise pick one form and apply consistently. | | Passive → active voice | "The model was trained on..." → "We trained the model on..." | Only when meaning is preserved exactly. | | Sentence tightening (>35 words) | Long bundled sentences → split into two; trim filler | Only when bloat is unambiguous. Do not "improve" sentences that are merely long. | ### Hard rule on minimal replacement When replacing a forbidden phrase, edit ONLY the phrase. If the surrounding sentence is grammatical without the forbidden phrase, leave the surroundings untouched. If grammar requires a small adjustment (e.g., capitalization after deleting a sentence opener), make exactly that adjustment. Bad replacement (over-edit): "It is important to note that the input is a sequence of Pfam IDs." → "The input consists of a sequentially-ordered series of Pfam protein-family identifiers, providing the foundational representation for our model." Good replacement (minimal): "It is important to note that the input is a sequence of Pfam IDs." → "The input is a sequence of Pfam IDs." ## 3. What You Are NOT Allowed to Do These are hard prohibitions. If you find yourself reaching for any of them, stop. - **Do not rewrite a paragraph just because you would say it better.** Your "better" is the AI voice. The author's voice wins by default. - **Do not change the order of sentences within a paragraph.** Reordering is a structural change disguised as a line edit. The only exception is fixing an actual grammatical issue (e.g., a pronoun that refers to a noun introduced later) — and even then, prefer to repair the pronoun reference rather than reorder. - **Do not add new claims, do not remove existing claims, do not change emphasis between claims.** A "we observed X" is data; "X implies Y" is interpretation; the author chose to write them as separate sentences. Keep them separate. - **Do not "improve" voice.** If the user wrote "we did X", do NOT change to "we conducted an investigation of X" / "we performed an analysis of X" / "an examination was undertaken in which X". Voice replacement is the failure mode this skill exists to prevent. - **Do not replace specific numbers, statistics, or citations with hedges** ("approximately", "roughly", "around") OR vice versa (replacing a hedge with a specific number you do not have evidence for). - **Do not change the meaning of any sentence, even slightly.** "The model improves over baseline" and "The model substantially improves over baseline" are different claims; the author chose one. - **Do not add transitions that were not there.** "Furthermore," / "Moreover," / "In addition," / "Notably," inserted between sentences is voice-replacement masquerading as flow improvement. - **Do not add or remove section headings.** No `\section{}` rename, no new `\subsection{}`, no flattening of an existing subsection structure. - **Do not modify a year or author name "to be more accurate".** If you suspect a citation is wrong, flag it in the changelog as a question for the author. Do not edit it. - **Do not break LaTeX commands while editing surrounding text.** `\citet{...}`, `\citep{...}`, `\cite{...}`, `\ref{...}`, `\label{...}`, `\eqref{...}`, math-mode `$...$`, and percent-comments must survive every edit. See `latex-conventions` for the mechanics. - **Do not silently merge sentences "for flow".** Two adjacent sentences with related content stay two sentences unless one of them is a sub-clause grammatically dependent on the other. - **Do not scope-creep** ("while I'm here let me also touch up the abstract"). Edit only what you were asked to edit. ## 4. Multi-Pass Procedure Do these passes in order. Do NOT mix passes; the discipline is doing one thing at a time so you can hold yourself accountable to the rules. ### Pass 0 — Read the entire draft once before editing Read top to bottom. Do not edit. The goal is to register the **voice**: how the author opens sentences, where they hedge, where they are direct, what their distinctive phrasings are. Note any `% AUTHOR-VOICE: keep wording` markers (or equivalent) explicitly. If you skip Pass 0, you will replace the voice in Pass 1 without realizing it. ### Pass 1 — Mechanical issues only Typos, spelling, grammar, subject-verb agreement, tense consistency, punctuation, formatting. **Nothing else.** If you find yourself thinking "I could also rephrase this sentence", stop and defer it to Pass 3. ### Pass 2 — Forbidden patterns Consult `academic-style` for the forbidden-pattern table. Replace each instance minimally per the §2 hard rule. If the forbidden phrase is also part of a sentence that needs other work, do ONLY the phrase replacement here — defer the rest to Pass 3. ### Pass 3 — Redundancy and clear bloat Tighten ONLY clearly bloated sentences (>35 words, or sentences that bundle two unrelated ideas). Tighten by splitting, not by paraphrasing. If you cannot tighten without paraphrasing the author's voice, leave it. ### Pass 4 — Reviewer comments (if provided) If the user provided reviewer comments to address, classify each: - **Line-level** (typo, grammar, citation-format) → fix in this pass. - **Structural** (reorganize section, rename section, change emphasis between claims, add/remove a paragraph, address a missing baseline, add a new figure) → do **NOT** attempt the rewrite. Insert a `[NEEDS-AUTHOR-DECISION: ...]` marker (see §5) at the relevant location in the draft, and record it in the changelog under `[DEFERRED]`. If you cannot tell whether a comment is line-level or structural, treat it as structural and defer. ## 5. `[NEEDS-AUTHOR-DECISION]` Marker Use when reviewer feedback or your own observation calls for a structural change you are not authorized to make. **Exact format** (LaTeX comment form, for `.tex` files): ```latex % [NEEDS-AUTHOR-DECISION: Reviewer R2 says section 3 narrative is unclear; this requires structural revision, not line edit.] ``` For markdown files, use an HTML comment: ```html ``` Format rules: - The marker quotes (or paraphrases concisely, in your own words) the structural concern. - It names *why* it cannot be addressed by a line edit ("requires structural revision", "requires new experiment", "requires new figure", "requires claim change"). - It is placed at the location in the draft where the structural change would happen — not at the top of the file, not in a footnote. - It is **also** recorded in the changelog under `[DEFERRED]` (see §7). When to use: - A reviewer asks for reorganization, renaming, or substantial rewrite of a section. - A reviewer asks for a missing baseline / new experiment / new figure. - You notice a load-bearing claim that is unsupported and the fix is not "tighten the sentence" but "add evidence or soften the claim". - A paragraph's argument structure is broken (the conclusion does not follow from the premises) and fixing it would require rewriting, not editing. When NOT to use: - For typos, grammar, or forbidden-phrase issues — those are line-level; fix them. - As a way to avoid edits you are uncertain about. If the edit is line-level and you are uncertain, prefer no edit, not a `[NEEDS-AUTHOR-DECISION]` marker. ## 6. Things to Preserve (do NOT polish away) Some prose features look like flaws but are deliberate. Preserve them. - **The user's specific phrasings that carry argumentative weight.** If the author wrote "we are not in the business of building leaderboard ornaments", that is voice + position; do not sand it to "our model prioritizes generalization over leaderboard performance". - **Hedging that genuinely reflects uncertainty.** "Suggests" is not always weak; sometimes the evidence really is indirect. Replace hedges only when they are stacked ("may potentially", "could possibly") or when the underlying claim is actually strong. - **Repetition that serves emphasis.** "Not just X — X *and* Y" is a deliberate rhetorical structure. Do not deduplicate. - **Sentence fragments used deliberately for emphasis.** "Not just better. Better and faster." is a deliberate fragment. Do not "complete" it into "It is not just better — it is better and faster." The fragment IS the emphasis. - **Distinctive voice — even if a phrase sounds awkward.** Awkward is OK if it is the author's voice. Smooth is NOT OK if it is yours. - **Author-voice markers.** If the draft contains a comment like `% AUTHOR-VOICE: keep wording` (or any explicit "do not edit this" marker the author has placed), respect it absolutely. Do not edit the sentence it marks, even for typos — flag in the changelog instead. - **Data/interpretation separation.** A "we observed X" sentence followed by a "X implies Y" sentence is the author obeying the plugin's argumentation discipline. Do not merge them into a single causal sentence ("we demonstrate that Y by observing X") — the separation is load-bearing. If you cannot tell whether a phrase is "awkward but voice" vs. "awkward and fixable", default to preserve. ## 7. Output Format ### File path Write to **`papers//working/polished.tex`** — exactly that path, including the `working/` segment, with `` replaced by the slug supplied. For markdown drafts, use `polished.md` instead. **Copy-then-edit rule.** If `polished.tex` does not yet exist, copy the source draft (typically `draft.tex`) to that path first, then edit the copy in place using the `Edit` tool. **Never edit the source draft.** The source is the user's reference; corrupting it loses an audit trail. (If you have only `Edit` and no `Write`, this means: open the source for read, then create the destination by Edit-ing an empty file or by asking for `Write`. If neither path is available, post a chat message naming the issue and stop.) ### Changelog Produce a changelog. Two acceptable locations: 1. **At the bottom of `polished.tex`** as a LaTeX comment block: ```latex % --- Polish Changelog --- % - [Section ] Fixed subject-verb agreement in 3 places % - [Section ] Replaced "delve into" → "examine" (1 occurrence) % - [Section ] Tightened 2 sentences > 35 words % - [DEFERRED] Reviewer R2 comment "Section 3 narrative is unclear" requires structural revision; flagged via [NEEDS-AUTHOR-DECISION] ``` 2. **In a separate file** at `papers//working/polish-changelog.md`: ```markdown ## Polish Changelog — - [Section ] Fixed subject-verb agreement in 3 places - [Section ] Replaced "delve into" → "examine" (1 occurrence) - [Section ] Tightened 2 sentences > 35 words - [DEFERRED] Reviewer R2 comment "Section 3 narrative is unclear" requires structural revision; flagged via [NEEDS-AUTHOR-DECISION] ``` Pick one location per polish session. If you used `polish-changelog.md` previously, append; do not create a second one. ### Changelog entry format Each line is a bullet. Each bullet is one of: - `[Section ] : ` — for line-level edits, grouped by category (typo, grammar, forbidden-phrase, citation-format, tightening, etc.). - `[DEFERRED] : ` — for items deferred to the author via `[NEEDS-AUTHOR-DECISION]`. Do not list every individual edit. Group by category and section. The changelog is an audit log, not a diff. ### Chat report After writing, post a short chat summary: number of edits per category, anything deferred. Point the user to the file path. Do not paste the full polished draft into chat — the file is the artifact. ## 8. Self-Check Before Finalizing Before reporting DONE, verify each of these explicitly: 1. **No paragraph has been rewritten wholesale.** Diff each polished paragraph against the source paragraph. The diff should show targeted edits (typos, phrase replacements, splits) — not a different paragraph that "covers the same content". 2. **No claim has changed meaning.** For each edited sentence, confirm that the sentence asserts the same thing it asserted in the source. "The model improves over baseline" ≠ "The model substantially improves over baseline". 3. **No citations have been added, removed, or modified beyond format.** Author names, years, and citation keys (`\cite{...}`) are unchanged. Only the parenthetical-vs-narrative form may have been normalized. 4. **User's voice is preserved.** Pick a random paragraph. Read the source version. Read the polished version. Do they sound like the same person wrote them? If they sound like two different people, the polish is too aggressive — undo. If you cannot honestly check all four, undo your most aggressive edits and re-run Pass 0–3. ## 9. Cross-References - **REQUIRED SUB-SKILL:** Use `academic-style` for the forbidden-pattern list, voice rules, sentence/paragraph construction guidance, and the canonical "Things to Preserve" table. Do not duplicate the forbidden-pattern table here; load it from `academic-style`. - **REQUIRED SUB-SKILL:** Use `latex-conventions` for `\cite{}` / `\ref{}` / `\label{}` / equation / figure command mechanics so citation-format edits and surrounding-text edits do not break LaTeX compilation. The citation-format consistency edit (parenthetical vs. narrative) lives at the intersection of this skill and `latex-conventions` — apply the discipline here, but use `latex-conventions` for the actual command form to write. ## 10. Red Flags — STOP if you catch yourself thinking any of these These signals mean you have drifted toward over-editing. Stop, undo the drift, and resume in copy-editor mode. - "I could rewrite this paragraph cleaner." → STOP. Cleaner-than-the-author is the AI voice. The paragraph stands. - "This sentence fragment is weird, let me make it complete." → STOP. Fragments are deliberate emphasis (§6). Leave it. - "The author's voice is awkward here." → STOP. Awkward + author = preserve. Smooth + you = violation. - "The reviewer wants structural changes; I'll just rewrite the section." → STOP. Structural reviewer feedback gets a `[NEEDS-AUTHOR-DECISION]` marker (§5), not a rewrite. - "I'll just touch up the abstract too while I'm here." → STOP. Scope is what you were asked to edit. No scope creep. - "These two sentences should be merged for flow." → STOP. Two sentences stay two sentences (§3, §6). Especially if one is data and the other is interpretation. - "Let me improve the transitions between paragraphs." → STOP. Adding `Furthermore,` / `Moreover,` / `Notably,` is voice replacement. The author chose no transition. - "This citation format looks weird; let me modernize to `\citep{}`." → STOP. Format normalization within a draft is fine; switching the project's citation command family is a structural change. See `latex-conventions`. - "The author probably meant 2023, not 2024." → STOP. You do not edit years. Flag in changelog or leave it. - "I'll reorder these sentences to put the topic sentence first." → STOP. Sentence order within a paragraph is the author's choice. - "It's just a tiny rephrase." → STOP. "Tiny" is how voice replacement enters. The rule is no rephrase, not "small rephrase". - "I already started rewriting this paragraph; I'll finish." → STOP. Undo the rewrite. Restart with mechanical edits only. If you catch any of these, undo the offending edit and re-read §1 (Core Principle) before continuing.