English Writing

English Writing

Revise and draft English documents so that structure carries the meaning.

Execution protocol

Seven gates, in order. A gate may not begin until the previous one is finished. Gates 2 through 5 each rewrite the whole document at one level; do not fix a sentence while you are still moving paragraphs, because the sentence may not survive the move.

1. Inventory. Read the whole document. For each paragraph, name what it is actually about, which may differ from what its first sentence currently says.

2. Structure. Write or rewrite every topic sentence. Reorder paragraphs. Split the ones over the cap. Merge fragments.

3. Chains. Inside each paragraph, reorder sentences so each stands in a parallel, contrast, or consequence relation to the last. Cut the ones that belong nowhere.

4. Sentences. Split long sentences, remove nominalizations, convert passives whose actor matters, replace elaborate words, and leave every term of art alone.

5. Surface. Headings, numbered lists, captions, notes, cross-references, APA form. Renumber anything that moved.

6. Machine check. Write the draft to a file and run it through the checker:

   python scripts/check_draft.py draft.md
   

   Fix every line under FAIL and rerun until FAIL reports zero. Read every line under REVIEW and either fix it or keep it on purpose. This gate is not optional and reading the draft yourself does not replace it, because a program catches the mechanical errors you are least likely to notice in your own output. If the script cannot run, say so in one line and list which of its checks you performed by hand.

7. Judgment check. The checker prints the topic sentence extraction but cannot judge it. Do that yourself, along with the rest of the list in Judgment check.

Deliver only after gate 7. The script run is your evidence that the gates happened, so do not narrate the protocol in your reply.

Output

Return the revised or drafted text directly, ready to paste. No preamble, no list of changes, no explanation of your reasoning. If something genuinely cannot be resolved without the user, put a single bracketed note inline at that spot and keep going. Write those inline notes in whatever language the user is speaking.

Markdown is the default format. Produce a Word file only when the user asks for one, and then follow the Word format specification below exactly.

Minimal intervention

Change what violates the standard. Leave everything else alone.

A sentence that is already short, already in the right place, and already carries its relation to its neighbors is finished, even if you would have phrased it differently. The user's wording is the default and yours is the exception.

Preserve exactly

Reproduce these character for character, in revisions and in drafts from source material:

• Every number, unit, percentage, date, and currency amount
• Every citation, in-text citation marker, and reference list entry
• Every direct quotation and anything inside quotation marks
• Every proper noun, product name, team name, dataset name, and person's name
• Every defined term, including its capitalization

If a number or a citation looks wrong, leave it as it is and flag it in a bracketed inline note. Never correct it, round it, or convert its units on your own initiative.

Citations are the one exception to preserving form. The document uses APA, so put in-text citations into author-date form and format reference entries to APA style, while keeping every author name, year, title, and identifier exactly as the user supplied them. See the APA section below.

The standard

1. The topic sentence carries the paragraph

The first sentence of every paragraph states that paragraph's core point. A reader who reads only the first sentences must understand the whole document.

• The first sentence is a claim or a statement of fact, not a setup line. "Three factors drove the cost increase." is a topic sentence. "This section discusses cost." is not.
• Never open a paragraph with background, a bare transition, a question, or a data point whose significance only arrives later.
• Consecutive topic sentences must connect. Read them in sequence and the document's logic should be visible: either the argument advances, or the parts of a whole are enumerated in order. If two adjacent topic sentences have no relationship, the paragraphs are in the wrong order or a paragraph is missing between them.

2. Short sentences, varied length

Default to short. Mix in a longer sentence so the rhythm does not turn choppy, but never two long sentences in a row.

• Most sentences under 20 words. One subject, one main verb.
• No nested subordinate clauses. Split instead.
• Plain vocabulary over elaborate vocabulary: use, not utilize; because, not owing to the fact that; show, not demonstrate, unless demonstrate is the precise word.
• Prefer verbs to nominalizations. "We decided" beats "a decision was made"; "this improves accuracy" beats "this results in an improvement in accuracy".

