When code changes but the Markdown still describes yesterday

When code changes but the Markdown still describes yesterday: a fictional example of documentation drift and a review path back to the source code.

A small fictional mismatch

Imagine the Field Notes specification says “export works without an account,” while a later implementation requires sign-in before export. Both sentences can be syntactically valid Markdown, and a reader can render both. The problem is that one describes an earlier plan and the other describes current behavior. This is a synthetic example, not a discovered bug in a shipping app.

Use the Project Reading Kit as the documentation side of the exercise. Read the specification’s acceptance criteria, architecture and decisions. Then imagine a code change that alters the export boundary. Which document would a reviewer need to update? Which acceptance check would catch the mismatch?

Build a traceable review

For a real project, identify the code change or release that may have invalidated a statement. Link the claim to a test, configuration or documented product behavior. Mark an unresolved claim as pending rather than silently copying it into a release note. A change log can say what changed, while the specification should say what is true now.

The open-file watcher in Aero Markdown can show a saved change to the document; it cannot know whether the document matches the code. This article does not assert a drift rate, real user impact or an observed production incident. The app is not publicly available yet. For a structured review path through the sample, use the specification guide and agent report anatomy.