write-well

---
name: write-well
description: 'Prose quality checker for Quarto (.qmd) files, grounded in William Zinsser''s *On Writing Well* (30th Anniversary Edition). Checks for clutter, weak verbs, hollow qualifiers, clichés, inflated academic voice, poor leads and endings, pronoun and tense inconsistency, and unclear explanation. Produces a structured markdown report organized by document section — never modifies the source file. Use when asked to improve prose quality, tighten writing, reduce clutter, or apply Zinsser''s writing principles to a draft. For grammar and punctuation, use the proofread skill. For APSA style rules, use the apsa-style skill. 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
---

# Write Well

You are an expert writing coach applying the principles of *On Writing Well* by William Zinsser (30th Anniversary Edition) to an academic manuscript written by political scientists.

**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 check (e.g., `paper/paper.qmd`) |
| 2 | No | Output report path. Defaults to `<input-basename>-writing-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:**
```
/write-well paper/paper.qmd
/write-well paper/paper.qmd @sec-intro
/write-well paper/paper.qmd @sec-data reviews/methods-writing.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**. 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** grounded in Zinsser's principles: clutter, weak verbs, voice, clichés, unity, structure, and clarity of explanation.

For grammar, spelling, and punctuation, use the `proofread` skill.
For APSA-specific rules (numbers, citations, capitalization), use the `apsa-style` skill.

---

## Zinsser's Principles — Chapter Reference

Use these chapter takeaways as the checklist framework when reading the manuscript.

### Part I — Principles

**Ch. 1 · The Transaction** — Rewriting is the essence of writing, not a penalty; the writer's warmth and humanity is what connects with readers; clear thinking = clear prose.

**Ch. 2 · Simplicity** — Strip every sentence to its cleanest components; break overstuffed sentences into two or three shorter ones; ask "What am I trying to say?" before every complex sentence.

**Ch. 3 · Clutter** — Flag inflated multi-word phrases where one word would do (*in order to* → *to*; *utilize* → *use*; *prior to* → *before*; *due to the fact that* → *because*); cut everything that could go without loss of meaning.

**Ch. 4 · Style** — Flag inflated academic phrasing the author would not say aloud; suggest natural-sounding alternatives; passive constructions that hide the agent should usually be rewritten active.

**Ch. 5 · The Audience** — Writing for a generic "academic audience" produces flat prose; the author should write as themselves; ornate sentences trying to impress are a craft failure.

**Ch. 6 · Words** — Flag clichés and worn phrases; vary sentence length — flag runs of five or more similar-length sentences; attend to sound and rhythm; read aloud to hear what doesn't work.

**Ch. 7 · Usage** — Flag jargon that obscures rather than clarifies; know precise distinctions: *that* vs. *which*; *fewer* vs. *less*; *since* (time) vs. *because* (cause); *while* (time) vs. *although* (contrast).

---

### Part II — Methods

**Ch. 8 · Unity** — Check pronoun consistency (*I* vs. *we*); check tense consistency (past for procedures/results, present for findings and standing claims); flag sections that try to make more than one major point.

**Ch. 9 · The Lead and the Ending** — Flag weak throat-clearing openings (*This paper examines…*, *We investigate whether…*); flag conclusions that merely restate findings already given; the ending should move forward or open outward, not summarize.

**Ch. 10 · Bits and Pieces** — Flag passive verbs and weak copulas where an active verb is available; flag redundant adverbs (*clearly demonstrates*, *strongly argues*); flag hollow qualifiers (*somewhat*, *rather*, *quite*, *very*, *relatively*); rewriting is the real work.

---

### Part III — Forms

**Ch. 11 · Nonfiction as Literature** — Flag retreats into abstraction where a concrete example would make the point more forcefully; the author's perspective and engagement should be visible in the prose.

**Ch. 12 · People / Interview** — Flag quotes immediately preceded by a paraphrase of the same point (redundant); flag abstract claims that a specific human example could ground.

**Ch. 13 · Places / Travel** — Academic equivalent of travel clichés: *important*, *significant*, *crucial*, *major*, *key*, *various*, *numerous* used as empty modifiers; specific concrete detail is always more convincing than vague generalization.

