write-like-mac

Distilled from How to write. Prefer later edits the user adds to this file over this baseline.

Save this page and point your AI at it (for example, if you use Cursor, put it under ~/.cursor/skills/write-like-mac/SKILL.md).

Core aim

Communicate findings faithfully, clarify method but do not focus on process of arriving at conclusions. Make it easy for readers to understand the work quickly. Never make things seem more complicated than they need be.

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.

Default structure (empirical work)

1. Introduction — question, approach, findings, and contribution early
2. Theory — relate the question to existing knowledge
3. Strategy — data, design, cases
4. Main results — the heart of the piece
5. Discussion — robustness, mechanisms, heterogeneity, cases
6. Conclusion — recap, caveats, implications, new agendas

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

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)

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.

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. Do not apply these sobriety rules to recommendation letters.

Style rules

Manuscript vs notes to the author. Running text and captions are for the reader. Production notes belong in chat or a memo. Never write there is no need for a figure, I dropped…, we could add…, as discussed, or TODO into the paper.

No comma-and second clause. Do not join two independent clauses with a comma plus and. Split into two sentences, or keep one subject and two verbs. Lists of nouns are fine.

Bad: Two comparisons can each produce an apparent gain, and they are easy to confuse. Good: Two comparisons can each produce an apparent gain. They are easy to confuse.

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

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

Math (Markdown / Quarto / Rmd)

• Inline: $x$ is $x$.

• Display (single line) $$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 bare Pr( in math mode

References and links

• Verify every citation in text
• If lib/ folder exists and access available, save cited papers in lib file
• 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

By section

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.

Abstracts. Problem or context → what you show → implication or scope.

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.

Tables and figures

Prefer figures over tables when the same claim can be shown visually. Keep displays in the main body when they carry the argument; do not park them at the end by default.

Figures

• Prefer ggplot2 where possible
• Maximize the information-to-ink ratio: cut chartjunk; let the data dominate; theme_bw() default
• 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 R² (or analogues) when available
• About two significant digits (e.g. 0.12, not 0.000121313245)
• A bottom-line sentence in or under the caption is often useful: Table shows no evidence that…

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.

Hand-holding quantitative walks

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

Phrases that fit

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’s 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…

Phrases 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; comma-and second clauses

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
• No contractions; formal but plain language
• No comma-and second clause
• 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