Every tech lead has this task. It sits in the backlog under the name “sort out the documentation,” it’s half a year old, and nobody takes it. Not because of laziness — because it has no boundaries. What does “sort out” mean? Where do you start? When do you call it done? A task without an end never gets done — it just radiates a background hum of guilt.

We decided the only way to kill that feeling is to turn it into a list. A concrete, finite one, with a clear “done.”

One call — a list of problems

For this, Meldoc has the MCP tool docs_audit. Give it a project — get the problems. There are two checks, and I’ll say it honestly: exactly two.

The first is duplicates. The audit gathers clusters of semantically similar documents within the project: here are three pages that appear to tell the same story. Then you decide: merge, delete, keep. If a pair of documents is similar but isn’t a duplicate — mark it “not a duplicate,” and it won’t surface again. In day-to-day work duplicates already pop up right in search — I wrote about that in Duplicates in documentation. But the audit serves a different mode: when you sit down and clean deliberately, instead of catching them one at a time.

The second is broken links. Documents whose [[alias]] links resolve to nowhere: the target was renamed, deleted, or never created. This signal doesn’t go stale, because it’s computed from the same connections the document graph stands on — the one from Graphs in Meldoc. A link either resolves or it doesn’t; there is no third state.

What the audit can’t do — honestly

Now about what docs_audit does not do, because this is where people usually lie. It does not detect staleness relative to the code. There’s no magic “we looked at your repository and figured out the deploy doc is lying” here. We fight staleness differently — not with an after-the-fact check, but by having the docs live in the same PR as the code: the divergence becomes visible right in review and gets fixed there, instead of accumulating invisibly for years. The audit is about the hygiene of the documentation itself: repetitions and dead links. Divergence from code is what docs-as-code is for.

It also won’t tell you what’s missing from the docs, and it won’t assign blame.

A list of problems — yes. Thinking for you — no.

For the question “what’s missing” Meldoc has a separate mechanism — the semantic layer of the graph: an agent finds an entity that’s mentioned across documents but never properly described. That was the subject of Graphs in Meldoc.

Who actually runs this

The best part: it doesn’t have to be you. docs_audit is an MCP tool, which means it’s available to an agent, like everything else in MCP in Meldoc. “Clean up the project docs” — the agent calls the audit, gets the list, works through it: proposes duplicate merges, fixes links. The task a human postponed for half a year becomes a routine you can delegate.

And since we’re on the subject: the CLI has a meldoc validate command — it checks files locally before push: duplicate aliases, required fields, cycles in the hierarchy, broken links to documents and assets. That one is about keeping garbage out of the project. docs_audit is about the garbage that already lives there.

Guilt versus backlog

“Clean up the docs” is a bad task because it’s infinite. “Resolve 4 duplicate clusters and fix 11 broken links” is a normal one: it fits into a Friday, has an end, and closes with a sense of accomplishment instead of eternity. The whole difference is that someone counted the list. Now one call does that.