writing-skill
Assess and revise prose for clarity, structure, signposting, flow, and calibrated claims. Also draft reports and technical documentation. For academic papers and recommendation letters, default to outlines and substantive guidance rather than original prose. Use when the user asks to using writing skill (or write-like-mac).
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.
Core aim
Communicate findings faithfully, clarify method but: remove scaffolding, do not focus on process of arriving at conclusions. Do not have notes to coauthors or to seld in-line: either include as comments or save in memos/; do not have text positioning statements relative to past drafts; e.g. no need for “not” clarificatory statements unless readers would have thought otherwise. Do not make promises about future analyses of plans. Text should be self contained.
Make it easy for readers to understand the work quickly. Never make things seem more complicated than they need be.
When editing a paper, always use tracked changes or colored highlighting for substantial changes when the format supports (not needed for spelling / grammar fixes). Otherwise, use a patch, change log (news.md), or separate description of substantive edits.
Findings first
- State main claims early (abstract, intro, section openers)
- Do not build suspense and reveal conclusions only at the end
- Every section must justify itself on first contact; readers may not read linearly
- Abstracts emphasize what was found, not only what was done (nulls are findings)
General style guidance
-
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, 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)
Signposting
Social science writing is not literary writing. Signpost heavily. Assume readers will not read linearly.
- Open each section with its purpose; close with a brief recap when useful
- One core idea per paragraph. The first line signals that idea; split if there are two
- No repetition unless adding new information. Cut as mentioned above, it is important to note that
- Cut throat-clearing (In order to, I am now going to talk about). Short transitions that signpost are fine (Several take-aways follow. · I highlight two.)
Useful patterns (adapt; do not copy blindly):
- I show that X. Section 2 provides the logic. Section 3 describes the strategy. Sections 4–5 give results; Section 6 discusses implications.
- Three theories predict an adverse effect of X. I describe each in turn and present strategies to distinguish between them.
- I estimate the effects of X on Y using qualitative and quantitative strategies. I describe each in turn.
- I first present general background on this case, then explore whether there is evidence for each of mechanisms 1, 2, and 3.
- In the remainder of this section, I… / Several take-aways follow. / We highlight three. First,… Second,… Third,…
Subsection titles can be claims, not only labels.
Flow
Flow within and between paragraphs is very important. Do not concatenate strings of claims unless these are clearly building up on each other.
Sober claims (scholarly prose)
Understated and precise. Let substance carry weight.
- Do not inflate scope, novelty, or certainty
- Ban important / importantly as empty intensifiers (also crucial, critical, key when they add no content)
- Avoid proves, demonstrates conclusively, necessarily, always, transformative, groundbreaking, novel unless strictly warranted
- Prefer concrete nouns and verbs over stacked modifiers
- Err on the side of modesty when that is all that is warranted: may, can, suggests, is consistent with, under these conditions
- Report null and negative results plainly
When editing scholarly text, strip empty intensifiers and replace with specifics (if available; with track changes). Soften these sobriety rules to recommendation letters.
Style rules
| 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
- Emphasis: italics sparingly; never ALL CAPS.
- Do not call an empirical claim my theory.
- Inferences. Failure to reject the null is not proof of no effect.
that
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”-
Avoid effect-first constructions; especially with negation
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 passive voice
Avoid the passive voice. Agents first please.
Hand-holding quantitative walk throughs
When the reader must follow an algorithm on numbers, walk the arithmetic. Do not only report the result.
- Show the calculation: $\delta_{+}=\min(1-0.2,0.6)=0.6$, not only $\delta_{+}=0.6$
- Keep the updated state explicit after each step
- Give probabilities as a computed ratio, then the fraction
- One step per stretch of prose; finish the pair before the next
Examples of crisp phrasing
Use when natural, not as filler:
- Several take-aways follow. / Three implications follow.
- In the remainder of the [paper/section], I…
- The utility of this result depends on the plausibility of…
- Observe that… / Note that… / It follows that…
- This is distinct from… though that is part of it.
- Less well understood is… / This leaves open…
- The key feature here is not X but rather Y.
- Put differently: can…?
- We highlight three. / First,… Second,… Third,…
- In practice, however, a common strategy is…
Examples of flabby phrasing to avoid (scholarly prose)
- Empty important / importantly / crucially / it is worth noting that
- As mentioned above / It goes without saying / In this context (when empty)
- This paper contributes to the literature by… → I show / I establish / We describe
- It is well known that… → cite or show
- Interestingly, / A growing body of literature
- Vague implications for policy and practice without saying what follows
- Author notes in the manuscript; overloaded compound sentences
Other small style points
Common slip-ups to catch when drafting or editing:
- Past tense of lead is led, not lead
- lose / loose; advise / advice; its / it’s (prefer its and it is; never it’s in formal prose)
- fewer for countables, less for mass
- expertise not expertize
- Question begging is a technical term; use it only if you mean it
- Cut hyperbolic adjectives (vast, massive, extraordinary) unless the claim is literal
- Prefer Unsurprisingly over It should therefore come as no surprise that
- Do not write no measurable / detectable effect when you only mean that you have not detected one
- Necessary / necessarily is a strong claim; reserve it for when you mean it
Structure check
Default structure (empirical work)
- Abstract
- Introduction — question, approach, findings, and contribution early
- Theory — relate the question to existing knowledge
- Strategy — data, design, cases
- Main results — the heart of the piece
- Discussion — robustness, mechanisms, heterogeneity, cases
- Conclusion — recap, caveats, implications, new agendas
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.
By section
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.
Appendix
- Appendix should have its own table of contents
- Make sure that tables and figures are well placed in subsections and don’t bunch
- Order should largely track the order of the paper
- A PAP reconciliation section makes sense as a last item in an appendix: A PAP reconciliation section can usefully have two tables
- a list of all the preregitered objects and a column saying where these are reported and a columns saying if the analysis has changed
- a list of objects in the paper and an indication of where they were re-registered or are novel in cases in which anlaysis differs from planned, with good reason, report the planned analysis here if possible
Checks
References and links check
- Verify every link in text
- Verify every citation in text
- If a
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. - Make sure .bib files include a URL when one exists (prefer DOI or other stable links)
- If a cited source cannot be verified, flag it for the user
- Specific citations should have pages or sections indicated; verify when possible and flag when not
Tables and figures check
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
- Prefer ggplot2 where it fits the existing workflow
- Maximize the information-to-ink ratio: cut chartjunk and let the data dominate;
theme_bw()is the house starting point, not a requirement - Prefer confidence intervals (or other clear uncertainty displays) over point estimates alone
- Prefer facets when comparing subgroups, outcomes, or specifications side by side would help
- Self-explanatory: a reader should grasp the claim without hunting through the text
- Number and caption; say what is plotted and, when helpful, the bottom line (Figure shows…)
Tables
- Self-explanatory captions/titles; number them
- Do not paste raw software output (Stata printouts, unformatted console dumps)
- Coefficients in rows with clear, consistent variable names
- Standard errors in parentheses (or say what uncertainty measure you show)
- State the dependent variable when relevant
- Report N and fit statistics when they help readers assess the analysis; do not add an irrelevant R² merely to complete a template
- Use consistent precision appropriate to the estimand and uncertainty; about two significant digits is often a useful default, not a rule for every quantity
- A bottom-line sentence in or under the caption can help when it remains accurate out of context. Otherwise describe what is shown and leave interpretation to the text.
Math formatting check (Markdown / Quarto / Rmd)
- Inline use
$:$x$is $x$. - Display (single line) use
$$:$$y = \beta x + \varepsilon$$is:
- Multiline / aligned:
\begin{align}...\end{align}or$$\begin{aligned}...\end{aligned}$$ - Introduce symbols in prose: We use $x$ to denote…
- Probability operator:
\Pr(not barePr(in math mode
Also:
- check that all terms are defined before use, subscripts and superscripts used consistently, no overloading of any symbols
Other document types
-
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.
Output checklist
All genres
- Main claim visible without reading to the end
- Section and paragraph signposting present
- One core idea per paragraph; no repetition or empty phrases
- Contractions match the chosen register; formal scholarly prose uses the house default of none
- Compound sentences are clear; split comma-and clauses when doing so improves focus
- Structure matches genre
- Closing point present
- No author notes in the manuscript
Scholarly prose only
- Claims calibrated; no empty intensifiers; sober tone
- Math uses
$/$$ - Tables and figures self-explanatory; figures preferred where apt
- References verified; URLs where available