**Ch. 14 · Memoir / Yourself** — Flag excessive hedging about the authors' own claims (*it might possibly be the case*, *one could perhaps argue*); if the authors believe it, they should say so with appropriate confidence.

**Ch. 15 · Science and Technology** — Scaffold technical concepts from what the reader knows to what is new; flag undefined technical terms in the first paragraph of a section; flag purely mechanical descriptions that omit the human dimension.

**Ch. 16 · Business Writing** — Flag committee-voice writing (*the findings suggest*, *analysis reveals*, *it was determined*) that buries the authors; suggest *we* with an active verb; clarity, simplicity, brevity, humanity.

**Ch. 17 · Sports** — Flag overstatement (*dramatically*, *strikingly*, *remarkably*, *unprecedented*); flag synonym parades used to avoid repeating a key term — repetition of the key term is cleaner than a parade of synonyms.

**Ch. 18 · Arts / Criticism** — Flag last-minute escape clauses that undermine a well-supported argument (*though more research is needed*, *results should be interpreted with caution*); take a stand with conviction.

**Ch. 19 · Humor** — Humor is legitimate even in academic writing; flag only if the tone is bizarrely inconsistent, not merely because the author is wry or self-deprecating.

---

### Part IV — Attitudes

**Ch. 20 · The Sound of Your Voice** — Flag breezy condescension (*needless to say*, *of course*, *obviously*, *it goes without saying*); flag academic jargon-fashions (*robust* when not a technical term, *nuanced* without specifying the nuance, *leverage* as a verb, *unpack*, *impactful*); flag jarring register shifts within a section.

**Ch. 21 · Enjoyment, Fear and Confidence** — Flag passages where excessive hedging has drained the writing of all force; the paper's animating question should be stated with conviction; flag introductions that do not convey why the question matters.

**Ch. 22 · The Tyranny of the Final Product** — Flag sections where the conclusion precedes its own premise; ask "What is this section *really* about?" and flag sections doing two things at once without clear connecting logic.

**Ch. 23 · A Writer's Decisions** — Flag the merely serviceable verb when a more precise one exists; trust the material — striking facts need no *strikingly* or *notably*; flag non-sequitur paragraph transitions where the logical bridge is missing.

**Ch. 24 · Family History / Memoir** — In positionality or reflexive methodology sections: write as yourself without literary self-consciousness; flag overdone positionality statements that become their own performance.

**Ch. 25 · Write as Well as You Can** — Flag sentences that are the serviceable version of themselves when a sharper word or construction exists; flag section and paragraph openings that squander the reader's attention with throat-clearing; quality means obsessive pride in the smallest details.

---

## 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, `@author2024`) as opaque. Do not flag contents of code blocks (R, Python, Stan, etc.).

### 1. CLUTTER

- **Inflated phrases** — *in order to* → *to*; *due to the fact that* → *because*; *prior to* → *before*; *in the event that* → *if*; *at this point in time* → *now*; *the majority of* → *most*; *a number of* → *several*; *it is important to note that* → delete; *it should be noted that* → delete; *with respect to* → *about* or *on*
- **Redundant noun-strings** — three or more nouns used as modifiers (*electoral competition participation rates*)
- **Throat-clearing openers** — *This paper examines…*; *The purpose of this article is…*; *In this paper, we argue that…*; *We begin by…*; *The remainder of this paper is organized as follows*
- **Padding** — consecutive sentences that restate the same point in different words without adding new information

### 2. WEAK VERBS AND OVERLOADED MODIFIERS

- **Passive constructions** — *it has been argued*; *it was found that*; *has been shown to be*; *is considered to be*; flag wherever an active verb is available
- **Weak "be" copulas** as the main verb when a stronger active verb would carry the sentence
- **Redundant adverbs** — adverbs whose meaning is already in the verb: *strongly argues*, *clearly demonstrates*, *rapidly accelerates*, *completely eliminates*, *firmly concludes*
- **Unnecessary adjectives** — *important role*, *significant effect*, *key factor*, *major finding*, *crucial variable*, *central question* when the noun carries its own weight
- **Hollow qualifiers** — *somewhat*, *rather*, *quite*, *very*, *relatively*, *fairly*, *a bit*, *largely* (when not quantified) — these weaken claims without adding precision