Short does not mean thin. Simple structure is the goal, not less content. Splitting a sentence redistributes its information across several sentences; it never discards any. Qualifying conditions, reasons, scope limits, and the basis for a claim all stay in, because dropping them is what makes a document unclear in the first place.

A sentence stripped to bare subject-verb-object usually leaves the reader asking why. Explaining takes the sentences it takes.

• Too thin: "We normalized the scores. Rankings changed. The method works." The reader learns nothing about why any of this happened.
• Right: "We normalized the scores within each category before blending them. Rankings changed most in Electronics, where the raw score range was widest. Normalization removes the scale difference, so the blended score now reflects relative quality rather than category size."

Aim at the second version. Its sentences are longer than the first version's and still easy to read, because each carries one idea in a simple structure.

• Technical terms are never simplified. Domain vocabulary, method names, metric names, and defined terms stay exactly as written. Turning normalization into scaling, or logistic regression into a prediction model, destroys the meaning. When a word looks unnecessarily complex, check whether it is a term of art before touching it. If unsure, leave it.

3. Sentences inside a paragraph form a chain

Every sentence after the first stands in a clear relation to what came before: parallel, contrast, or consequence.

• Parallel: adds another item of the same kind.
• Contrast: qualifies or opposes.
• Consequence: follows from, explains, or concludes.

The relation must be recoverable from the content itself. Add a connective (however, so, also) only when the relation would otherwise be ambiguous. A paragraph where every sentence opens with Moreover, Furthermore, Additionally reads worse than one with no connectives at all.

A sentence that bears no relation to those around it belongs in another paragraph or should be cut.

4. Paragraph length cap

Five sentences and seven lines are the ceiling. A paragraph over that limit is doing two jobs. Split it and give each half its own topic sentence.

There is no minimum. A one-sentence or two-sentence paragraph is correct when the point is genuinely that small. Never pad a paragraph to reach a sentence count, which would violate rule 10.

Line count depends on a page width you cannot see, so use 110 words as the working proxy for the seven-line ceiling. When the document already contains paragraphs that the user is happy with, use the longest of those as the reference instead.

5. Headings

Every document has a structure of numbered sections. The document title carries no number. Every heading below it is numbered as 1, then 1.1, then 1.1.1, and no deeper. In Markdown, the title is #, section 1 is ##, section 1.1 is ###, and section 1.1.1 is ####, with the number written into the heading text.

# Seller Quality Score Normalization
## 1 Introduction
## 2 Method
### 2.1 Data
### 2.2 Normalization procedure
#### 2.2.1 Within-category scaling

Where the document's conventions allow it, a heading follows the same rule as a topic sentence: it states a finding, not a topic. "Cost rose 12% in Q3" beats "Cost analysis". When an assignment template or a house style fixes the heading names, keep them exactly as given.

A section never contains a single subsection. If 2.1 exists, 2.2 must exist too, or the content belongs directly under 2.

A heading never substitutes for a topic sentence. The first paragraph under a heading opens with its own claim and reads correctly with the heading removed. A paragraph that begins "This was driven by three factors" and depends on the heading to say what "this" refers to has failed rule 1.

6. Lists

Use a list only for three or more genuinely parallel items. Two items belong in a sentence. Reasoning belongs in prose, because a chain of logic loses its connectives the moment it is broken into bullets.

Mark enumerated points within a section as (1), (2), (3), not as bullets. Run them inline when each item is short, and put them on separate lines when an item runs longer than a line. Either way the marker form stays the same.

• Introduce every list with a lead-in sentence that does the topic sentence's job for the whole list.
• Make the items grammatically parallel: all noun phrases, or all starting with a verb, never a mixture.
• Keep punctuation consistent. Fragments take no terminal period, full sentences take one, and the two styles do not mix within one list.

7. Figures and tables

Caption every figure as Picture 1. <caption> and every table as Table 1. <caption>, numbered sequentially through the document, with separate counters for pictures and tables.

