---
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:

```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 **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 follow)
- **After a colon** — lowercase unless proper noun, direct quotation, or two or more sentences follow

### 3. ABBREVIATIONS

- **First use** — spell out on first occurrence with abbreviation in parentheses immediately after; omit if the term appears fewer than five times and is not a recognized noun in abbreviated form
  - *United Nations (UN)*, *International Monetary Fund (IMF)*; but ATM, IQ, DIY need no introduction
- **e.g., i.e., et al.** — roman type (not italicized); use only in parentheses or tight matter (tables, notes, captions); never in running prose — spell out (*for example*, *that is*, *and others*); a comma must follow before any additional content
- **No periods** in most abbreviations; exceptions: those consisting of lowercase letters or given-name initials (*etc.*, *a.m.*, *p.m.*, *Jan.*, *Gov.*, *Ms.*)
- **Academic degrees** — no periods (*BA*, *MA*, *PhD*, *JD*, *LLM*); spelled-out forms lowercase (*a bachelor's degree*)
- **Civil/military titles** — abbreviate before a full name (*Sen. Kamala Harris*); spell out before surname only (*Senator Harris*)
- **States and countries in running text** — spell out (*United States*, *United Kingdom*); exceptions that may remain abbreviated: UAE, US, UK, GDR, FRG, USSR
- **Article before abbreviation** — determined by pronunciation aloud (*an APSA meeting*, *a UN Security Council chamber*)
- **Organization as citation author** — include short form/acronym in parentheses on first reference, use acronym thereafter

### 4. ITALICS

- **Titles of works** — books, journals, periodicals, newspapers, blogs, films, video games: italicized; article, chapter, blog-post, dissertation, and website-section titles: quotation marks; book series and websites: roman, no quotation marks
- **Legal cases in running text** — italicized, including *v.* (*Miranda v. Arizona*); set in roman in reference lists
- **Foreign-language words** — italicize on first occurrence; proper nouns exempt
- **Latin expressions** — most are assimilated and should NOT be italicized (*ex officio*, *ad nauseam*, *in situ*, *a priori*, *de facto*); flag incorrect italicization
- **Mathematical variables** — italicize letters used as variables in equations (*3x + y*, *p* < .05)
- **Words used as words** — italics preferred over quotation marks
- **Avoid** boldface and underline in manuscript body text; italics for emphasis only

### 5. IN-TEXT CITATIONS

- **Format** — `(Author Year)` for parenthetical; `Author (Year)` for narrative; no comma between last name and year
- **Page numbers** — required for direct quotes and specific data; comma after year, then page numbers (*Jentleson 2015, 12–14*); omit *p.* or *pp.* unless needed to avoid ambiguity
- **Two or three authors** — cite all names every time; use *and*, not `&` (*Roberts, Smith, and Haptonstahl 2016*)
- **Four or more authors** — *et al.* in roman type after first author's name (*Angel et al. 1986*)
- **Multiple sources in one citation** — same parentheses, separated by semicolons, alphabetized (*Hauck 2000; Jordan et al. 1999*)
- **Same author, different years** — can omit name on second source (*Barbarosa 1973; 1978*)
- **Same author, same year** — add lowercase letter to year (*Frankly 1957a, 1957b*)
- **Citation placement** — before the final period for regular inline citations; after the final period for block quotes
- **Block quotes** — 100+ words or 2+ paragraphs; not enclosed in quotation marks; citation follows end punctuation; introduced by a sentence ending with a period (or colon if *as follows* or similar)

### 6. NEUTRAL AND UNBIASED LANGUAGE

Per the APSA Style Manual (pp. 25–27):

- **Gender neutrality** — avoid gendered pronouns when the referent is not a specific individual; preferred strategies in order: omit pronoun, use plural antecedent, use *one*, use *who* clause, use imperative mood; avoid *s/he* and *(wo)man*
- **Singular *they*** — acceptable and required for individuals who do not identify with a gender-specific pronoun; takes a plural verb
- **Racial / ethnic identity** — *Black* and *Indigenous* capitalized when referring to race; *white* lowercase; omit hyphen in compound ethnic identifiers (*African American*, *Asian Pacific Islander*); use current, respectful terminology
- **LGBTQ+ language** — *transgender* is an adjective, never a noun (not *transgendered*); use specific identity terms when applicable
- **Disability language** — people-first terminology preferred (*person with Down syndrome*); flag potentially offensive terms unless contextually essential and enclosed in quotation marks
- **Unnecessary personal characteristics** — flag references to race, gender, age, etc. that are not essential to the manuscript's argument

### 7. APSA COMMONLY USED TERMS

Flag incorrect forms and suggest the APSA-preferred spelling:

| Incorrect | Correct |
|-----------|---------|
| *advisor* | *adviser* |
| *co-author*, *co-editor* | *coauthor*, *coeditor* |
| *decision-maker*, *decision-making* (noun) | *decision maker*, *decision making* |
| *e-mail* | *email* |
| *policy-making* (noun), *policy-makers* | *policy making*, *policy makers* |
| *re-election* | *reelection* |
| *9/11*, *9-11*, *September 11th* | *September 11* |
| *social-networking site* | *social networking site* |
| *transgendered* | *transgender* (adjective only) |
| *Ph.D.* | *PhD* |
| *congressman*, *congresswoman* | *representative* |
| *meta analysis* | *meta-analysis* |
| *under-represented* | *underrepresented* |
| *World wide web*, *Web* | *World Wide Web*; *web*, *website*, *webpage* (lowercase) |

---

## 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>-style-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** across all seven check categories above. Assign every issue to the section in which it appears in the text.
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
# APSA Style Report: <filename>

_Generated: <date>_
_Style guide: APSA Style Manual for Political Science (2018, updated 2023)_
_Total issues: N (Critical: X · Minor: Y)_

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

---

## Abstract

### [MINOR · Numbers] Numeral should be spelled out
**Original:** We analyzed 3 cases across 5 countries.
**Recommended:** We analyzed three cases across five countries.
**Reason:** APSA requires spelling out cardinal numbers zero through nine in running text.

---

## Introduction

### [CRITICAL · Citation] Ampersand used in narrative citation
**Original:** As Smith & Jones (2019) argue, polarization has increased.
**Recommended:** As Smith and Jones (2019) argue, polarization has increased.
**Reason:** APSA uses *and*, not `&`, when citing two or three authors.

…
```

### Severity Definitions

| Level | When to use |
|-------|-------------|
| **CRITICAL** | Violates a clear APSA rule in a way that would cause rejection or embarrassment; or creates ambiguity |
| **MINOR** | Departs from APSA preference but meaning is clear; or involves a style choice with a standard correct form |

### Category Labels

`Numbers` · `Capitalization` · `Abbreviations` · `Italics` · `Citation` · `Neutral Language` · `Terminology`

### Guidelines for Issue Entries

- **Original** and **Recommended** must both be **complete sentences** (or the smallest complete unit giving clear context) — never isolated words.
- 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.

---