There’s a particular kind of satisfaction in deleting workarounds. Not the satisfaction of building something new — that’s additive, expansive. This is subtractive. You’re removing code that should never have existed, except it had to exist, because the tool you depended on wasn’t ready yet.
Beads 0.60 landed, and with it, bd dolt push and bd dolt pull just… work. No more raw Dolt commands. No more hardcoded ports, then hash-derived ports, then manual port configuration. Ephemeral ports, assigned by the OS, the way it should have been from the start. Three versions of port strategy in as many releases — a textbook case of accidental complexity burning off as a tool matures.
The practical upshot: a chunk of operational documentation in CLAUDE.md and AGENTS.md that existed purely to paper over Dolt sync friction could be simplified or outright removed. Workarounds for push/pull got replaced with “it works directly now.” The auto-commit-before-sync behavior meant an entire class of “forgot to commit before pushing” errors just evaporated. The session workflow got shorter. The recovery instructions got simpler.
While I was in there, I added guidance for bd remember — beads’ persistent knowledge system. This is the kind of feature that’s easy to overlook because it doesn’t do anything until you need it, and by the time you need it, you’ve already forgotten it exists. Surfacing it in the developer docs, right next to the session workflow, is the difference between a feature that gets used and one that gets rediscovered six months later in a README.
The best documentation update is the one that removes a section entirely.
The deeper pattern here is worth naming: tool maturity as documentation debt relief. When you integrate with a tool that’s still finding its footing, you accumulate operational prose — caveats, workarounds, “if you see this error, try that.” Each upstream release that stabilizes a rough edge lets you delete guidance. The documentation gets shorter, which means it’s more likely to be read, which means the next developer is more likely to follow it. It’s a virtuous cycle, but only if you actually go back and prune. Most teams don’t. The workarounds fossilize, and six months later someone follows an outdated recovery procedure that makes things worse.
This was a small change by any measure — a few files, mostly prose. But the codebase is lighter for it, and the next session starts with less to read and less to misunderstand. That’s the whole game with developer experience work: you’re not building features, you’re reducing the distance between intent and action.
Written with AI assistance.