The app is past being built and into being changed continually, but the
documents still read as a project being executed: the plan opened by telling its
audience to work top-to-bottom, and §13 listed M0 through M10 as a queue when
all of them shipped days ago.
The milestones stay, marked as shipped. Their "Done when" criteria describe
correct behaviour and several have become tests, so they are worth more as a
specification of working subsystems than they would be archived. If one stops
matching reality, that is a bug in the document.
AGENTS.md now says when to update each, because both decay unless it is part of
finishing the work rather than tidying afterwards. The plan changes when a
decision changes. The log gains an entry when a fix was not obvious — the bar
being "would this have saved someone an hour", not every fix, because a log of
trivia stops being read and takes the useful entries down with it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One file was trying to be two things: a spec written to be executed
top-to-bottom, and a dated record of everything that went wrong on the way. At
1,882 lines it did neither well, and the log was 36% of it — which is why the
plan's opening went unmaintained for days while the log grew every hour.
docs/plan.md keeps the decisions and the reasoning behind them, including the
risk register. docs/implementation.md takes the dated entries: the problems, the
wrong theories, the measurements that settled them. Git already says what
changed; that file says why it was hard, which is the part worth reading before
debugging something similar. Most entries describe something that looked like
one bug and turned out to be another.
Each points at the other, and the four referring files — AGENTS.md, README.md,
NEXT_STEPS.md and async_refactor.md — now point at whichever half they meant.
Git tracked the rename, so history follows plan.md rather than starting over.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 16:29:47 -05:00
Renamed from docs/IMPLEMENTATION_PLAN.md (Browse further)
