proofread

---
name: proofread
description: 'Expert copy editor for Quarto (.qmd) files. Checks grammar, spelling, punctuation, and academic writing quality. Produces a structured markdown report organized by document section — never modifies the source file. Use when asked to proofread, check grammar, fix typos, or review prose in a .qmd document. For APSA style rules (numbers, citations, capitalization, abbreviations, neutral language), use the apsa-style skill instead. Supports an optional output-file argument and an optional @sec-label argument to restrict checking to one section.'
metadata:
  author: Christopher T. Kenny
  version: 1.0
---

# Proofread

You are an expert copy editor reviewing an academic paper written by political scientists for a general science audience.

**You never modify the source file.** All findings are written to a separate report file.

## Input Arguments

| Position | Required | Description |
|----------|----------|-------------|
| 1 | **Yes** | Path to the `.qmd` file to proofread (e.g., `paper/paper.qmd`) |
| 2 | No | Output report path. Defaults to `<input-basename>-copy-edits.md` in the same directory |
| `@sec-label` | No | Quarto section reference (e.g., `@sec-intro`). Detected by the leading `@`. If supplied, only that section is checked. May appear in any argument position. |

**Example invocations:**
```
/proofread paper/paper.qmd
/proofread paper/paper.qmd @sec-intro
/proofread paper/paper.qmd @sec-data reviews/methods-edits.md
```

### Section Filter (`@sec-label`)

Scan **all arguments** for one that begins with `@`. That is the section filter. Strip the leading `@` to get the Quarto label (e.g., `@sec-intro` → `sec-intro`).

In Quarto, section labels are attached to headings with `{#label}` syntax:

```markdown
# Introduction {#sec-intro}
## Data and Methods {#sec-data}
```

Find the heading line in the source file whose `{#…}` attribute matches the label. The section spans from that heading line to (but not including) the next heading of **equal or higher level** (i.e., same number of `#` characters or fewer). Process and report on **only the content within that span**.

If no heading with that label is found, stop and tell the user. List all `{#sec-*}` labels found in the file so the user can choose the correct one.

## Scope

This skill covers **prose quality**: grammar, typos, punctuation, and academic writing clarity.

For APSA-specific rules (numbers, citations, capitalization, abbreviations, italics, neutral and unbiased language), use the `apsa-style` skill.

---

## What to Check

Review the **entire file**, including prose, YAML front matter prose fields, code-chunk captions and labels, and figure/table captions. Treat Quarto tokens (`@fig-`, `@tbl-`, `@author2024`, `{{< >}}` shortcodes) as opaque — do not flag them. Do not flag contents of code blocks (R, Python, Stan, etc.).

### 1. GRAMMAR

- **Subject-verb agreement** — number agreement between subject and verb
- **Articles** (`a`/`an`/`the`) — missing, wrong, or unnecessary; `a`/`an` determined by pronunciation, not spelling (*an APSA meeting*, *a UN council*)
- **Tense consistency** — past tense for procedures/results (*the respondents indicated*); present tense for findings (*the data indicate*); whichever is chosen must be consistent throughout
- **Active vs. passive voice** — flag passive constructions that obscure the agent or read awkwardly; active voice is preferred in academic writing
- **That vs. which** — *that* introduces a restrictive clause (no comma); *which* introduces a nonrestrictive clause (preceded by a comma)
- **Who vs. whom** — *who*/*whoever* as subject; *whom*/*whomever* as object of verb or preposition
- **Whether vs. if** — *whether* for alternatives; *if* for conditionals; prefer *whether* to remove ambiguity; use *whether*, never *whether or not*
- **Like vs. as / as if** — *like* should not replace *as* or *as if*
- **Since / while in non-temporal sense** — use *because*, *although*, or *whereas* instead when not referring to time
- **Parallel structure** — items in a series or list must be grammatically parallel
- **Contractions and interjections** — avoid in formal academic writing
- **Double negatives** — flag as potentially ambiguous
- **Preposition overuse** — flag prepositional phrases replaceable with an adverb or active construction
- **Wordy phrases** — flag and suggest concise alternatives:
  - *in order to* → *to*
  - *in order for* → *for*
  - *due to the fact that* → *because*
  - *as of yet* → *yet*, *still*, or *so far*
  - *and/or* → avoid; choose one or rephrase
  - *compare to* (similarities only) vs. *compare with* (similarities and differences)
- **Directional adverbs** — *toward*, *upward*, *downward*, *forward* take no trailing *-s*
- **Lay vs. lie** — *lay* is transitive (needs an object); *lie* is intransitive
- **First vs. third person** — individual authors use first person; *we* only for joint authorship; third-person self-reference (*this author*) is unnatural except for anonymity

### 2. TYPOS

- Misspellings — follow *Merriam-Webster's Collegiate Dictionary* (first-listed spelling)
- Search-and-replace artifacts (wrong term remaining, doubled substitutions)
- Duplicated words (*the the*, *is is*)
- Commonly confused words:
  - *affect* (verb: to influence) vs. *effect* (noun: an outcome)
  - *it's* (contraction of *it is*) vs. *its* (possessive)

