docs(newsletter): record the multi-paragraph section shape in the style guide - #161
Conversation
…le guide The style guide told agents that a newsletter article section is "One paragraph. No bullets, no sub-headings, no block quotes", which stopped being true four issues ago. It was mined from issues 359-398, and that window is entirely the single-block era, so a regeneration could not have caught the change on its own. Measured across 399-404: 9 of 30 sections are a single paragraph and every one of those sits in 399 or 401. Issue 400 broke sections into 5-8 paragraphs once, and from 402 on it is consistent at 4-7 paragraphs with a median of 5. The median paragraph is a single sentence, two is normal, three is the upper end and four is the most anywhere in the corpus. Lists inside a section went from banned to rare-but-allowed: 1 section in 30, the 6 principles in issue 402. Adds a Paragraphing subsection carrying those numbers and the rhythm they imply, with the lede taking its own paragraph and the editorial beat closing on its own. The existing word, sentence and comma table is left alone because it measures the whole section and does not change with how the section is broken up. Also warns at the top of the file that this one subsection is mined from a different, newer window than the rest, so a regeneration that widens the window back to 40 issues will dilute it rather than confirm it. Claude-Session: https://claude.ai/code/session_011jP6p4zSaZncEXPdqiLg57
Issue 405 opened two sections on a bare one-line reaction ("This one is a
genuinely new kind of model!") and the owner rewrote both. Nothing in
either guide forbade it, because the failure only became possible once
sections started being broken into short paragraphs: in the single-block
era an exclamation lede was followed by a comma and the news, so it could
never strand on its own.
voice.instructions.md gains a rule under "No superfluous text": a
paragraph whose whole job is a reaction states an opinion the reader
cannot check and carries no fact, so it is folded into the sentence with
the news or cut. It applies to blog posts too, which is why it sits in the
shared core rather than only in the newsletter guide.
style.md spells out the newsletter-specific half, which is that the
existing "then continue normally" for the 42% of non-colon ledes means in
the same paragraph. A colon lede is the exception and is meant to sit
alone, because the colon hands over to the paragraph beneath it; an
exclamation or question lede has nothing to hand over with, so it has to
carry its own news. Includes the before and after from 405 and the owner's
own rewrite of the t0-beta opener as the worked example.
Claude-Session: https://claude.ai/code/session_011jP6p4zSaZncEXPdqiLg57
|
Added a second commit covering the related failure you caught in 405. The gap: two sections opened on a bare one-line reaction ("This one is a genuinely new kind of model!") and you rewrote both. Neither guide forbade it, because the failure only became possible once sections started being broken into short paragraphs. In the single-block era an exclamation lede was followed by a comma and the news on the same line, so it could never strand.
This makes the PR two related fixes to the same root cause: the section shape changed at issue 402 and the guidance never caught up. |
1 participant
What
The newsletter style guide told agents that an article section is "One paragraph. No bullets, no sub-headings, no block quotes inside an article section". That stopped being true four issues ago, and I only caught it because you spotted that issue 405 did not read like the recent editions.
Why it went stale
references/style.mdis mined from issues 359-398. That window is entirely the single-block era, so no regeneration of the existing window could ever have surfaced the change.The measurements
Across issues 399-404 (30 sections):
Issue 400 had already broken sections into 5-8 paragraphs once before it settled from 402 on.
The change
Adds a
Paragraphingsubsection underShape of one article sectioncarrying those numbers and the rhythm behind them: the lede takes its own paragraph and its colon hands over to the paragraph beneath, each supporting point gets its own line, and the editorial beat closes on its own. Lists move from banned to rare-but-allowed.The existing word, sentence, comma and link table is untouched: it measures the whole section and is unaffected by how the section is broken up.
Also adds a warning at the top of the file that this one subsection is mined from a newer window than the rest, so
--issues 40will dilute it rather than confirm it, and it should be re-checked against the newest three issues instead.Testing
Documentation only, no code paths touched.
npx prettier --writeapplied to the edited file.https://claude.ai/code/session_011jP6p4zSaZncEXPdqiLg57