Living Documentation — Docs That Decide Their Own Update Cadence
Watch every commit. Decide what's significant. Regenerate the README, the architecture diagram, and the dataflow chart only when reality has actually shifted. End the week with a digest in plain English.
Why this exists
Documentation rots because the update rule is wrong. Regenerate on every commit and the docs become noise — a churn of diff-shaped diagrams nobody trusts. Regenerate only on demand and they're stale by the time anyone looks. The right cadence is neither aggressive nor lazy. It's learned. The agent should infer, from the shape of past commits, what counts as a real shift in the system — and only spend tokens, attention, and reader trust when the shape has actually moved.
What you get back
- An agent that watches every commit and self-throttles — silent on cosmetic changes, loud when the architecture has actually shifted.
- Regenerated architecture diagrams and dataflow charts only when the system's shape moves, not every time a variable gets renamed.
- A weekly Monday digest in plain English — the kind of thing a teammate returning from vacation can read in two minutes and be caught up.
When to reach for this pattern
Fast-moving services where the architecture is in motion every sprint. Multi-team monorepos where no single person can hold the whole picture. OSS projects with rotating contributors who need to ramp on Monday and ship by Friday. Anywhere the real question isn't "what does this code do" but "what changed, and why does it matter" — this pattern answers that question on a cadence the codebase sets for itself.
Watch this codebase. On every commit, decide whether to regenerate
the architecture diagram, the data-flow chart, and the README — but
only if the change is significant enough to matter. Decide what
"significant" means by inferring it from past commits. End every
week with a digest in plain English of what changed and what it
means for someone returning from vacation.Paste this into Claude, Cursor, or Copilot. Change one thing that matters to you.
What I learned shipping it
- Most docs rot because the update threshold is set to 'every PR' or 'never' — both produce garbage.
- Learned-significance is the missing middle gear: the agent infers what 'matters' from the commit history itself.
- Weekly digests are how absent humans stay current — the artifact isn't the diagram, it's the narrative.