Closing the Loop With Living Documentation
Why the workflow isn't finished until the outcome is written back somewhere findable — a real changelog format, a routing table, and the meta-example of asking an agent to maintain its own knowledge base.
Confirmed Isn’t the Same as Closed
Module 4’s first lesson ended at “confirm” — the batch matches the verified reference. But confirming a change is correct in the moment doesn’t help the next session, or a teammate three weeks from now, unless the outcome gets written down somewhere it can actually be found again. The loop isn’t closed until it is.
A Real Changelog Format
One project’s root CHANGELOG.md uses a simple, consistent entry format, newest first:
## YYYY-MM-DD
### [tag] Short title
- Bullet with specific detail
- Another bullet if needed
With a fixed tag vocabulary — [feature], [bug], [ux], [refactor] — and an explicit rule for bug entries: include the symptom, the root cause, and the fix, not just “fixed a bug.” That structure exists because “fixed a bug” tells a future reader nothing; “objectives reset on refresh because saveState() was called before loadState() completed” tells them exactly what to check if something similar happens again.
The same project routes detailed entries to per-area changelog files (one per top-level folder) and keeps only a one-line summary in the root file — the routing table from Module 2’s instructions-file lesson is what makes that automatic instead of a judgment call every time.
The Meta-Example: Asking for the Habit Itself
The most interesting entry in this project’s own lessons-learned notes isn’t about a bug — it’s about how the living-documentation habit came to exist at all:
“Should Claude also update the lessons-learned files when a new bug/fix/pattern is discovered, the same way it updates the changelog?”
That single question — framing a new desired behavior as an analogy to an existing one the agent already follows — is what turned “update the changelog” into a standing, permanent habit covering a second document (lessons-learned) as well. The general pattern is worth naming on its own: “should you also do X the same way you do Y?” is a more effective way to introduce a new standing behavior than “always remember to do X,” because it anchors the new rule in something already proven to work, rather than asking the agent (or a person) to hold a brand-new instruction in mind indefinitely.
The result, concretely: what used to be a one-time snapshot of decisions became a document that grows automatically, every session, without a separate reminder each time.
What Goes Where
Putting this course’s documents together: the instructions file (Module 2) holds the current, standing rule. The changelog records what changed and when. The lessons-learned (or equivalent knowledge base) records why — the reasoning, the root cause, the pattern — categorized so it can be searched later by topic rather than by date. A rule earns a permanent place in the instructions file specifically because a pattern in the lessons-learned repeated enough times to justify becoming a standing check — the same escalation path from Module 2’s “you said it twice” signal.
An entry like “fixed some bugs” or “updated the docs” satisfies the letter of “keep a changelog” while providing none of its value. If you can’t summarize what changed in one specific sentence — naming the file, the symptom, or the decision — the entry isn’t done yet, the same way a spec with a vague quality word in it isn’t done yet. Write every entry as if the reader has zero context, because eventually they will.
A team's changelog has an entry reading: '## 2026-06-01 — [bug] Fixed login issue.' What's missing, and why does it matter?
Reveal Answer & Explanation
It’s missing the symptom, root cause, and specific fix — without those, the entry can’t help anyone diagnose a similar problem later, which is the entire point of writing it down instead of just fixing it and moving on.
“Fixed login issue” tells a future reader that something was wrong with login and now it isn’t — it gives them no way to recognize whether a new bug they’re seeing is the same root cause resurfacing, or how it was actually resolved if they need to apply the same fix elsewhere. A useful entry names what happened (e.g., “session token expired mid-request, causing a 401 on page two of the form”), why it happened, and what specifically changed to fix it — following the same discipline this course’s earlier lessons apply to specs and acceptance criteria: replace vague summary language with specific, checkable detail.
Example: A Filled-In CHANGELOG.md Entry
Following the format and discipline from this lesson — specific enough that a reader with zero context could act on it.
## 2026-07-21
### [feature] Client Onboarding — Data Migration Confirmed step added
- Added 9th onboarding checklist step (between steps 7 and 8) across all
40 client pages; defaults to "Not Started" for existing clients
- `saveState`/`loadState` updated to persist the new step key
- See `changelog/clients.md` for the full per-client rollout list
### [bug] Contract Terms table — renewal date sorting was alphabetical, not chronological
- **Symptom:** Clients with a renewal date in "Jan" sorted before "Dec"
of an earlier year
- **Root cause:** Dates were sorted as strings, not parsed to `Date` objects
- **Fix:** Sort comparator now parses `YYYY-MM-DD` before comparing
Up Next
The capstone in Module 5 asks you to write all three artifacts — an instructions-file section, a quantified spec, and a workflow checklist — for the real recurring task you’ve been building toward since Module 1.