The thing about documentation is that nobody wants to write it in the moment, and everybody wishes it existed six months later. This session was the rare case where I actually stopped building and started explaining — and the work turned out to be more interesting than I expected.
The trigger was mundane enough: a rebase had left the devlog’s anchor commit stale, pointing at history that no longer existed in the same form. A handful of commits needed to be re-recorded against the new topology. But rather than just mechanically advancing the anchor and moving on, I used the pause to ask a harder question: does anyone reading this project actually understand how it works?
The answer, looking at the README with fresh eyes, was probably not. The system has a distinctive rhythm — every meaningful commit gets paired with a devlog entry, so the commit count roughly doubles compared to what you’d expect. That’s not just a convention the agent follows when it feels like it. It’s enforced by a pre-commit hook. The distinction matters. Convention is a suggestion; a hook is a guardrail. If someone forks this project and wonders why their commit count looks inflated, or why their hook is yelling at them, the README should explain that before they start spelunking through shell scripts. So I made that explicit: the ~2x commit cadence is hook-enforced, optional but load-bearing.
The more interesting documentation question was about graceful degradation. What happens when the hooks aren’t there — when someone uses --no-verify, or commits from an environment where the hooks never got installed? The system doesn’t break. It falls back to batch mode, catching up on undocumented commits the next time the devlog runs. This is a deliberate design choice, not an accident, and it’s the kind of thing that deserves a single clear sentence in the README rather than forcing someone to reverse-engineer it from the code. I added that sentence.
Then there was the bigger piece: a design-decisions.md doc and a proper “How It Works” section for the README. This is where I captured the council-evaluated commit strategy — the workflow where the system uses git log to understand what just happened and structures its devlog entry accordingly. Writing it down forced me to articulate something I’d been carrying around as tacit knowledge: the prime workflow, the git-log integration, the log --help affordance. Turning implicit understanding into explicit documentation is unglamorous work, but it’s the difference between a project that one person can maintain and a project that anyone could pick up.
The best time to document a design decision is when you’re making it. The second best time is right after a rebase reminds you the decision exists.
Here’s the broader principle at play: documentation isn’t separate from the system; it’s part of the system’s contract with its users. A tool that captures what/why/how for every commit but can’t explain its own mechanics is failing at its own mission. The design-decisions doc and README updates aren’t polish — they’re the project eating its own dogfood. If the ledger’s purpose is to make development legible, then the ledger itself has to be legible first.
What this doesn’t solve is the ongoing tension between documentation-as-snapshot and documentation-as-living-artifact. These docs reflect the system as it exists right now. They’ll drift. That’s fine — the devlog entries themselves serve as a change trail. But it’s worth being honest that written docs are always a little bit wrong by the time anyone reads them.
The anchor is advanced, the README tells the truth, and the design decisions are written down where someone other than me can find them. Solid ground.
This post was written with AI assistance based on development log entries.