Many of the changes we ship to Linear don’t come with the fanfare of a full-blown launch. A bug fix here, a quality-of-life update there, our engineers are predisposed to making small tweaks that might affect how the product works.

Those changes make Linear better, but as an unintended side effect, our docs can drift out of sync with the product. Alan Doyle, a member of our Customer Experience team, wanted to close the gap without anyone having to manually reconcile the docs.

The loop

Alan built a loop that runs everyday, looking for product changes since its last run. It checks the codebase using Code Intelligence, launch-related initiatives in Linear, issues the CX team is working on, and relevant Slack channels; and then compares what it finds against our docs.

Throughout the week, the loop collects its findings in a running document. It includes the strongest candidates for a docs update, explains the context behind each suggestion, and also records changes it investigated but ruled out.

At the end of the week, the loop creates an issue for Alan to review. He works through the document with Linear Agent, deciding whether the docs need to change and, when they do, refining the proposed wording with the agent before making the update.

A seasoned workflow

Alan wrote the initial prompt with Linear Agent, put the loop to the test, and iterated over time. For example, the first version relied heavily on updates posted to Slack and Linear, which often excluded smaller changes such as adjustments to the UI or URLs; so he expanded scope to include the codebase which would capture those changes implicitly.

Alan also adjusted the cadence. Initially, the loop created a new issue for him every day, but when that became too noisy, he moved to a weekly review.

Finally, he refined the instructions to discourage change for change’s sake. The loop is now instructed to first understand the level of detail already present in a doc, and only suggest an update when it would improve accuracy. In practice, that means docs which give our users a better experience, catching gaps that would’ve lingered unnoticed otherwise.

Build your own

If you want to build something similar, start with an area where you notice content going stale because the thing it describes keeps moving. Give the loop access to both, the places where those changes appear and the material that needs to be updated, then have it periodically compare the two.

Open this prompt in Linear Agent to adapt it to your own team, tools, and signals.