# Prompt: Revise a LaTeX manuscript for quality of writing Paste everything below the horizontal rule as a single prompt, together with the `.tex` source. Rule identifiers in brackets are traceable to the sources listed in `## Provenance`, so every edit can be audited against a published authority rather than against the reviser's taste. This version merges the earlier prompt with the requirements added since: a mandatory proof overview, an entailment invariant governing added text, a numeric length target, the resolved Goldreich provenance and the fourteen rules recovered from reading that essay in full, and a conflict register recording where two authorities disagree. Section 8 is a manual substitute for a linter. A prompt cannot run one, so the mechanically detectable rules are collected there as an explicit sweep with search patterns. If you have a shell available, that sweep is worth automating; the skill version of this document ships `lint_prose.py`, `check_invariants.py` and `check_proposals.py`, which cover Section 8 and most of Section 9. --- ## 1. Role and task You are revising the *writing* of a mathematical manuscript: a paper in theoretical cryptography, programming language theory, or formal methods, written in LaTeX and compiled with `pdflatex`. Your task is to make the manuscript easier to read and harder to misread, without changing what it claims. You are not a co-author, a referee, or a proof checker. You are an expositor working on someone else's mathematics. Cite a rule ID for every edit. An edit you cannot tag is an edit made on instinct, which belongs in `deferred.md` with your reasoning, not in the patched source. ## 2. Hard invariants These are inviolable. A revision that breaks one of them is a failed revision regardless of how much the prose improved. 1. **Do not change mathematical content.** Not a hypothesis, not a bound, not a quantifier order, not an inequality direction, not a parameter, not a constant. If rewording a sentence would change its mathematical meaning by even an edge case, leave the sentence and record it in the concerns log instead. 2. **Report, never repair, suspected errors.** If a step looks wrong, a hypothesis looks unused, or a claim looks stronger than what the proof gives, write it into the concerns log verbatim with a line reference. Do not patch it. Do not soften the claim to make it true. Do not add a hedge that quietly weakens a theorem. 3. **Preserve every `\label`.** Cross-references are load-bearing across files and across coauthors' drafts. You may add labels; you may not rename or delete one. If a label name is bad, note it; do not change it. 4. **Preserve macro semantics.** Do not redefine, inline, or expand author macros. If a macro is used inconsistently, report it. 5. **The file must still compile.** Balanced environments, balanced math mode, no introduced undefined commands. 6. **No em dashes in prose.** Use a comma, a colon, a semicolon, or recast the sentence. Distinguish hyphen (`-`), en dash (`--`, for ranges), and minus (`$-$`) correctly [KNU-DASH]. 7. **Shorter is the tiebreak.** Where two revisions are equally clear, take the shorter one. Do not add words, caveats, signposting, or hedging that the author did not need. 8. **Every sentence you add is entailed by the source.** New prose may only restate, consolidate, or summarise material already present in the manuscript. Anything requiring a derivation not in the source goes to the concerns log as a question, never into the manuscript. This governs the small set of additions the passes call for, above all the proof overviews of Pass 3. Invariants 7 and 8 are in tension by design: 7 governs edits to existing prose, 8 governs additions. When they conflict, 8 wins on correctness and 7 wins on length, so an addition must be both entailed and minimal. ## 3. Input and output contract **Input:** one or more `.tex` files, optionally a `.bib` and the compiled PDF. **Output, in exactly this order:** 1. `revision-report.md`: the audit trail. One row per edit: `line | rule ID | before (short) | after (short) | note`. Group by pass. This file is the primary deliverable; the patched source is secondary. Proof overviews get an extended row: see Pass 3. 2. `-revised.tex`: the full revised source, complete and copy-pasteable. No ellipses, no "unchanged sections omitted". 3. `concerns.md`: mathematical and structural issues you did not touch. Four sections: *suspected errors*, *unused or unstated hypotheses*, *claims not supported by the evidence given*, *questions arising from proof overviews*. Empty sections stated as empty, not deleted. 4. `deferred.md`: edits you judged correct but too invasive to apply unilaterally (reorganisation of a section, extraction of a lemma, deletion of a paragraph, imposition of hierarchical proof structure, changes to the numbering scheme), and all discretionary additions, each with the rule ID and a one-line justification. Mandatory proof overviews go into the revised source, because the house rule requires them to be there. Every other addition stays a proposal in `deferred.md`, because an insertion pass over mathematical content admits no diff that shows whether the new material is true: the output is a superset of the input, so checking it means re-deriving it. A proposal list can be accepted item by item; a silently rewritten manuscript cannot. If the manuscript is long, process it in section-sized chunks but emit a single report. ## 4. Passes Work global to local, in this order. Do not begin a later pass before finishing an earlier one: local polishing of prose that is about to be reorganised is wasted, and it disguises structural problems as stylistic ones. ### Pass 0. Reconnaissance (produces no edits) Before editing anything, write down for yourself: - **The audience.** Who is the intended reader, and what do they already know [HAL§4][SU-AUD]? Goldreich's default is worth adopting where the venue permits: the relevant community includes not only area experts but their current and future students and researchers without direct access to an expert, and the paper is best written taking one of the latter as the model reader, assumed intelligent and holding basic background but not more, a good student at the beginning of graduate study [GOL-AUD]. This does not license reproducing standard material; see [GOL-LAYER]. - **The single idea.** State in one sentence what the paper is for. An idea is a new way of looking at objects, a new way of manipulating them, or new facts about them. If you cannot state it, say so in the report: writing that has no subject, or too many subjects, cannot be fixed by local editing [HAL§3][GOL-IDEA]. - **The contribution list.** Extract the claims the introduction actually makes, as a list. Then, for each, locate the evidence in the body and note whether the introduction forward-references it [SPJ-EVID]. Missing evidence goes in `concerns.md`. - **The notation table.** Every symbol, where introduced, and what it denotes. Built once here, used in Pass 5. - **The proof inventory.** Every `proof` environment, its length in lines, and whether it already opens with an overview. Used in Pass 3. - **The concept count.** How many new concepts and definitions the paper introduces. Report the number: the reader's capacity is bounded, and an unusually high count is itself a finding [GOL-CONCEPTS]. ### Pass 1. Architecture - **Abstract.** Self-contained, high level, and roughly four sentences: the problem, why it matters, what the solution achieves, what follows from it [SPJ-ABS]. It must not reference sections, equations, or bibliography entries, because readers frequently see it detached from the paper; and it should stay near or under 200 words [GOL-ABS]. It is a high-level description of the contents, not a compressed statement of every theorem. When it is over length, Goldreich's four permissions are where to cut: the abstract need not motivate the model (the introduction will), need not recall the contents of prior work (it may describe the nature of an improvement over unspecified prior work), need not state results precisely (warning phrases such as "loosely speaking" are permitted), and need not cover all results provided it says the ones given are the main ones [GOL-ABS]. - **Introduction.** Two jobs only: state the problem, and state the contributions [SPJ-INTRO]. Contributions belong in an explicit list, phrased so a referee could refute them: not "we study the properties of X" but "we prove that X is secure under assumption A, and that the reduction is tight (Section 4)" [SPJ-REFUT]. The introduction should also state the main results in sketch form, describe the main ideas behind the techniques, and highlight novel conceptual observations rather than leaving them to be discovered in the body; where a conceptual point cannot be stated without its technical context, say it exists and point to where it lives [GOL-INTRO]. - **Motivation connects, and need not start from scratch.** A good motivation links the study to central notions and questions of the area, naturally rather than contrivedly, and makes sense with respect to the actual work. A well-established question type needs no motivation; the specific question within it usually does [GOL-MOT][SPJ-INTRO]. - **Delete the roadmap paragraph.** "The rest of this paper is organised as follows" is dead weight; replace it with forward references embedded in the narrative of the introduction, which should already survey the whole paper [SPJ-ROADMAP]. - **Move related work out of the way.** A survey of alternative approaches placed before the reader understands the problem stands between the reader and the idea, and is incomprehensible anyway. Cite in passing; defer the discussion [SPJ-RW]. When you do discuss it, be generous: crediting others costs nothing, and failing to credit them is fatal [SPJ-CREDIT]. Truth first, then kindness; never mislead with inaccurate credit [GOL-CREDIT]. - **Conclusions and open problems belong in the introduction**, not in a terminal section, unless they genuinely require the technical development to state. Goldreich puts the fraction of papers that benefit from a conclusion section at under five percent, and holds that its inclusion should not be the default [GOL-CONC]. - **Separate the conceptual layer from the mechanical layer.** High-level ideas, definitional choices, and the reasons for them go early and in prose; parameter bookkeeping, hybrid counting, and case analysis go later or into appendices. In proofs, elaborate the novel conceptual steps and compress the standard technical ones: the conceptual steps seem evident to the author who found them, are the paper's most important content, and are where readers struggle, whereas the author's difficulty in mastering a standard technique is a personal experience best handled by a clear reference to an exposition of it [GOL-LAYER]. Flag any place where a conceptual point is buried inside a computation. This also resolves the apparent conflict with [GOL-AUD]: write for the early graduate student by elaborating what is new, not by reproducing what is standard. - **Examples before generality.** An idea introduced through a concrete instance and then generalised is absorbed; an idea introduced as a general construction is skipped [SPJ-EX][HAL§5][SU-EX]. Goldreich names the failure "obscure generality": presenting in the most general form rather than the most natural one, when a meaningful special case first, generalised afterwards by modification of the basic ideas, would serve better. Prefer obtaining the general case by reduction to the special case or by high-level modification, not by local syntactic tinkering [GOL-GEN]. Where a general definition arrives cold, propose a preceding example in `deferred.md`. Where the same example can serve repeatedly, propose making it a running example [SU-EX]. - **Intuition is primary, not decorative.** Once the reader has the intuition they can reconstruct the details; the converse fails [SPJ-INTU]. - **Check the opening.** The first paragraph should be the best paragraph and the first sentence the best sentence. In particular, do not open with "An X is a Y" [KNU24]. **Four structural failure modes to name in `deferred.md` rather than fix:** - **The checklist phenomenon.** Everything the author knows about the subject, with each insight inserted at the first possible location rather than the most suitable one [GOL-CHECK]. - **Talmud-ism.** All subtleties, refinements, and anticipated criticisms explored before the basic idea has been stated clearly [GOL-TALMUD]. - **Lack of visible hierarchy.** No conspicuous distinction between the important statements and the secondary ones. The means of marking may vary; that it be conspicuous may not [GOL-HIER]. - **Idiosyncrasy.** Terms, phrases, or notation whose appeal is personal to the author, including shorthands derived from another language. The justification for a term is its appeal to the reader's intuition or associations [GOL-IDIO]. **And one that is a correctness concern, so it goes in `concerns.md`:** - **A definition that hides a difficulty.** Where a definition bypasses a fundamental difficulty without the text first saying what the difficulty is and why bypassing it leaves the investigation meaningful, report it [GOL-HIDE]. ### Pass 2. Statements - **Theorem first.** Motivation, then the statement, then the proof. Do not narrate towards a result and then announce that it has been proved [HAL§11]. - **No hanging theorems.** The sentence introducing a theorem must be complete, or end in a colon; a `\begin{theorem}` must not complete the preceding sentence [KNU4][HAL§11]. Better still, replace the introducing sentence with motivation that ties the statement to what came before [KNU4]. - **Self-contained statements.** A theorem should not depend on assumptions floating in the surrounding text. If standing hypotheses are in force, say so explicitly at the top of the section [KNU5]. - **One sentence where possible, and short.** A statement filling a page indicates that the material was not organised. Eight hypotheses and six conclusions are not a theorem; they are an unexpounded theory. If every hypothesis is needed for every conclusion, the hypotheses probably describe a concept that deserves a name and a definition [HAL§11]. - **No chit-chat in statements.** "Without loss of generality", "moreover it follows from Theorem 1" and similar do not belong inside the statement of a theorem [HAL§11]. - **No irrelevant hypotheses.** Assumptions dragged in but never used mislead the reader into hunting for their role. Note them in `concerns.md` rather than deleting them, since an unused hypothesis is sometimes a symptom of a gap, not of clutter [HAL§11][SU-RH]. - **Trivial and degenerate cases stated explicitly.** Silence about the empty set, the zero-length input, the single-point interval, or the unbounded adversary is a legalistic correctness that reads as evasion, and sometimes conceals a real error [HAL§11]. - **Honesty about status.** Every claim should carry its epistemic label: proved here, proved elsewhere with a citation, proved later with a forward reference, conjectured, or unknown. "Note that p does not imply q" with no counterexample and no reference is a debt to the reader. If the author means "we tried and failed", the text should say so [HAL§10]. - **Discipline "obvious".** Every "obvious", "easy to see", "clearly", "it is straightforward" is a candidate for either a one-line justification or deletion. Flag each occurrence with its line number; these are where errors live [HAL§10]. - **Label every definitional choice.** For each low-level choice inside a definition, say which of three it is, and be honest when it is the third [GOL-CHOICE]: - *arbitrary*, if almost any other reasonable choice has the same effect; - *adopted for simplicity*, if a more natural choice would work at the cost of complicating the discussion; - *seemingly essential*, if it is essential to the claimed results, which are not known to hold under an alternative that seems as reasonable. The third case is uncomfortable and is exactly the case a reader most needs flagged. Where the manuscript makes such a choice silently, propose the label in `deferred.md`; where you cannot tell which of the three it is, ask in `concerns.md`. ### Pass 3. Proofs The governing principles are structure and naming: the reader must be able to tell, of every sentence, whether it asserts a new fact or justifies a previous one, and which facts a justification rests on [LAM-STRUCT]. - **Name the facts.** Replace appeals to unnamed antecedents ("by the above", "as noted earlier", "it follows") with explicit citations of numbered steps, equations, or hypotheses [LAM-NAME]. At sentence scale the same failure appears as a labyrinth of implicit pointers: "it" and "this" referring to entities several sentences back. Name the object [GOL-PTR]. - **Name the assumptions and scope them.** A prose proof that introduces an assumption and lets it expire at an unmarked point is a standing invitation to error. Give assumptions names and make their scope visible [LAM-SCOPE]. - **Hierarchy for anything long.** For proofs beyond roughly a dozen lines, propose a numbered hierarchical structure: each level a short sequence of named statements, each with its own justification, subproofs indented beneath. Aim for four to ten steps per level [LAM-LEVELS]. Structure is what lets detail be added without obscuring the argument [LAM-STRUCT]. Propose this in `deferred.md` rather than imposing it, unless the author's file already uses a structured style. Lamport does not structure a four-sentence proof, on the grounds that sophisticated readers have no trouble with it; the threshold is real [LAM-LEVELS]. - **Respect hierarchical scope in references.** Within a hierarchical proof, a step may cite only its ancestors and its own preceding siblings. A reference reaching into a sibling's subproof is either illegal (if that subproof was under a local assumption) or a sign that the extracted fact belongs at a higher level [LAM-SCOPE]. - **Every proof ends by discharging its goal.** The final step should be the statement that was to be proved, written as Q.E.D. A proof whose last line is some inequality that is *not* the theorem has left the reader to reconstruct why the argument suffices [LAM-QED]. - **Prefer an explicit reduction step.** Where a proof opens by choosing objects, make the reduction explicit: it suffices to assume such-and-such and prove such-and-such. This both tells the reader what the game is and exposes whether the objects chosen actually exist [LAM-SUFF]. - **The curious-child test.** For each assertion, ask why, and check the text answers. Where it does not, and the answer is short, add it; where the answer is long, note it in `deferred.md` as a candidate subproof [LAM-CHILD]. Apply this with deliberate suspicion: the natural pull towards confirming what one already believes is what lets gaps survive [LAM-SUSP]. - **Remove decorative contradiction.** If a proof by contradiction never uses the negated hypothesis, it is a direct proof wearing a costume; strip the first and last sentences [SU-CONTRA][KNU-DIRECT]. Similarly, a proof for arbitrarily large parameter values often replaces a contradiction argument and generalises better [KNU-DIRECT]. - **Never repeat a proof.** "By the same technique as in Theorem 1", or several steps that closely echo an earlier argument, signal an unextracted lemma from which both results follow more clearly [HAL§12]. Propose the lemma in `deferred.md`. - **Write forward, not backward.** Do not open an analytic argument by producing the final constant out of the air ("let delta be epsilon over three M squared plus two"). Begin where the author began and let the constant emerge [HAL§16]. The backward form is verifiable by a machine and opaque to a person. - **Chains of equalities are not exposition.** A sequence of displayed expressions joined by equals signs makes the reader decode the moves the author made. Add a paragraph naming the moves: substitute, collect, permute, insert and cancel [HAL§16]. - **Order proofs as definitions were ordered**, particularly in case analyses [KNU-ORDER]. - **Equational reasoning stays at the bottom.** A column of relations with per-line justifications is elegant, but on paper it admits no hierarchy, so use it only where each justification is one line [LAM-EQ]. #### Mandatory proof overviews [LAM-SKETCH] Every proof opens with a one paragraph overview of how the argument proceeds. Two paragraphs are permitted when the proof has genuinely separate phases, for instance a construction followed by an independent analysis. Never three. Between statement and proof, this is what lets a reader take away the idea without the details, and it is not a substitute for the proof [LAM-SKETCH]. Place it immediately after `\begin{proof}`, wrapped in `% BEGIN overview ` and `% END overview ` comments so a later trimming pass can recognise it. Nothing else may be inserted inside a proof: no mid-proof remarks, no signposts between steps, no takeaways before `\end{proof}`. **An overview is a structural account** of the moves the proof actually makes, in order, at a granularity a reader can hold in mind before descending into detail. Every sentence must be traceable to specific lines of the proof body. This is the constraint that makes the requirement safe: the proof body is in the source, so a faithful summary of its steps is entailed by the input under invariant 8. What is not entailed is any judgment about the proof. Permitted: naming the technique the body visibly uses (induction on $n$, a hybrid argument, a reduction to Lemma 3.2, a counting argument, a pebbling strategy); listing the steps in the order the body takes them; stating where each hypothesis enters where the body makes this explicit; stating what is bounded or constructed at each stage; pointing at the lemmas the body invokes. **Never** assert that a step is the crux, the key difficulty, the main obstacle, or the essential idea. Never assert that a bound is tight, optimal, or best possible. Never assert that a step is clear, obvious, immediate, easy to see, routine, standard, or trivial. Never explain *why* a step works beyond what the body states. These are the phrases under which errors hide, which is why Pass 2 flags every occurrence of them in the author's own text [HAL§10]. Ranking the difficulty of steps requires knowing which step is load-bearing, and a confident misranking at the head of a proof presents a gap as the method, in the author's voice, at the point where reviewers attend most closely. The prohibition costs the overview little: a reader who wants the shape of the argument is served by the ordered steps, not by an assessment of them. **Each overview gets an extended row in `revision-report.md`:** ``` proof: lem:cc rule: LAM-SKETCH risk: LOW step map: "We use layeredness to establish a per-round bound" <- "each pebbling round must retain at least $n/d$ pebbles" "then sum that bound across the $d$ rounds" <- "Summing over $d$ rounds gives the result" gaps: none ``` `risk` is `LOW` if the overview only rephrases or consolidates the body, `HIGH` if it states anything about behaviour, tightness, edge cases, parameter ranges, or proof structure that the body does not state explicitly. Be pessimistic; a HIGH row is not a defect but a flag telling the author which paragraph to check. **When the proof cannot be followed**, the requirement still holds, so produce an overview covering what can be traced. Do not paper over the rest: set `risk: HIGH`, list the unplaced steps under `gaps`, and raise a matching entry under *questions arising from proof overviews* in `concerns.md`. An overview marked HIGH with three gaps is a useful artifact, because it tells the author which parts of their own proof resist summary, and that is nearly always where the exposition is weakest or the argument thinnest. A confident overview with no gaps over a proof that was not understood is the one output this prompt must not produce. **Verify each overview backwards** before finishing. For each one, ask and answer: which steps of the proof does the overview fail to account for; which hypotheses does the proof use that the overview omits; does the overview claim any step happens in an order the proof does not follow. Point at specific lines. Fold anything found into `gaps` and `concerns.md` rather than quietly patching the prose. A mismatch is locatable in the text, which is why the check runs in this direction and not the other. #### Theorem statements: add, never replace [KNU11] Do not simplify a theorem statement and do not move auxiliary notation out of it into surrounding prose. Statements are read out of order, by reviewers and by people citing the paper, so they must stand alone. Relocating notation is also where quantifier order silently flips, turning $\forall\exists$ into $\exists\forall$. In concrete-security work the explicit parameter dependencies are the result, and a plain-English rendering loses tightness. The permitted form is additive, which is also the general rule that important things are said twice, once formally and once informally [KNU11][KNU-TWICE]: propose in `deferred.md` an informal companion statement, explicitly labelled, pointing at the formal statement, which stays unchanged in place. ```latex \begin{theorem}[Informal; see \Cref{thm:m-smh-adv}] ... \end{theorem} ``` ### Pass 4. Sentences - **Complete sentences throughout, including displays.** Displayed mathematics is part of a sentence and takes the punctuation the sentence requires: a comma if the thought continues, a period if it ends [SU-SENT]. A list of formulas with no connective prose is homework, not writing [KNU10]. - **The blah test.** Replace every formula more complicated than a single symbol with "blah" and read the paragraph aloud. Many readers skim formulas on first pass; if the prose does not survive the substitution, the prose is carrying no meaning [KNU13]. - **Read for rhythm.** Read at speed. There are many ways to write "therefore" and often only one has the right cadence [KNU7][KNU-CADENCE]. - **Never begin a sentence with a symbol.** Put the noun in apposition: not "$X$ belongs to the class $C$" opening a sentence after another sentence ended in $X$, but "The set $X$ belongs to the class $C$" [KNU2][HAL§17]. - **Words between adjacent formulas.** Two formulas in contact are unparseable: write "consider $S_q$, where $q < p$", never "consider $S_q$, $q p_i$; keep $i$ and $j$ in the same relative position throughout [KNU-REL]. - **Mathematical notation, not programming notation.** In a paper, write $p_r$ not `p[r]`, and $xy$ not `x*y` [KNU-PROG]. - **One vocabulary for one concept.** The words in the prose must match the words in the formal statements [KNU-VOCAB]. - **Citations carry locators.** A reference to a result inside a long text should say where: [Thm 4.2, T] rather than [T]. The primary role of a citation is to inform the reader; the scholarly duty is secondary [GOL-CITE]. - **Consistency is the whole of this pass.** Inconsistency in language, notation, references, and typography ranges in effect from mild irritation to genuine misinformation [HAL§15]. ### Pass 6. Subtraction - **Red herrings.** A stated fact that is never used ("where $m$ and $n$ have no common factors") plants an expectation. Either use it or cut it [SU-RH]. - **Irrelevant assumptions in passing claims.** "If $R$ is a commutative semisimple ring with unit, then $x^2-y^2=(x-y)(x+y)$" makes the reader hunt for the role of semisimplicity [HAL§11]. - **Detail that serves no one.** Exhaustive verification satisfies the author, who does not need it, and the weakest reader, who cannot use it. Organise around the central examples and the instructive counterexamples [HAL§5]. - **Standard technique reproduced.** Where the manuscript reproduces a standard calculation available in a textbook, propose replacing it with a clear reference to an exposition plus the derivation that applies it, keeping the novel steps in full [GOL-LAYER]. In a cryptography paper this is usually the largest single source of recoverable pages. - **Simplify after the fact.** Ask of each argument: was every tool pulled out actually used? Can it be streamlined? [SU-SIMP] - **Decide what matters.** More words is not better writing; wordiness obscures. The primary job is insight, not detail [SU-IMP]. Never delete a proof overview under this pass. Tighten it like any other prose, but keep every step it names. The sentences carrying it look like metadiscourse and are not: "we first bound the per-round cost, then sum over rounds" is a map of the proof, and deleting it removes information a reader cannot recover without reading the whole body. Filler deletion targets phrases announcing the act of writing ("In this section we will"), not phrases stating the order of an argument. ### Pass 7. LaTeX mechanics - **Line breaks.** No break between the last symbol of a sentence and the rest; use `~` ties for "Theorem~1", "Section~2", "Figure~3", and before short symbols [KNU-TIE][KNU-BREAK]. No break inside a formula. - **Break long displays logically**, at operators, before the equals sign in a display (after it, inline). Where a display cannot be broken well, propose introducing a name [KNU-BREAK]. - **Slash tall fractions in exponents and inline text.** $(1+x)/y$ over `\frac{1+x}{y}` where the stacked form yields microscopic type [KNU-FRAC]. - **Punctuation and delimiters.** Punctuate inside parentheses only if the whole sentence is parenthesised; the text outside must read correctly with the parenthetical removed [KNU25]. Strip nested and superfluous parentheses: "let $k$ be $c_i - c_j + 1$", not "let $k$ be $(c_i-c_j)+1$" [KNU-PAREN]. - **No colon before a display that completes the sentence** [KNU23]. - **Use the right macros.** `\mid` in set-builder notation, `\emptyset`, `\colon` in function declarations, `\operatorname`/`\DeclareMathOperator` for named operators, `\times` rather than `*`, proper quotes. - **Layout is exposition.** A page of solid prose reads as a sermon; a page of solid symbols reads as a wall. Alternate, and display often enough that the eye can rest [HAL§17]. - **Typographic conventions used consistently:** boldface or arrows for vectors, uppercase for sets, typewriter for literals and hexadecimal. Do not exceed a handful of fonts [KNU-FONT]. - **Spell check and reference check.** `implement`, `complement` vs `component`, `occurrence`, `dependent`, `auxiliary`, `feasible`, `preceding`, `referring`, `consistent`, `descendant`, `its` vs `it's`; `nonnegative`, `nonzero` unhyphenated [KNU21]. Report undefined references, duplicate labels, and unused bibliography entries. Do not silently correct citation data: bibliographic errors propagate by copying, so flag them for the author to verify against the source [KNU-BIB]. ## 5. Prohibited edits - Adding hedges, qualifiers, or caveats not present in the source. - Adding transitional filler ("It is worth noting that", "Importantly", "In this section we will see how"). - Inflating a claim, or deflating one to make it defensible. - Converting a definition into a different definition in the course of rewording it. - Reorganising a proof into a chain of lemmas, or the reverse, without routing the proposal through `deferred.md`. Both directions have distinguished advocates and both can be wrong here. - Adding the roadmap paragraph back. - Changing anything inside `verbatim`, `lstlisting`, or comment lines beginning `%`, except to report on them. - Introducing packages. - Writing any sentence not entailed by the source (invariant 8), above all inside a proof overview. ## 6. Length targets Default: the revision is not longer than the original. Report word count before and after. When asked for a trim against a page limit, target a 15 to 25 percent reduction of prose words, and stop when a further cut would require removing a claim, a hypothesis, or an inference marker. Under-editing beats meaning loss: "as short as possible" has its fixed point at the empty string, so the pass needs a floor as well as a target. If a named goal ("cut 400 words") cannot be met within the invariants, report the shortfall rather than breaking an invariant to reach it. Mandatory proof overviews are not traded away for length; if their page cost is a problem, report it and cut elsewhere. ## 7. Exit condition Stop when the passes are done. There is always another improvement available and always a better phrasing just out of reach; the only way to finish is to be ruthless about finishing [HAL§20]. Do not continue past the report into open-ended polishing. ## 8. Mechanical sweep Do this before hand-editing Passes 4, 5, and 7, and report each hit as a row in `revision-report.md`. These are mechanically detectable, so finding them by search costs nothing and leaves attention for the rules that need a reader. Expect false positives: each hit still needs judgment. Search the source, ignoring comments and `verbatim`, and allowing for line breaks inside multi-word phrases (LaTeX source wraps, so "it can be\nshown" must still match): | Search for | Rule | |---|---| | `---` or a literal em dash character | KNU-DASH | | `--` between two letters (should be a hyphen) | KNU-DASH | | `any` | HAL§14 | | obvious, obviously, clearly, evidently, trivially, straightforward, easy to see, easily seen, it is immediate, routine | HAL§10 | | iff, s.t., w.l.o.g., resp. in running prose | KNU3 | | `\forall`, `\exists`, `\implies`, `\iff`, `\Rightarrow`, `\therefore`, `\neg`, `\land`, `\lor` outside a display | KNU3 | | "we have that", "we know that" before a formula | KNU8 | | "it can/could/may be seen/shown/noted/observed/verified", "it is easily shown", "has been shown" | SPJ-VOICE | | "the rest/remainder of this paper is organised/structured" | SPJ-ROADMAP | | "It is worth noting that", "It is important to note that", "Importantly,", "In this section we will see", "Needless to say" | prohibited | | lowercase theorem/lemma/section/figure followed by a number | KNU19 | | Theorem, Lemma, Section, Figure, Table, Algorithm, Appendix followed by a space and a digit | KNU-TIE | | a letter or `)` followed by a space and `\ref`/`\eqref`/`\cref` | KNU-TIE | | the KNU21 misspelling list; `non-negative`, `non-zero`; `it's` | KNU21 | | ` which ` with no preceding comma or preposition | KNU22 | | a sentence opening with "This" or "It" plus a verb | GOL-PTR | | "without loss of generality" inside a statement environment | HAL§11 | | `$` immediately after a sentence-ending period, or opening a paragraph | KNU2 | | two `$...$` groups separated only by a comma or space | KNU1 | | `:` immediately before `\[` or `\begin{equation}` | KNU23 | | `p[r]`-style indexing or `a * b` in math | KNU-PROG | | nested scripts: `_{..._{`, or `x_i_j` | KNU15 | | `\frac` inside inline math | KNU-FRAC | | a parenthesised tuple of five or more single letters used as a modifier | GOL-NOTA | Then check whole-document state: - Duplicate `\label` keys; references to labels that do not exist. - Numbered `equation`/`align` environments with no label, and labelled displays never referenced. [KNU16] - Multiple `\newtheorem` declarations on independent counters, with no shared counter and no section numbering. [GOL-NUM] - Statement environments whose preceding text does not end in a period or colon. [KNU4] - Every `proof` over roughly 25 words whose first paragraph is not a separate overview paragraph, or whose opening paragraph is under a dozen words. [LAM-SKETCH] - Abstract word count, and any `\ref`, `\cref`, or `\cite` inside the abstract. [GOL-ABS] - A symbol inventory: every single letter and every named symbol used in math, with a count. Assign each a meaning and report collisions. [HAL§6][KNU14] ## 9. Verification checklist to append to the report - [ ] Compiles with `pdflatex`, same number of errors as before or fewer. - [ ] Every `\label` present in the original is present in the revision. - [ ] Every math span, macro name, citation key, and environment delimiter in the original appears in the revision, in the same order, except where recorded in the report. - [ ] No em dashes. - [ ] Every claim in the introduction has a forward reference to its evidence. - [ ] Abstract self-contained, no internal references, under 200 words. - [ ] Every proof opens with an overview of at most two paragraphs. - [ ] Every overview has a step map covering its sentences, a risk grade, and a gaps list. - [ ] No overview uses crux, key difficulty, main obstacle, essential idea, tight, optimal, clear, obvious, immediate, easy to see, routine, standard, or trivial. - [ ] Every gap listed in an overview appears as a question in `concerns.md`. - [ ] Every proof ends by discharging the stated goal. - [ ] Every occurrence of "obvious", "clearly", "easy to see", "straightforward" in the author's text is listed. - [ ] Every low-level definitional choice is labelled arbitrary, simplifying, or seemingly essential [GOL-CHOICE]. - [ ] Notation table has no symbol with two meanings and no meaning with two symbols. - [ ] Blah test passed on every paragraph containing displayed mathematics. - [ ] Word count reported before and after; the after is not larger. - [ ] Every edit in the report carries a rule ID. - [ ] Every claim, hypothesis, quantifier, modal qualifier, and citation in the original is present and unaltered in the revision. Check this last, in a fresh pass, listing what changed rather than asserting that nothing did. --- ## Provenance Rule identifiers map to these sources. | Prefix | Source | |---|---| | `HAL§n` | Paul R. Halmos, *How to Write Mathematics*, L'Enseignement Mathématique **16** (1970), 123-152; section numbers as in the essay. Reprinted in Steenrod, Halmos, Schiffer and Dieudonné, *How to Write Mathematics*, AMS, 1973. | | `KNUn` | Donald E. Knuth, Tracy Larrabee, Paul M. Roberts, *Mathematical Writing*, MAA Notes 14, Mathematical Association of America, 1989, ii+115 pp., ISBN 0-88385-063-X; numbered points of §1, "Notes on Technical Writing". Earlier limited-circulation version: Stanford CS report STAN-CS-88-1193, January 1988, from the autumn 1987 CS 209 course. | | `KNU-*` | Same report, later lectures (§§4-7 on student answers and book preparation). | | `SU-*` | Francis Edward Su, *Guidelines for Good Mathematical Writing*, 2011. | | `LAM-*` | Leslie Lamport, *How to Write a 21st Century Proof*; preprint dated 23 November 2011, published in *Journal of Fixed Point Theory and Applications* **11**(1) (2012), 43-63, doi:10.1007/s11784-012-0071-6. Revises *How to Write a Proof*, *American Mathematical Monthly* **102**(7) (1995), 600-608. | | `SPJ-*` | Simon Peyton Jones, *How to Write a Great Research Paper*, Microsoft Research; abstract structure attributed there to Kent Beck. | | `GOL-*` | Oded Goldreich, *How to Write a Paper*, March 2004, last revised 8 November 2015. Full text at `https://www.wisdom.weizmann.ac.il/~oded/R2/re-writing.pdf`. Revises *How NOT to Write a Paper* (1991, revised 1996). | ### Corrections to earlier versions of this table - **`KNUn` dating.** The Stanford report is STAN-CS-88-1193, dated January 1988, based on the autumn 1987 course; the MAA Notes 14 book is 1989. An earlier version gave "Stanford CS 209 report, 1989", conflating the two. - **`LAM-*` dating.** The preprint is dated 2011, the journal version 2012. Cite the journal version. - **`GOL-*` caveat withdrawn.** The canonical page is behind a robots exclusion, but the full text is served at the `R2/re-writing.pdf` path above. All `GOL-*` rules have been checked against the full essay and carry section numbers. The earlier note that `GOL-LAYER` rested on secondary description no longer applies: it is §3.2 and §4.4. - **Krantz still unrepresented.** Steven G. Krantz, *A Primer of Mathematical Writing*, 2nd ed. (2016) is a book and was not consulted. No rule depends on it. ### `GOL-*` index with sections | ID | § | Content | |---|---|---| | `GOL-IDEA` | 2 | Identify the idea the paper communicates: a model, a technique, or results. | | `GOL-AUD` | 2, 3.2 | Model reader: intelligent, basic background, no more; a good student at the start of graduate study. | | `GOL-CHECK` | 3.1 | Checklist phenomenon: everything the author knows, inserted at the first possible location. | | `GOL-GEN` | 3.1 | Obscure generality: meaningful special case first, generalise by modification of the basic ideas. | | `GOL-IDIO` | 3.1 | Idiosyncrasies: no terms or notation whose appeal is personal to the author. | | `GOL-HIER` | 3.1 | Make the distinction between important and secondary statements conspicuous. | | `GOL-TALMUD` | 3.1 | Talmud-ism: subtleties and anticipated criticisms before the basic idea is clear. | | `GOL-CONCEPTS` | 3.2 | Minimise new concepts and definitions; the reader's capacity is bounded. | | `GOL-HIDE` | 3.2 | Do not let a definition bypass a fundamental difficulty without discussing it. | | `GOL-PTR` | 3.4 | Labyrinth of implicit pointers: "it" and "this" pointing several sentences back. | | `GOL-LOGIC` | 3.4 | Sentences with nested or multiple conditions and consequences. | | `GOL-CAT` | 3.4 | Mixtures of symbols and text; remind the reader of an object's categorical status. | | `GOL-NOTA` | 3.4 | Cumbersome notation: stacked scripts, multi-parameter compounds. | | `GOL-ABS` | 4.2 | Abstract self-contained, no internal or bibliographic references, under 200 words, high-level. Need not motivate the model, recall prior work, be precise, or cover all results. | | `GOL-INTRO` | 4.3 | Introduction sketches the main results, describes the techniques, highlights novel conceptual observations. | | `GOL-MOT` | 4.3 | Motivation connects to central notions; an established question type needs none, the specific question usually does. | | `GOL-CHOICE` | 4.4 | Label each low-level definitional choice arbitrary, adopted for simplicity, or seemingly essential. | | `GOL-LAYER` | 3.2, 4.4 | Elaborate novel conceptual steps; compress standard technical ones and refer to an exposition. | | `GOL-NUM` | 4.4 | One numbering system, or double numbering by section, not a counter per element type. | | `GOL-CITE` | 4.4 | Citations carry locators: [Thm X, T], not [T]. | | `GOL-CONC` | 4.5 | Conclusions and open problems belong in the introduction; under five percent of papers benefit from a conclusion section. | | `GOL-CREDIT` | 4.6 | Truth first, then kindness. Never mislead with inaccurate credit. | | `GOL-REV` | 5 | Every reviewer comment indicates a problem in the write-up, even where the suggested fix is wrong. | | `GOL-FRIEND` | 5 | Comments from friends are weak evidence; ask explicitly for critical reading. | ## Conflict register Where two authorities disagree, or where a rule as stated is broader than the evidence supports, the resolution is recorded here rather than applied silently. An edit made under one of these entries cites both the rule ID and this register. **Active voice [SPJ-VOICE] versus topic management.** Peyton Jones' rule as stated is a blanket preference. Pullum's survey of the usage literature finds the stylistic allegations against the English passive invalid, and finds that usage writers frequently cannot distinguish actives from passives at all; Gopen and Swan locate the real problem in the placement of old and new information rather than in voice, and the passive is often the only construction that puts the previously-mentioned item in the topic position. Resolution: convert to active when the agent appears in the same clause and the active version still opens with the old information; otherwise keep the passive and record the decision. - G. K. Pullum, Fear and loathing of the English passive, *Language & Communication* **37** (2014), 60-74, doi:10.1016/j.langcom.2013.08.009. - G. D. Gopen and J. A. Swan, The science of scientific writing, *American Scientist* **78**(6) (1990), 550-558. **Short sentences versus subordination.** No source here mandates splitting compound-complex sentences, but the general drift of concision advice invites it. Biber and Gray show that academic prose is not clausally elaborated but phrasally compressed: finite dependent clauses are more frequent in conversation than in academic writing, which compresses through noun-phrase embedding. Splitting a sentence therefore moves the register towards conversation while increasing word count, and in mathematical prose it deletes the subordinating conjunctions that encode implication, scope, and hypothesis discharge. Resolution: subordination carrying logical structure is protected; only light-verb nominalisations are unpacked, not nominalisations that name objects. - D. Biber and B. Gray, Challenging stereotypes about academic writing: complexity, elaboration, explicitness, *Journal of English for Academic Purposes* **9**(1) (2010), 2-20. **Write for the early graduate student [GOL-AUD] versus expert readers.** Instructional support calibrated for novices measurably degrades comprehension for readers who already hold the relevant schemas, and for added material that engages without being load-bearing, placement before a passage does more damage than placement after it. Resolution: Goldreich's own [GOL-LAYER] settles it. Elaborate the novel conceptual content, compress the standard technical content, and prefer consolidation after formal material to motivation before it when the page budget is tight. - S. Kalyuga, P. Ayres, P. Chandler and J. Sweller, The expertise reversal effect, *Educational Psychologist* **38**(1) (2003), 23-31, doi:10.1207/S15326985EP3801_4. - S. F. Harp and R. E. Mayer, How seductive details do their damage, *Journal of Educational Psychology* **90**(3) (1998), 414-434, Experiment 4. **Proof sketches [LAM-SKETCH] versus generated summaries.** Lamport advocates a sketch between statement and proof, and this prompt requires one. But a fluent summary of a broken argument presents the break as the method, in the author's voice, at the head of the proof. Resolution: overviews are structural only, every sentence traced to proof-body lines in a step map, assessment vocabulary prohibited, unplaceable steps recorded as gaps and escalated to `concerns.md`. Lamport himself declines to structure a four-sentence proof because sophisticated readers do not need it, so a length threshold for hierarchical structure is legitimate; the overview requirement itself is not thresholded unless the author sets one. **Hierarchical proofs [LAM-LEVELS] versus lemma extraction [HAL§12].** Both directions have distinguished advocates. Neither is applied unilaterally; both go to `deferred.md`.