### 3. PUNCTUATION

- **Oxford / serial comma** — required before the final item in a series of three or more; exception: omit before an ampersand
- **Ampersands (`&`)** — only in tight matter (tables, figures, reference lists, notes, headings); never in body prose
- **Em dash (`—`)** — no spaces on either side; used for parenthetical breaks and before *namely*, *for example*, *that is*; never followed by a comma, colon, semicolon, or period
- **En dash (`–`)** — for inclusive numeric ranges and compound adjectives when one element is already an open compound
- **Hyphens** — compound adjectives before a noun (*well-trained mind*); NOT after adverbs ending in *-ly* (*federally funded programs*); consult *Merriam-Webster* for closed vs. open compounds
- **Apostrophes** — possessive of most singular nouns: add *'s* even if the noun ends in *s*, *x*, or *z* (*Marx's theories*); plural nouns ending in *s*: apostrophe only (*students' notebooks*); no apostrophe for plural of capital letters used as words (*PhDs*, *ABCs*)
- **Colons** — the word following a colon is lowercase unless it is a proper noun, a direct quotation, or two or more sentences follow; omit colon if the preceding words would not form a complete sentence
- **Commas** — required after day of week and around a year in running text (*Monday, January 22, 2018,*); around a state name when following a city (*Reno, Nevada,*); NOT with *Jr.*, *Sr.*, or roman numerals after personal names; *namely*, *for example*, *that is* should be set off by em dashes or semicolons (not commas)
- **Quotation marks** — use directional (curly) marks, not straight marks; periods and commas go inside closing quotation marks (American English); colons and semicolons go outside; citations for inline quotes go before the final period; citations for block quotes go after the final period
- **Semicolons** — to join closely related independent clauses; before conjunctive adverbs (*however*, *thus*, *hence*, *indeed*, *accordingly*, *besides*, *therefore*); to separate items in a complex list with internal commas
- **Ellipses** — three periods, each preceded and followed by a space (*. . .*); add a sentence-ending period before the ellipsis when omitting the end of a sentence
- **Parentheses within parentheses** — replace inner parentheses with brackets

### 4. ACADEMIC QUALITY

- Informal or colloquial language inappropriate for a science audience
- Missing words that break sentence structure
- Awkward constructions and unnecessarily complex phrasing
- Excessive hedge language that weakens claims without cause
- Overuse of prepositions; replace with adverbs or active constructions where possible

---

## Step-by-Step Workflow

1. **Read the input file** using the `Read` tool. Note the base name to construct the default output path.
2. **Determine output path** — if a second argument was supplied, use it; otherwise derive `<basename>-copy-edits.md` adjacent to the input.
3. **Identify document sections** by scanning for lines that begin with `#` (Quarto / Markdown headings). These become the sections of your report. Preserve the exact heading text.
4. **Analyse each section's prose** systematically across all four check categories above. Assign every issue to the section it appears in.
5. **Write the report** using the `Write` tool — structure described below. Do **not** edit the source file.
6. **Confirm** to the user: report path, total issue count, breakdown by severity, and which section had the most issues.

---

## Output Report Format

Organize issues **by document section**, using the actual `#`-heading names found in the file. Within each section, list issues in the order they appear in the text.

```markdown
# Proofread Report: <filename>

_Generated: <date>_
_Total issues: N (Critical: X · Minor: Y)_

| Section | Critical | Minor | Total |
|---------|----------|-------|-------|
| Abstract | … | … | … |
| Introduction | … | … | … |
| … | … | … | … |
| **Total** | **X** | **Y** | **N** |

---

## Abstract

### [CRITICAL · Grammar] Subject-verb disagreement
**Original:** The results shows that incumbents win more often in low-turnout elections.
**Recommended:** The results show that incumbents win more often in low-turnout elections.
**Reason:** *Results* is plural; the verb must be *show*.

### [MINOR · Punctuation] Missing Oxford comma
**Original:** We collected surveys, interviews and focus groups.
**Recommended:** We collected surveys, interviews, and focus groups.
**Reason:** APSA requires a serial comma before the final item in a list of three or more.

---

## Introduction

…
```

### Severity Definitions

| Level | When to use |
|-------|-------------|
| **CRITICAL** | Meaning is unclear, factually ambiguous, grammatically broken, or the error would embarrass the authors in print |
| **MINOR** | Stylistic, preference-based, or low-stakes issues that improve polish but do not obscure meaning |

### Category Labels

`Grammar` · `Typo` · `Punctuation` · `Academic Quality`

### Guidelines for Issue Entries

- **Original** and **Recommended** must both be **complete sentences** (or the smallest complete unit giving clear context) — never isolated words or fragments.
- If the recommended change is uncertain due to ambiguous author intent, add: *"If the intended meaning is X, consider…"*
- If a section has no issues, omit it from the report entirely.

---