Stop your docs drifting from your code: catch it on every change Tessl published the first post in a three-part series on building a "docs-sync loop" that keeps a command-line tool's README in sync with its code, pairing a deterministic Node.js test that runs the CLI and compares its commands against the README with a Tessl verifier, a plain-English rule an LLM checks each change against. Tessl defines a loop as an agent process that takes a defined input, runs an agent in a container with only the access and secrets that job needs, and produces a defined output, and argues that checking the output is the real work that makes a loop worth running rather than "just another cron job." The post covers only Part 1, the check itself; the loop that opens a pull request to fix drift is slated for Part 2. ARTICLE Stop your docs drifting from your code: catch it on every change Chandler Mayo TL;DR: A loop is an agent process that does one job, with a defined input and output, in an environment you control. A docs-sync loop, for example, compares a CLI's README with its code and opens a pull request when they've drifted. But a loop is only as good as your ability to trust it, so before you build one, you need a check you can trust. In this first post of a three-part series, you'll build that check: a test and a Tessl verifier that check every change to a CLI's docs. You'll watch it fail when it should and pass when it should, and by the end you'll have a check that's useful on its own, before there's a loop to put it in. The problem: agents ship code faster than anyone can keep the chores around it in shape. Your coding agent can ship a feature in minutes. The chores around it are a different story: docs drift, tests get flaky, and agent instructions go stale, all week long. Who's keeping up with all of that? If you're not sure, you've already met the problem this series solves. Doing it all by hand doesn't scale. You could ask an agent to "tidy up" every so often, but without a way to check its work, all you know is that it ran, not whether it fixed anything. There's a better way. It's called a loop, and this series walks you through building one. What you'll get out of this: in this post, you'll build the check for a loop that keeps a CLI's docs in sync with its code. It's two checks on every change: a deterministic test, a standard Node.js test that runs the CLI and compares its commands with the README, for what a script can check; and a Tessl verifier https://docs.tessl.io/codifying-and-enforcing/verifiers-overview , a rule written in plain English that an LLM checks each change against, for what takes judgment. That means changes that forget the docs get caught while you're still on the branch, including the ones your tests can't see. Better still, every loop needs a check like this, so once you've built one, the loop in Part 2 has something to stand on. What is a loop? At Tessl, a loop is an agent process that does one job. It takes a defined input, runs an agent in a container with only the access and secrets that job needs, and produces a defined output. An implementor loop, for example, takes the spec from a Linear ticket, runs an agent to build the code, and opens a pull request. A reviewer loop might then check that pull request. Chain loops like these together and you get a workflow. Here, you'll build one loop: a loop that keeps a CLI's README in sync with its code. This series is all hands-on, so if you want the bigger picture first, Feedback loop engineering https://tessl.io/blog/feedback-loop-engineering-making-your-project-agent-ready explains the different kinds of loops and why they matter, and Context-Driven Factories https://tessl.io/blog/context-driven-factories shows how they come together into a factory. Checking the output is what matters most. Scheduling an agent is easy. Trusting what it does is the real work, and it's what makes a loop worth running, rather than just another cron job. Docs drift makes a great first loop, because the job is small, drift is easy to spot, and you can check the result. It's also exactly where we suggest starting: pick one narrow problem, and run the loop by hand before you trust it on a schedule. Once you've built this one, Tessl's docs have more example loops https://docs.tessl.io/automations/overview/overview/example-schedules to try next. What you'll build Across the series, you'll build a loop that keeps a CLI's README in sync with its code: it blocks changes that forget the docs, and opens a pull request to fix any drift that slips through. It comes together in three parts: - Part 1: A check for every change this post . Two checks every change has to pass: a test that compares the CLI's commands with the README, and a Tessl verifier that checks the README is updated whenever a command changes. - Part 2: A weekly sweep. A loop you write yourself, scheduled to compare the docs with the code and open a pull request when they've drifted. - Part 3: Close the loop. Turning the check into a gate: running it on every pull request and blocking changes that fail, then using what the sweep finds to make it stronger. Once it's enforced as a gate, it stops new drift. The sweep catches whatever gets past it, and each catch shows you where to tighten the gate. This post builds the check, boxes 1 and 2 in the diagram. Prerequisites To run everything smoothly, here's what you need before you start. - Node.js and git. The example CLI has no dependencies. - The Tessl CLI and a free Tessl account. Install the CLI with curl -fsSL https://get.tessl.io | sh , then run tessl login . If you don't have an account yet, you can sign up for a free one when you log in. If anything below doesn't behave, the verifier docs https://docs.tessl.io/codifying-and-enforcing/verifiers-overview have more details to help you along. Step 1: Set up a sample app You need something to check, so this series uses a tiny sample CLI called tally , which you'll build first. There's nothing special about it: two commands and a README, just enough for drift to happen. Once you've seen the check work, you can and should point the same setup at a real project. Set up a working directory and follow along. Create a folder with three files in it. First up, the CLI itself, which lives in bin/tally.js : 1 /usr/bin/env node 2 3// Every command the CLI supports, with the description shown in --help 4const commands = { 5 add: 'Add a number to the running total', 6 reset: 'Set the total back to zero', 7}; 8 9const cmd = process.argv.slice 2 ; 10 11if cmd || cmd === '--help' { 12 // Print usage and the command list 13 console.log 'Usage: tally