How StratoFusion keeps documentation current without publishing AI guesses

Documentation rarely becomes wrong in one dramatic event. It drifts a sentence at a time.

An endpoint changes but its example does not. A deployment moves to a new runtime while an old provider remains described as current. A recovery mechanism gains a limit that never reaches the operator guide. Each omission looks small in isolation; together they make the documentation less trustworthy than the implementation.

StratoFusion now uses a scheduled AI-assisted audit to look for that drift. The important word is audit. The system can inspect recent changes, compare them with canonical documentation and prepare a correction, but it cannot decide that its own answer belongs in production.

That boundary came from studying how other engineering teams automate documentation and from treating documentation changes with the same care as code changes.

What other teams have learned

Several public implementations converge on the same operating model: automate discovery and drafting, then put the result through an ordinary review process.

Ona describes a daily documentation agent that clones the code and documentation repositories, inspects the previous 24 hours of changes, writes Markdown and opens a draft pull request. The team chose a daily batch after finding that per-commit updates created too much noise. It also taught the agent to ignore dependency bumps, formatting changes and internal refactors that do not affect readers.

Intility takes a similar post-merge approach. Its reusable GitHub Actions workflow separates validation, preparation, generation and publication into isolated jobs. Generated changes arrive in a separate pull request rather than appearing directly on the documentation site.

Red Hat's Code-to-Docs workflow adds another useful control. One command proposes the documentation files affected by a code change; a human reviews that list before a second command generates updates. For larger repositories, semantic file and folder summaries narrow the search space and reduce noisy suggestions.

The lesson is not that every team needs the same tool. It is that a useful documentation agent needs a narrow job, a reviewable output and a clear stopping point.

The workflow we chose

The StratoFusion audit runs at 2:30 AM Sydney time on weekdays, after the usual merge window. It starts from the latest main branch in an isolated Git worktree and examines a rolling three-day window of changes. The overlap covers weekends, delayed runs and changes that deserve a second look without making repeated edits acceptable.

The audit looks for changes to:

• user-visible workflows;
• API contracts;
• architecture and deployment;
• provider and OAuth behaviour;
• billing and subscription rules;
• AI Search;
• testing workflows;
• the rclone data plane behind transfers, backups and synchronisation.

The same canonical documentation index is captured in light and dark variants so the article follows the reader's selected theme.

Commit messages and pull-request descriptions are clues, not proof. The agent must verify a claim against implementation, tests, configuration, migrations or stable interfaces before it can propose a documentation correction.

It then maps the verified change to the smallest canonical document. API behaviour belongs in the API reference. Deployment and environment changes belong in the deployment guide. Transfer-worker behaviour belongs in the rclone service guide. User workflows belong in the relevant user guide. Historical reports and completed runbooks are deliberately excluded because rewriting history creates a different kind of inaccuracy.

The complete, reusable task prompt is published in the Scheduled Documentation Maintenance guide.

Why the agent does not publish

An AI model can compare a large codebase with a large documentation set more consistently than a tired person can do every evening. It can still misunderstand intent, overstate an implementation detail or turn an internal mechanism into a public promise.

For that reason, the first three scheduled runs are report-only. They identify the commits and documentation areas reviewed, show the evidence behind each finding and recommend corrections without editing a file. This onboarding period lets us measure whether the scope and prompt produce useful signal before granting the task permission to write.

After that review, the next level of autonomy is limited to a draft pull request. A proposed change must still pass validation, receive human review, merge through the protected main branch and complete the normal production deployment. The agent cannot merge, deploy, force-push or publish directly.

This resembles the governance used by large documentation projects. Kubernetes distinguishes reviewers from approvers and expects documentation pull requests to pass preview checks before approval. GitHub's CODEOWNERS mechanism can automatically request the relevant reviewers and make their approval a branch-protection requirement.

Human review is not a ceremonial final click. It owns product intent, reader impact and the decision to publish.

Semantic review and deterministic checks do different jobs

The scheduled audit is useful for questions that require judgment:

• Did this code change alter behaviour a user or operator needs to understand?
• Which canonical document owns that explanation?
• Does the current wording describe the implementation accurately?
• Is the evidence strong enough to propose a correction?

Other questions should not be left to a language model. A file either exists or it does not. A relative link either resolves or it does not. An OpenAPI description either matches its generated output or it does not.

That is why the longer-term design combines semantic review with deterministic documentation checks. Docusaurus can fail a production build on broken links. Vale applies repeatable terminology and prose rules. Lychee checks links in Markdown and HTML and can also run on a schedule for external-link health.

API documentation deserves the same treatment. The OpenAPI Initiative recommends treating an OpenAPI description as a first-class source that can drive rendered reference documentation, tests and generated code. Where a fact can be generated or validated from a contract, automation should compare facts rather than ask a model to remember them.

The division is simple:

Use AI to find and explain possible drift. Use deterministic tools to prove mechanical correctness. Use people to approve meaning and publication.

Noise is an operational failure

A documentation agent that opens a pull request for every internal refactor will quickly be ignored. High recall is not enough; the system must be conservative enough that a report is worth reading.

The StratoFusion prompt therefore prefers a documented no-op over a speculative edit. It excludes generated output, routine dependency changes, dated reports, archives and changes without reader impact. When evidence is incomplete or contradictory, the task records the ambiguity and leaves the documentation unchanged.

We will judge the workflow by more than how many words it writes. Useful measures include:

• the proportion of runs that correctly produce no change;
• the false-positive rate of proposed corrections;
• how often draft changes are accepted, revised or closed;
• the age of genuine drift when it is discovered;
• whether the same finding returns after a correction;
• the time a reviewer needs to understand and approve a proposal.

If the task creates attention debt, its scope, cadence or instructions need adjustment. Automation should reduce the burden of maintaining documentation, not move that burden into a noisier inbox.

Documentation remains part of the product

The goal is not a site that changes every morning. It is a product whose explanations remain connected to its behaviour.

Scheduling the audit makes drift easier to notice. Isolating it in a worktree contains its changes. Requiring implementation evidence keeps it grounded. Draft pull requests make the result inspectable. CI catches mechanical errors. Human review protects intent.

No single control is sufficient, but together they create a practical maintenance loop: detect, verify, propose, validate, review and publish.

That is the same shape we prefer elsewhere in StratoFusion. Complicated work can be automated, but authority should remain explicit—and the final result should always be explainable.