• The caption states what the reader should see, not just what the object is. "Picture 3. Error rate falls sharply after week 4" beats "Picture 3. Error rate over time".
• Reference every figure and table by name in the body text before it appears: "Picture 2 shows the distribution of...".
• Keep whatever caption position the document already uses. If there is none, put picture captions below and table captions above.

Add a note when the reader needs something to read the object that the object does not show on its own: the data source, the sample size, an abbreviation or symbol used in it, what was excluded, or the conclusion it supports. Write it as Note. <text>, italicizing Note., on its own line below everything else belonging to that figure or table.

• Useful: Note. Scores are normalized within category. Sellers with fewer than 10 orders are excluded. The gap between categories closes after normalization.
• Not useful: Note. This table shows seller scores by category. The caption already said that.

One note per object. A note that restates the caption or narrates what is visually obvious should be cut.

8. Voice and punctuation

Prefer active voice. Active voice shortens sentences and names who did what, which is what rules 2 and 10 are after. Use passive only when the actor is unknown, genuinely irrelevant, or when the sentence's real subject is the thing acted on.

• Fine: "The data were collected in March." The collector does not matter.
• Fix: "It was found by the team that errors increased." becomes "The team found that errors increased."
• Fix: "A normalization step was applied to the scores." becomes "We normalized the scores." or "Normalization removed the scale difference."

No em-dashes or en-dashes as punctuation. Use a period for a full stop, a comma for a pause, and a colon to introduce. En-dashes in number ranges and hyphens in compound words are unaffected.

Reduce parentheses. A parenthetical aside usually means the writer could not decide whether the content belongs. Decide: either cut it, or promote it to its own sentence.

These parentheses are not asides and stay: APA in-text citations, units, statistical values, first-use definitions of an abbreviation, and figure or table cross-references.

• Fix: "The model improved accuracy (which had been a problem since launch) by 4 points." becomes "The model improved accuracy by 4 points. Accuracy had been a problem since launch."
• Keep: "Accuracy rose 4 points (Yin, 2026)." and "Latency fell to 300 ms (p < .01)."

9. Tie back to the scenario

A document written for a scenario, a case, a client, or a business question must return to it. Technical passages drift: after enough method and data, the reader has lost why any of it matters.

Return to the scenario at the end of a section, or in the opening sentence of the paragraph that follows a technical stretch. The trigger is concrete: when three or more consecutive paragraphs contain only method, data, or detail with no statement of what it means for the scenario, the reader is overdue for one.

Name the specific consequence. A callback that could have been written without reading the analysis is padding and violates rule 10.

• Fix: "This has important implications for the business." That sentence fits any analysis ever written.
• Use: "This makes seller rankings unstable across categories, so a seller penalized in Electronics may be rewarded for the same behavior in Books."

Do not do this in every paragraph. Once per section is usually right, and a short document may need it only at the end.

10. Clarity first

When goals conflict, rank them in this order: the content is understood, the logic is visible, the prose is concise, the prose is elegant. Elegance never wins.

Cut anything that carries no meaning: throat-clearing openers, restatements of what was just said, hedges (I think, it seems, perhaps, to some extent), and empty intensifiers (very, quite, significantly with no number behind it).

APA citations

Format citations and the reference list in APA 7th edition. Never invent a source, an author, a year, or a DOI. When a detail is missing from what the user supplied, leave a bracketed inline note at that entry.

In text. Author-date. Use the parenthetical form by default and the narrative form when the author is the subject of your sentence.

• Parenthetical: (Yin, 2026). Two authors: (Yin & Xie, 2026). Three or more: (Yin et al., 2026) from the first citation onward.
• Narrative: Yin (2026) found that... Two authors: Yin and Xie (2026) found that...
• Use & inside parentheses and and in running text.
• Direct quotation adds a page or paragraph: (Yin, 2026, p. 14).
• Several sources in one parenthesis are alphabetical, separated by semicolons: (Chen, 2024; Yin, 2026).

Reference list. Alphabetical by first author's surname, hanging indent, one entry per source.

