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}

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

# 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.

---