Distilled from How to write. Prefer later edits the user adds to this file over this baseline.
This file combines correctness checks with house style. Apply the house preferences below by default, but do not present them as universal grammar rules or rewrite clear prose merely to enforce them.
Use this skill primarily to assess and revise writing. It may also draft reports and technical documentation, but treat original drafts as provisional and tell the user that they require review. For papers and recommendation letters, offer an outline with sections and substantive pointers rather than drafting prose, unless the user explicitly requests otherwise.
Communicate findings faithfully, clarify method but: remove scaffolding, do not focus on process of arriving at conclusions. Remove scaffolidng particular do not have notes to coauthors except if commented; do not have text positioning statements relative to past drafts; e.g. no need for “not” clarificatory statements unless readers would have thought otherwise.
Make it easy for readers to understand the work quickly. Never make things seem more complicated than they need be.
When editing a paper, preserve the author’s meaning and voice. Use tracked changes or colored highlighting for substantial changes when the format supports it and the user wants visible markup. Otherwise, use a patch, change log, or separate description of substantive edits.
Scholarly prose is relatively clipped but not opaque: short sentences, concrete nouns, plain verbs. State claims up front; let specifics do the work. Intuition for important or hard ideas is critical; never obscure. End with a point—what the reader should take away—not only procedural wrap-up.
When reviewing a recommendation letter or helping structure one, language can be more effusive, with more adjectives. Check that claims are backed by evidence or illustrations. Make sure that the bottom line is clear. Check consistency, including pronouns and institution names. Do not draft original letter prose by default.
Avoid ambiguity. (Bad: “France and the UK have two different legal systems. One has common law, one has civil law.” At a minimum follow order but better: “France has civil law..”, or perhaps “The former…” )
Avoid creating new terms for existing concepts. Flag when new terms are used without justification.
Avoid using multiple terms for the same concept in a paper. Check for consistency of terms (e.g. in theory, hypotheses, measurement, analysis)
Social science writing is not literary writing. Signpost heavily. Assume readers will not read linearly.
Useful patterns (adapt; do not copy blindly):
Subsection titles can be claims, not only labels.
Flow within and between paragraphs is very important. Do not concatenate strings of claims unless these are clearly building up on each other.
Understated and precise. Let substance carry weight.
When editing scholarly text, strip empty intensifiers and replace with specifics (if available; with track changes). Soften these sobriety rules to recommendation letters.
| Do | Avoid |
|---|---|
| Short sentences, tight prose | Flab, flower (much ink has been spilled) |
| Formal register; house default is no contractions | Casual contractions unless the chosen voice uses them |
| Present tense for what the text does | I will describe… / I described… for structure |
| Past tense for past events | |
| Modest claims; substance not hype | Superlatives in papers; exaggeration |
| Concrete nouns and verbs | Empty important, crucial, key, critical |
| Correct affect/effect, fewer/less, its/it’s | Prove for empirical claims; no detectable effect when you mean not detected |
| US spelling as the house default | Mixing spelling systems within one document |
| Italics for math symbols in prose | Starting a sentence with math |
| First, second (not firstly, secondly) | aforementioned; repeated points across paragraphs |
$…$ / $$…$$ for math |
\( \) \[ \]
except multiline align |
| Reader-facing claims only | Author notes in the manuscript |
Manuscript vs notes to the author. Running text and captions are for the reader. Production notes belong in chat or a memo or commented out. Never write there is no need for a figure, I dropped…, we could add…, as discussed, or TODO into the paper. Principle: try to have the paper be a shareable object at all times.
Comma-and clauses (house preference). Prefer splitting independent clauses when that makes the sentence shorter or prevents two distinct ideas from being buried together. A clear, grammatical compound sentence is acceptable; do not split it mechanically. example: not: “The contribution is real, and it is not the contribution the introduction claims” rather: “The real contribution is different to what the introduction claims”
example: Bad: Two comparisons are at play, and they are easy to confuse. Good: There are two separate comparisons. or Two comparisons are at play. Make sure not to confuse them
don’t skip ‘that’ if it creates ambiguity or makes things too terse:
Bad: The body still argues the result the abstract has already given up - Better: “The body still claims a result that the abstract has now dropped”-
Bad: The decline in Y was not the effect X was designed to produce. Better: X was not designed to produce a decline in Y
Avoid the passive voice. Agents first please.
When the reader must follow an algorithm on numbers, walk the arithmetic. Do not only report the result.
Use when natural, not as filler:
Common slip-ups to catch when drafting or editing:
Voice (house default): For single-authored work, I is fine; we only when it implicates the reader or discipline (we see from this figure…). Prefer I argue over this paper argues, unless venue or author convention differs.
Abstract. Should be absolutely clear what the paper achieves: the question, the strategy (data strategy, answer strategy), the findings.
Introduction. Motivation and question; methods preview; findings; contribution; optional roadmap. Open on a concrete problem or stakes, not a literature review. End with a roadmap when useful.
Theory. Motivate the argument; formalize if needed; state propositions; end with testable implications. Setup and results stay separate; flag assumptions; state limitations explicitly.
Strategy (quantitative). Hypotheses and estimands → population/cases → data and measures → analysis strategy.
Case studies. Justify selection; say what you look for and what you infer; distinguish typical/atypical or most-/least-likely cases.
Conclusion. Recap, caveats, implications, gaps. Land a closing point—what the reader should believe or do differently—not a summary alone.
Appendix. Put material that supports the main text without belonging in it: reconciliation reports (deviations from analysis plans), proofs of formal results, robustness checks, and tabular analogues of figures shown in the main text. Keep appendices short. Letter sections (Appendix A, Appendix B), do not number them. Every appendix section should be referenced from the main text. Prefer figures in the main text; tables that only back those figures can live in the appendix.
lib/ folder exists, note useful (lawful) holdings
that are absent. Do not download or save papers unless the user asks and
licensing and repository policy permit it.Prefer figures over tables when visual form materially improves comprehension. Use a table when readers need exact values or the figure would obscure them. Keep displays in the main body when they carry the argument; do not park them at the end by default.
Figures
theme_bw() is the
house starting point, not a requirementTables
$ : $x$ is \(x\).$$:
$$y = \beta x + \varepsilon$$ is:\[ y = \beta x + \varepsilon \]
\begin{align}...\end{align} or
$$\begin{aligned}...\end{aligned}$$\Pr( not bare Pr( in
math modeAlso:
Essays and commentary. Shorter paragraphs; one idea each; metaphor sparingly; close with focus on what can be done.
Short memos. Clipped factual tone: claim first, evidence second. Enumerate stakes (I see two gains.). End with a point for the decision, not only next steps.
Documentation. Such as for packages, projects: Clear, emphasize intuition. Not overly terse. Plenty of cross references between sections, pointers to further reading and related documents. Boxes and similar to highlight big / central ideas.
All genres
Scholarly prose only