Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions .claude/skills/newsletter-issue/references/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ This file is the newsletter's own structure and register, which the shared core

Mined from issues 359-398 (198 article sections) by `scripts/newsletter/style-corpus.mjs`. Regenerate with `node scripts/newsletter/style-corpus.mjs --issues 40` and re-curate this file when the voice drifts.

The paragraphing guidance below is the exception: it is mined from 399-404, because the section shape changed after the window the rest of this file covers. A regeneration that widens the window will dilute it, so re-check it against the newest three issues rather than letting the mined numbers overwrite it.

Keep the window at 40 issues. Over the full 398-issue archive the colon-lede rate falls from 58% to 27% and the median section halves from 158 to 70 words: the current voice is recent, and mining the whole archive teaches the wrong one.

## Shape of one article section
Expand All @@ -17,10 +19,25 @@ Keep the window at 40 issues. Over the full 398-issue archive the colon-lede rat
| Commas | 9 | 17 | 0-27 |
| Links inside the prose | 0 | 1 | 0-3 |

One paragraph. No bullets, no sub-headings, no block quotes inside an article section. The link lives in the heading, so the prose usually carries none: name the source in words instead of linking it again.

Per issue: 5 sections, 789 words and 29 sentences of article prose in total.

### Paragraphing: short paragraphs, not one block

**A section is several short paragraphs separated by blank lines, not a single block of prose.** The word and sentence counts above are for the whole section and are unaffected by how it is broken up.

| Measure | Median | Range |
| ----------------------- | ------ | ----- |
| Paragraphs per section | 5 | 4-7 |
| Sentences per paragraph | 1 | 1-4 |

This is a recent change and the table above is mined from a window that predates it, so do not trust the older sections for this one thing. Issues up to 399 are almost all single-block: 9 of the 30 sections across 399-404 are one paragraph, and every one of those sits in 399 and 401. From 402 on it is consistent, and 400 had already done it once.

The rhythm is one thought per paragraph. The lede takes its own paragraph and the colon hands over to the paragraph beneath it, each supporting point gets its own line, and the editorial beat closes on its own. A paragraph carrying two sentences is normal, three is the upper end, and four is the most in the corpus.

A numbered or bulleted list inside a section is rare but allowed: 1 section in 30, the 6 principles in issue 402. Use one only where the source really is a list. No sub-headings and no block quotes inside an article section.

The link lives in the heading, so the prose usually carries none: name the source in words instead of linking it again.

## The lede

58% of sections open with a scene-setting first sentence that ends in a colon, then the detail follows. This is the single strongest structural tell of the voice.
Expand All @@ -33,6 +50,28 @@ The blog bans mid-prose apposition after a colon ("The rule is simple: ..."), wh

> Last week OpenAI published about their rouge hacking HuggingFace, this week HF published a super detailed forensic reconstruction and it's insane:

### The lede is never a stranded one-liner

**"then continue normally" means in the same paragraph.** Now that sections are broken into short paragraphs, an exclamation or question lede left alone on its own line becomes a paragraph that carries no information, and the owner rewrites those on sight.

```
This one is a genuinely new kind of model!

Diogo Almeida, who was at OpenAI and is one of the co-inventors of RLHF, launched Jev, ...
```

The first line says nothing a reader could not have guessed from the heading. Fold the reaction into the news, or drop it and open on the news:

```
Structured outputs are what everyone wires around when putting an LLM inside software, and this week someone shipped a model that does nothing else. Diogo Almeida, who was at OpenAI and is one of the co-inventors of RLHF, launched Jev, ...
```

The owner's own rewrite in issue 405 shows the shape: a claim about where the field is, then the actor and the release, in one paragraph.

> Forecasting foundation models are taking over, with a new top model from Europe this week 🇪🇺🚀🇫🇷 The Forecasting Company released an Open 256 million parameter time series foundation model and it's going for the top 3 best in performance.

A colon lede is the exception and is meant to sit alone, because its colon hands over to the paragraph beneath it. An exclamation or question lede has nothing to hand over with, so it carries its own news or it is not a lede.

The other 42% open on a short exclamation or a question, then continue normally:

> Europe is on Fire with another Foundation Model!
Expand Down
1 change: 1 addition & 0 deletions .github/instructions/voice.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Every sentence must add knowledge; a sentence that only emphasises or restates t
- No bullet list that elaborates the benefits of a point already made in prose.
- No justification sentence appended after a stated practice ("We put the machine on format checking because it does that job better..."). State the practice; the reader can infer why.
- One example or consequence where the draft piles up three ("how software gets built, how research gets summarised and how decisions get drafted" became "how software gets built").
- No paragraph whose whole job is a reaction. A standalone line like "This one is a genuinely new kind of model!" or "Huge if true!" states an opinion the reader cannot check and adds no fact, and it reads as filler wherever it sits. Fold the reaction into the sentence carrying the news, or cut it. This bites hardest at the start of a section, where an opener is meant to tell the reader what happened.
- No trailing amplifier clause ("...without being rewritten for either", "...and the risk goes away") and no closing sentence that repeats the section's point.
- Added words must carry new facts, motive or a concrete example ("as we don't aim for this to be a complete list of skills, but a curated list").

Expand Down
Loading