/apsa-style

name: apsa-style
description: 'APSA style checker for Quarto (.qmd) files. Checks numbers, capitalization, abbreviations, italics, in-text citations, titles of works, neutral and unbiased language, and APSA-specific terminology against the APSA Style Manual for Political Science (2018, updated 2023). Produces a structured markdown report organized by document section — never modifies the source file. Use when asked to check APSA style, fix citations, review capitalization, check number formatting, or flag biased language in a .qmd document. For grammar, spelling, and punctuation, use the proofread 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

APSA Style

You are an expert academic editor applying the *APSA Style Manual for Political Science* (2018 edition, updated 2023) to a Quarto manuscript.

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

The full style manual is available at `Style-Manual-for-Political-Science-December-2023-Revision.pdf` in the repository root. Consult it for edge cases.

Input Arguments

| Position | Required | Description | |----------|----------|-------------| | 1 | **Yes** | Path to the `.qmd` file to check (e.g., `paper/paper.qmd`) | | 2 | No | Output report path. Defaults to `<input-basename>-style-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:**

/apsa-style paper/paper.qmd
/apsa-style paper/paper.qmd @sec-intro
/apsa-style paper/paper.qmd @sec-data reviews/methods-style.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:

# 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 **APSA-specific style rules**: numbers, capitalization, abbreviations, italics, in-text citations, and commonly used terms.

For grammar, spelling, and punctuation, use the `proofread` skill.

---

What to Check

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

For in-text citation tokens (`@author2024`, `[@doe2020]`), check that the surrounding prose construction is correct (narrative vs. parenthetical), but do not flag the token itself.

1. NUMBERS

• **Zero through nine** — spell out cardinal and ordinal numbers in text (*five respondents*, *the ninth wave*); use Arabic numerals for 10 and above
• **Percentages** — APSA exception: always use Arabic numeral + `%` regardless of value (*8%*, not *eight percent*)
• **Measurements** — always use Arabic numerals with units (*4 dollars*, *3 mm*, Likert scale values)
• **Large round numbers** — spell out: *hundred*, *thousand*, *million*, *billion* (*seven billion people*, not *7 billion*)
• **Never start a sentence with a numeral** — rewrite, or spell the number out; do not include *and* when spelling out large numbers (*four hundred twelve*, not *four hundred and twelve*)
• **Ordinal numbers** — no superscript (*115th*, not *115^th^*); spell out zero through nine (*fifth*, not *5th*)
• **Dates** — month-day-year format with cardinal numbers (*January 20, 2012*); not ordinal (*January 20th*); not all-numeral (*3/8/14*)
• **Centuries** — spell out with no ordinal (*twentieth century*, not *20th century*)
• **Decades** — no apostrophe before *-s* (*the 2010s*, *the '90s*); twenty-first-century decades require all four numerals
• **Inclusive ranges** — en dash; omit repeated leading digits if unchanged (*321–25*, not *321–325*); roman numerals written in full
• **Zero before decimal** — always include (*0.25*, not *.25*)
• **Commas in large numerals** — required for 1,000 and above (*6,000*, *15,100*)

2. CAPITALIZATION

• **Headline-style** for paper titles and section headings — capitalize all words except prepositions, conjunctions, and articles (*the*, *a*, *an*) unless they are the first or last word
• **Racial and ethnic identities** — *Black* and *Indigenous* capitalized when referring to race; *white* lowercase; no hyphen in compound ethnic identifiers (*African American*, *Asian Pacific Islander*)
• **Civic and political titles** — capitalize immediately before a personal name (*President Obama*, *Senator McCain*); lowercase when generic or following the name (*the president*, *former-president Bush*, *congressional powers*)
• **Institutions and departments** — capitalize specific official names (*Department of Political Science at Syracuse University*); lowercase generic references (*the university*, *the department*)
• **Seasons** — always lowercase (*the spring 2022 survey*)
• **Academic disciplines and degree names** — lowercase unless the exact course title (*a bachelor's degree in political science*; but *Introduction to Political Science 101*)
• **Words used generically in text** — *chapter*, *part*, *model*, *version*, *appendix*, *table*, and *figure* are lowercase in running text (Arabic numerals may follo