Accretive Editing

Same problem, same solution: For technical docs, tell it when facts change, rewrite as if the wrong fact never happened, with no references or even allusions to the obsolete fact or the change. It's been effective.

From time to time I have to go further and tell it to imagine an alternate reality where the fact never happened, and write this doc as if the new thing had been true all along. This second iteration always gets it.

(A separate instruction keeps the fact-change in a dev log that serves as basis for release notes.)

I think the cause might stem from a larger issue: LLMs are trained to err on the side of caution. This is probably a good default, but can often get in the way.

When I use coding agents to help with prose, they default to bending over backwards to avoid any absolutes or otherwise risky text that might offend someone. (For example, an LLM would add a lot of hedging to my previous sentence to clarify I haven't tried all LLMs, soften the language, etc...)

While I understand the intent, it often makes the text verbose and awkward. So usually the suggested text is safer, but at the same time harder to read.

Another example is always planning/implementing a path for backwards compatibility/migration even when the project is still a prototype where the only user is myself.

In my experience they're pretty well aware of this failure mode, to the point where I learned the word accretive from adversarial agent code reviews this week. Less good at fixing it, but once you know it'll happen you can ask it not to.

It’s such an annoying pattern. When bugfixing, Opus will frequently dump massive amounts of useless context into comments when documenting changes, which is relevant to the conversation and dev process but not to future readers. I’ve found that having it just do an audit of all the comments it writes can be helpful. Like, “remove comments by default but keep a brief summary when there’s important context” can help a ton after the initial draft.

Humans working on documentation who are not set up for success and not incentivized to do the right thing exhibit exactly the same behavior.

I just tell it to make a hard switch and remove references to the old way. It is in git anyway.

I'm pretty sure that this is both

1. an artifact of agent tools only doing generic greps based on keyword searches, limiting the scope to a few lines 2. RLHF from Anthropic and OpenAI that bake in catastrophic edit avoidance

I used to have a CLAUDE.md rule that forbid inline comments and only allowed public API doc comments. That used to work perfectly back in 2025 era models. Now these models refuse to honor it and write worse comment slop.

This has become the "voice" of Opus 4.8 and I just roll my eyes when someone puts up a PR that includes more comments than code changes telling a story about all the random things it found during exploration.

These comments do cost us real dollars to endure, both from the model generation cost and the human cost of having to read them. I was hopeful Fable would have been better, but aye, it's worse and writes the same comment slop in multiple places now.

This word can be understood by many people at first sight but I don't think I had ever seen it in that form in writing before 2026.

Now everything is accretive this, accretive that.

Someone must have fed the wrong dictionary page into ChatGPT.