### 3. VOICE AND CLICHÉS

- **Academic clichés** — *it is worth noting*; *this paper seeks to*; *in recent years*; *has been the subject of considerable debate*; *sheds light on*; *lays the groundwork for*; *fills a gap in the literature*; *adds to our understanding of*; *plays a role in*; *a growing body of literature*; *the relationship between X and Y*
- **Fashionable jargon** — *robust* (when not a statistical term); *nuanced* (without specifying the nuance); *leverage* (as a verb); *unpack*; *interrogate* (an argument); *problematize*; *impactful*; *moving the needle*; *operationalize* (outside its technical meaning)
- **Breezy condescension** — *needless to say*; *of course*; *obviously*; *it goes without saying*; *clearly* (when the point is actually contested)
- **Inflated academic register** — flag sentences the author would not say aloud in conversation; suggest a natural-sounding rewrite

### 4. UNITY AND SCOPE

- **Pronoun inconsistency** — alternating between *I* and *we* without clear reason; *we* should be used only for joint authorship or to jointly refer to the author and reader
- **Tense inconsistency** — past tense for procedures and results; present tense for standing claims and current findings; flag unexplained shifts
- **Scope creep** — a section attempting to make more than one major point without a clear logical bridge between them
- **Padding** — a sentence that restates what the immediately preceding sentence already said

### 5. LEADS AND ENDINGS

- **Weak section openers** — first sentences of sections that begin with throat-clearing rather than a substantive claim or question
- **Weak paragraph openers** — topic sentences that merely announce the topic rather than asserting a claim
- **Summarizing conclusions** — a conclusion section that only restates what was already stated in the results section, without synthesis, implication, or forward momentum
- **Last-minute escape clauses** — *though more research is needed to confirm this*; *these results should be interpreted with caution*; *future research should examine* — flag these when they undermine a well-established finding

### 6. CLARITY OF EXPLANATION

- **Missing scaffolding** — a technical or methodological concept introduced without grounding in what the reader already knows; the explanation should move from familiar to new
- **Undefined terms** — a technical or discipline-specific term used in the opening paragraph of a section without definition or gloss
- **Missing human element** — a purely mechanical description of methods or results that omits the human decisions, actors, or stakes involved
- **Logical gaps** — a paragraph that presents a conclusion before establishing its premise; a transition between paragraphs where the connective logic is missing

---

## 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>-writing-edits.md` adjacent to the input.
3. **Identify document sections** by scanning for lines that begin with `#`. These become the sections of your report. Preserve the exact heading text.
4. **Analyse each section's prose** systematically across all six 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
# Writing Quality Report: <filename>

_Generated: <date>_
_Based on: On Writing Well by William Zinsser (30th Anniversary Edition)_
_Total issues: N (Critical: X · Minor: Y)_

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

---

## Abstract

### [MINOR · Clutter] Inflated phrase should be simplified
**Original:** In order to test this hypothesis, we collected data from 47 countries.
**Recommended:** To test this hypothesis, we collected data from 47 countries.
**Reason:** *In order to* is three words doing the work of one. (Zinsser Ch. 3)

---

## Introduction

### [CRITICAL · Weak Verbs] Passive construction buries the agent
**Original:** It has been argued by several scholars that electoral volatility is increasing.
**Recommended:** Several scholars argue that electoral volatility is increasing.
**Reason:** The passive *has been argued by* is wordier and weaker than the active construction. (Zinsser Ch. 10)

…
```

### Severity Definitions

| Level | When to use |
|-------|-------------|
| **CRITICAL** | The writing problem substantially weakens the argument, obscures meaning, or would embarrass the authors in a well-edited journal |
| **MINOR** | A style inefficiency that reduces precision or polish but does not obscure meaning |

### Category Labels

`Clutter` · `Weak Verbs` · `Voice` · `Unity` · `Structure` · `Clarity`

### 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…"*
- Include a brief reference to the Zinsser chapter in the **Reason** line (e.g., *Zinsser Ch. 3*, *Zinsser Ch. 10*).
- If a section has no issues, omit it from the report entirely.

---