• Journal article: Yin, M. (2026). Title of the article in sentence case. Journal Name, 12(3), 45 to 67. https://doi.org/10.xxxx/xxxxx
• Book: Yin, M. (2026). Title of the book in sentence case (2nd ed.). Publisher.
• Chapter: Yin, M. (2026). Chapter title. In A. Editor (Ed.), Book title (pp. 45 to 67). Publisher.
• Web page: Yin, M. (2026, March 14). Page title. Site Name. https://example.com/page
• Article titles are sentence case. Journal names and volume numbers are italicized. Issue numbers are not.
• Give a DOI as a full https://doi.org/ link. Use a URL only when no DOI exists.
• Every in-text citation appears in the reference list, and every reference entry is cited in the text. Flag any mismatch inline rather than deleting or adding an entry.

Word output

Markdown is the default. When the user asks for a Word file, read references/word-format.md for the full specification and build the file with scripts/build_docx.py:

python scripts/build_docx.py document.md -o document.docx

The script applies every rule in the specification: fonts and sizes, single line spacing with 6 pt before and after each paragraph, Moderate margins, a right-aligned page number, full-width three-line tables with content-proportional columns, and centered figures at a uniform width. Do not hand-build the docx when the script can do it.

Read the specification file when the user's requirements differ from the default, when the script's output needs checking, or when a document needs something the script does not handle.

Judgment check

Gate 6 covers paragraph length, sentence length, heading numbering, bullets, caption numbering and cross-references, em-dashes, stray parentheses, and citation matching. Do not re-check those by hand. Check these, which no program can judge:

1. Read the extraction the checker printed as a standalone passage. Does it convey the argument on its own? Does each line connect to the next? A line that reads as a fragment, a setup line, or a non sequitur means that paragraph needs a new topic sentence. Fix it and rerun gate 6.
2. Any sentence stripped so far that the reader cannot tell why it matters? Put the reason back.
3. Any term of art replaced with a simpler word? Restore it.
4. Every number and quotation identical to the source?
5. Any already-compliant sentence you rewrote for taste rather than for a rule? Restore the user's version.
6. Each REVIEW passive: does the actor matter? If so, make it active.
7. Any figure or table that needs a Note. and lacks one, or carries a note that only repeats the caption?
8. Any run of three or more technical paragraphs with no callback to the scenario?
9. Any sentence removable without losing meaning?
10. In a Word file: tables at full text width with three rules and no vertical lines, figures centered at one uniform width.

When the user supplies a single paragraph rather than a whole document, run gates 3, 4, and 7, and rewrite the opening sentence so it carries the paragraph. Skip the extraction, which needs the full document. Do not invent the surrounding context.

Drafting from source material

When the user supplies notes, papers, data, or slides and asks for a draft:

• Plan the topic sentences first, as a list, before writing a single paragraph. That list is the skeleton and it must read coherently on its own. Then expand each one into a paragraph.
• Keep every claim traceable to the supplied material. Do not add facts, figures, or citations that are not in the source.
• When the material is thin on a point the structure needs, write the topic sentence and mark the gap inline rather than inventing content.
• Preserve the source's terminology exactly. If two sources use different terms for the same thing, pick one, use it throughout, and note the choice inline once.

Example

Before:

In recent years, with the rapid development of e-commerce platforms, there has been a growing amount of attention paid to the issue of seller quality, and it is worth mentioning that various different metrics have been proposed by researchers in order to measure it, although these metrics often produce inconsistent results when they are applied to the same set of sellers, which is a problem that this paper attempts to address by proposing a normalization approach.

After:

Existing seller quality metrics disagree with each other on the same sellers. Researchers have proposed several metrics to measure quality on e-commerce platforms. Applied to one seller set, these metrics rank sellers differently. The disagreement comes from differences in scale, not differences in judgment. This paper addresses it with a normalization approach.

One 70-word sentence became five short ones, the topic sentence states the problem instead of setting the scene, each sentence follows from the last, and the term of art normalization survived untouched.