Contents
The order was already fineSame paragraph length, different densityI gave it the authority to cutWhat the reader test pointed to was the titleWhat's leftReferencesIn the previous post I wrote about fixing the polishing skill that edits my sentences. After sentences came structure. I built one more skill with the agent, this one for diagnosing the skeleton of a post. It writes down what each paragraph says to build a reverse outline, and it measures how far into the body the post's main claim first appears. It also checks whether each section picks up the reader's question from the one before. I ran it on 15 published posts and restructured 11 of them.
When I reread the restructured posts, not much had changed. They were still hard to read and needlessly detailed, and the substance didn't come through. I had fixed the order, so why were they still hard to read?
Here is the answer I reached after measuring again. The posts were hard to read because of density, not order. So I added two things to the skill: the authority to cut paragraphs, and a reader with no context who reads the post for the first time.
The order was already fine
The first version of the skill only moved paragraphs and changed headings. The rule was to move each paragraph whole, word for word, and cut nothing. The point of the rule was to keep the facts, numbers and quotes that stayed from changing. I gathered up the verdicts this skill gave the 15 posts.
The first version's verdicts. Of the 11 posts I restructured, 10 only got their headings tidied.
The only post where the skill said paragraphs actually had to move was the Polyglot post. For the other 10, it grouped small sections into a few large ones and pushed the original headings down a level. Even the 4K post about upscaling only had its ten top-level headings grouped into four questions; the paragraphs mostly stayed where they were. The diagnosis reports say again and again that the flow of questions is already in place. The reason most often given for a minor verdict was that there were too many question sections. Almost no report took issue with the order the paragraphs came in.
I thought I had restructured the posts, but what actually changed was the layering of the headings. The diagnosis said the order was fine and I still felt the posts were hard to read, so the problem lay outside the order.
Same paragraph length, different density
So I took two pieces I usually find easy to read and measured them the same way as posts on this blog. One is a Yozm IT interview, the episode with Linegames technical director Lee Do-haeng, and the other is sonanlee.com's review of the book Readable Code. The posts from this blog I compared were the Polyglot post and the 4K post as the first version of the skill had left them. I dropped the sites' headers and footers and counted only the body text, without spaces.
At first I guessed the posts were hard to read because the paragraphs were long. The median paragraph length was 162 characters for the Polyglot post, 160 for the 4K post and 136 for the interview. Only the short review was at 84; the other three were about the same. This wasn't a problem that splitting paragraphs would solve.
The big gap was in English words and numbers per thousand characters. For English words, my two posts had 19.3 and 24.4, while the interview and the review had 4.2 and 0.7. For numbers, the 4K post had 25.3, more than nine times the interview. My two posts also had 20 and 46 external links in the body, and the two examples had none.
Paragraph lengths are similar; density differs several times over.
As I see it, every English word and every number is a request to the reader to remember something. In the 4K post, product names, versions and sources came one after another inside a single paragraph. Even at the same paragraph length, there was several times as much to hold on to, so the same length read as longer. I think my inability to let go of sources I found during research played a part too. The 4K post's cut list had several paragraphs introducing sources with three or more links each. They were the result of keeping a sentence in the body for each piece of material I had found and didn't want to waste.
The number of threads to follow differed too. The interview follows a single thread, the story of how one person became a leader, and roughly every 390 characters a Q. asks the reader's question for them. With questions showing up that often, there's no chance to lose track of what you're reading an answer to. The review ends with one claim, one anecdote and one line from the book. In the Polyglot post, the main claim first appeared only about three quarters of the way into the body. It used six metaphors borrowed from translation and language, and three of them backed a single claim.
In Writing, Briefly, Paul Graham advises that if you have to start before you've thought of the first sentence, you should say the most important sentence first. My post put that sentence at the back and filled the front with names and numbers. A skill that changes the order could pull that sentence forward, but it couldn't reduce the amount that filled the front.
I gave it the authority to cut
The second version of the skill cuts before it moves, and trims after it moves. First it labels each paragraph with one of five tags. A paragraph that carries a section's question or answer is 'core'. The strongest piece of evidence for a claim is 'evidence-1', and every further piece of evidence for the same claim is 'evidence+'. Among pieces of evidence, the strongest is the one that resolves the exact point the reader would doubt. After that come a concrete scene, a demo or figure I made myself, and a primary source, in that order. A number attached to something doesn't make it strong evidence. A paragraph that doesn't hang on any question is a 'tangent'. A paragraph where the post announces its own order or repeats what came before is 'preview/restatement'.
Evidence+, tangents and preview/restatements are the cut candidates. The agent puts out a list that gives each candidate a number, a proposed action and a reason. The 4K post's list had lines like these.
K14 · ¶65-66 (+timeline.svg) · tangent · 12-year timeline · proposal: delete · reason: 80% of the section is tangent
K22 · ¶75 · evidence-1→¶78 · spec upscaling assumes (Remnant 2) · proposal: keep, move to ending · reason: evidence-1 (not cut)Some lines proposed keeping a paragraph even though it was evidence+. The agent proposed keeping the 4K post's shader example because it's the only place where reprojection, clamping and accumulation come together. I answer with numbers, like keep 3,7 / rest as proposed. I took this from the procedure in anthropics/skills' doc-coauthoring, which numbers candidate points so the user can pick. Cutting loses information, so I decide what to throw away and the agent supplies the candidates and the reasons.
The paragraphs left after cutting get trimmed section by section to a detail budget. For an essay, one section gets one or two key numbers, one example, one quote that borrows someone else's name, and one metaphor per claim. The agent shows the original and the trimmed version as a pair, and trimming only removes. The words that stay must match the original, and no new sentence fills the gap. Here is how the 4K post's resolution paragraph shrank.
Original: Resolution grows by multiplying width and height. 1080p is 2,073,600 pixels, 1440p is 3,686,400
and 4K is 8,294,400. Taking 1080p as the baseline, 1440p is 1.78 times as many pixels and
4K exactly 4 times. Going from 1440p to 4K alone multiplies the pixels by 2.25.
Compressed: Resolution grows by multiplying width and height. Taking 1080p as the baseline, 4K is exactly
4 times as many pixels.What came out were three pixel counts and two ratios. They restate the same cost in other units, so the single 4x carries the claim. Of the numbers removed, the three pixel counts and the 1.78 are still in that paragraph's figure. In Writing Well, Julian Shapiro treats succinctness not as length but as the share of significant thoughts among all the thoughts communicated. The detail budget is a rule that turns that principle into something you can count, section by section.
The last step is a comparison. Two subagents with no context each pull the claims, one by one, out of the original and the new version, and another subagent compares the two lists. Every claim found only in the original has to match a cut or trim number I approved. If a claim without a number has gone missing, it counts as an error and goes back in.
The 4K post shrank to under half. Most of it went in the cuts.
The 4K post, which shrank the most, went from 11,722 characters to 5,689. Paragraphs on the timeline, console news, frame generation and controversies came out as tangents. So did the closing summary section that repeated earlier points item by item. Cuts alone left close to 61% of the original, and compression trimmed a little more from the remaining paragraphs. The SHA-256 post, the agent-skill comparison post and the AI watermark post also came down to about half of their original length. Posts with few tangents kept around 80 to 90%.
For posts that went below half, I checked once more: that no evidence-1 had been cut, that every step explaining the mechanism was still there, and that the premises and definitions of the remaining claims had stayed. In the 4K post, all six steps of the mechanism were still there, paragraph for paragraph.
On the review page, I accepted every item on the cut and compression lists as proposed. The first version had only rearranged the same amount into a different order because the skill had no authority to cut.
What the reader test pointed to was the title
Whether a shortened post really reads better shouldn't be judged by the side that edited it. As the previous post showed, language models are generous toward their own writing. So I gave a subagent with no context a single post and had it write the main point in one sentence as a first-time reader. I also had it note what question each section answers and where it got lost. Another subagent, without knowing which one was the new version, scored how close that sentence was to the main point I had set. The score was 0 if the sentence differed, 1 if it captured part of it and 2 if it meant the same.
For the Polyglot post, the score dropped from 1.5 to 1.0 after restructuring. The readers picked the sentence that answered the title at the time, 'Why Unreal chose Verse over C++', as the main point. One reader wrote the main point as the real reason Unreal picked Verse over C++ was not syntax but to change the way gameplay code is thought about (a worldview for handling failure and state). The main sentence I had set was about how the value of knowing several languages is changing. Even with the main point pulled forward, the title asked a different question, so readers took the title's answer as the main point. When I picked the body's side as the main point and ran it again, the original and the new version both scored 1.5. I changed the title to match that main point: 'Coding got easy. Do we still need to learn more languages?'
The same thing happened with headings. Readers see the headings before the body.
A heading where a borrowed term became plain words.
When I first read the heading 'Translation is one thing, adaptation another', I didn't know what it meant either. Adaptation here means reworking a story for a new stage, the way a novel is reworked into a film, but the heading alone doesn't show that. I changed the heading to say exactly what the section says, and explained the word where it first appears in the body. I also added a rule to the skill: don't put a term borrowed from another field in a heading without explaining it.
Reader test scores. 7 posts went up, 6 stayed the same and 2 went down.
Across all 15 posts, 7 went up, 6 stayed the same and 2 went down. For the Spotify post, the judge took points off because the word 'habits' the readers used in their summaries differed from 'built the structure so that' in the reference sentence. For the 4K post, the phrase one reader left out of their summary was still in the new version's body, word for word, so I treated it as noise. I also checked whether the question each reader wrote for each section matched the questions in the new outline. In the Shadows post, a reader didn't see the boundary between two sections, so only four of the five sections matched.
I expected that restructuring would help readers catch the main point, but what readers followed first was the title and the headings.
What's left
These are things I haven't settled or am not yet sure of.
The scores wobble. The judging subagent sometimes gave 1 and sometimes 2 to nearly identical summaries. I only ran up to two readers per post, so a 0.5 difference may be noise.
I don't yet know whether the posts cut in half are better. The reader test only checks whether the main point comes across. Only real readers' reactions can tell whether a post cut below half, like the 4K post, reads better for people.
Both readers and judges are language models. I used a different model as the reader from the one that did the edits, but I don't know whether it gets lost in the same places a human reader would. The spots readers flagged as boring are only noted as candidates for the next round of edits.
The structure check turned up a possible factual error. A subagent comparing claims found a mismatch in the published version of the game shadows post. The ratio for mixing AO into sunlight was 0.45 in the formula in the body text, but 0.55 in the code of the same post. The compression took that formula out, so only the code is in the body now. A comparison built to check structure also turned out to work for fact-checking.
I wrote about cutting down the commas inside sentences in an update to the previous post.
Back to the opening question: the posts were still hard to read after I fixed the order because the order was already in place. What made them heavy was the names and numbers, sources and threads packed into every thousand characters. To trim those, the skill needed the authority to cut. Whether a trimmed post gets its main point across was something a reader with no context told me, not the side that did the edits, and the first thing that reader pointed at was the title.
References
Writing principles
- Paul Graham — Writing, Briefly (2005)
- Paul Graham — How to Write Usefully (2020)
- Julian Shapiro — Writing Well, Rewriting
- Larry McEnerney — The Craft of Writing Effectively (University of Chicago Leadership Lab talk)
- George Orwell — Politics and the English Language (1946)
Skills and tools
- anthropics/skills — doc-coauthoring
- blader/humanizer
- Panickssery, Bowman, Feng — LLM Evaluators Recognize and Favor Their Own Generations (NeurIPS 2024)
Pieces compared
