manuscript-prose-style

Files (1)

• SKILL.md

SKILL.md (first lines)

# Manuscript Prose Style (research papers, supplements, technical notes)

Use this skill when drafting or editing the prose of a research paper, supplement or technical note in the FLARE, PFR or Voltivity projects, or when the user mentions a language pass, a register pass, Americanization, heading sweep, de-AI-ing, or removing machine-generation tells.

This is the prose counterpart to `aps-figure-style`, `nature-figure-style` and `science-figure-style`. Those govern what a figure looks like; this governs what the text looks like. It exists because three failures kept reaching the author by hand: British spelling, conversational headings, and machine-generation tells.

## Key Conventions

| rule | why |
|---|---|
| American English, always, unless the venue says otherwise | The destination governs, not the sources |
| Headings are noun phrases — never sentences, questions or asides | Journal register |
| Zero invisible characters, zero Unicode punctuation substitutes | Most identifying artifact there is; invisible on the page |
| Paragraphs develop an argument; they do not state and stop | The tell that survives every surface cleanup |
| `\SI`, `\label`, `\cite`, `\ref` multisets unchanged after any prose edit | A language pass that moves a number has broken something |

---

## 1. Language: American English

**American English is the default for every document in these projects.** The
cause of the recurring error is worth naming, because it will recur otherwise:
the surrounding literature is British. A&A and MNRAS house style is British, and
*fibre* dominates the astrophotonics corpus — one FLARE note converted *fibre* →
*fiber* 127 times. An agent that matches the register of the papers it is citing
instead of the register of the venue it is writing for produces a British draft
every time. **Match the destination, not the corpus.**

### 1.1 Exceptions that keep their source spelling

| exception | example |
|---|---|
| Quoted material | A direct quotation is reproduced as its source wrote it |
| Published titles in a bibliography | *Coupling starlight into single-mode fibre optics* stays as published. A bibliography entry is a quotation of a title |
| Proper nouns, institutions, programme names | The *Centre* National d'Études Spatiales |
| Vendor product names | A catalogue part named *Fibre Coupler X* keeps the vendor's spelling |
| **Venue house style** | Nature family prints *Acknowledgements*; APS prints *Acknowledgments*. Two versions of one paper aimed at different venues legitimately differ on that word |

Venue house style **overrides the default**. Check the target venue before
sweeping, and record the decision — the same manuscript submitted to two venues
will not agree with itself, and that is correct.

### 1.2 The siunitx trap

`\metre` is a macro name. It is code, not prose, and converting it produces a
document that does not compile. The scale of the trap, measured on one FLARE
note: of **656 `metre` tokens, 652 were `\metre`** and 4 were the English word.
A naive `s/metre/meter/g` breaks 652 unit macros to fix 4 words.

The same applies to `\centering`, `\color`, `\itemize`, `\definecolor{oiGrey}`,
and every other control sequence and key that happens to contain a British
string.

### 1.3 Safe conversion order

Mask first, substitute second. Mask, in this order:

1. `\begin{thebibliography}…\end{thebibliography}` — published titles
2. siunitx calls (`\SI`, `\SIrange`, `\SIlist`, `\num`, `\numrange`, `\si`, `\ang`, `\qty`) **with every brace group**
3. Every remaining control sequence `\[A-Za-z]+` — catches standalone `\metre`
4. `\label{}`, `\cite{}`, `\ref{}`, `\includegraphics{}`, `\definecolor{}`, `\newcommand{}` and their arguments
5. Inline and display math
6. Comments

**Blank comments before pairing math.** A single `$` inside a comment
desynchronizes `$…$` pairing and silently masks the rest of the file. That defect
was live in the FLARE tool and suppressed 287 candidate words in one document
until it was found.

Words that only *look* British and are correct American English: *advertise*,
*compromise*, *promise*, *exercise*, *precise*, *otherwise*, *pairwise*,
*likewise*, *contour*, *cancellation*, *percentage*.

Reference implementation:
`FLARE/docs/notes/coupling_trades/reports/anglicise_to_american.py` — a
protection-aware substitution over a 210-form table that reports every masked hit
with its line number and reason. Generalize it; do not start a second one.

---

## 2. Headings

`\section`, `\subsection` and run-in `\paragraph{}` headings are **noun phrases**.

A heading may not:

- be a sentence, or carry a finite verb making an assertion
- pose a question
- comment on its own content ("Shape accuracy, and what the vendor figure means.")
- promise a payoff ("Why this matters.")
- read conversationally
- be content-free ("The correction.") — replace it with what the paragraph is about

Where a heading carries a label — `G1:`, `D3:`, `A6:` — **the label stays** and
what follows it is a noun phrase. Punctuation is uniform across a labelled
series: `<label>: <lowercase noun phrase>.`

Real conversions, from the FLARE long note:

| before | after |
|---|---|
| The photonic lantern does not beat étendue. | Étendue cost of the photonic lantern. |
| Three requirements together exclude multicore fiber. | Three concurrent draw requirements on a multicore feed. |
| Tool throughput is not the constraint. | Tool throughput for the production run. |
| Registration accuracy is published by four platforms and delivered by one. | Detection accuracy against delivered placement across the platforms. |
| The height constraint is a property of the process rather than of one machine. | The writable-height limit as a process property. |
| Shrinkage compensation does not close the gap, and the reason is that the part is anchored. | Limits of shrinkage compensation on an anchored part. |

Where a heading carried a claim, the claim is not lost — the body text already
states it. Verify that before deleting it from the heading.

---

## 3. Machine-generation tells

Four layers, each checkable. Run them in order; each is cheaper than the next.

### 3.1 Invisible characters

The most identifying artifact there is, and invisible on the page. Zero

From ricfulop/cba-agentic-engineering-bootstrap, MIT.

More from ricfulop/cba-agentic-engineering-bootstrap