Case studies · Retail

Documentation became a review of about ten minutes a week

How the knowledge moved from people's heads into the repo, in a platform with around 950 dbt models.

In a data platform with around 950 dbt models and a dozen developers in the same repo, documentation goes stale between two sprints. Rebtech built an agent that compares the documentation against the code every Sunday and produces a finished change to review, instead of each person maintaining their own documentation.

Client: International retail company, anonymised
Industry: Retail
Engagement: AI-driven automation in data platform maintenance
Scope: Around 950 dbt models, 360 test and schema files, a dozen developers in the same repo
Roles: Senior data engineer with an AI focus
Tech stack: BigQuery, dbt, git-based repo
Delivery: Agent for continuous documentation maintenance, running weekly
Method: RAID

The challenge

Out-of-date documentation is more dangerous than none

The problem is rarely that documentation is missing. It was written once, by someone who understood what it described, and it was correct that day. Then a model moved, a command was replaced, a table took on a new meaning, and none of it showed up in the document. Nobody did anything wrong; there is simply no point in a normal workflow where someone is responsible for checking what has ceased to be true.

That makes out-of-date documentation more dangerous than none at all. Those who trust it make decisions on the wrong basis; those who do not trust it read the code instead. It shows most clearly at handover: when the written word does not match, the knowledge stays with whoever built the platform, and the dependence on individuals grows.

The solution

A deliberately narrow mandate: documentation, never code

The agent maintains three surfaces: the solution documentation, the shared business glossary and the verified facts recorded per business area. For each document it tests whether what is referenced still exists, whether the solution matches the code, whether the commands match how the team works, and whether a newer document has made the old one redundant. It then lands on one of six outcomes, each of them evidenced against something it has read in the repo:

Keep
Update
Merge
Replace
Remove
Mark as uncertain

The most important rule is that it may not guess. If it cannot evidence what holds today, it must mark the document as uncertain, with reason and date, and leave the content alone. A language model without evidence writes something plausible, well phrased and wrong, and that is the most dangerous output because it is impossible to tell apart from the correct one at review.

Results

Knowledge moves continuously from heads into the repo

Getting an agent to write documentation is quick; getting it to refrain is hard, and that is where the value lies. The development team no longer spends time on documentation maintenance but on a review that takes minutes, knowledge moves continuously from heads into the repo, and a new developer is onboarded against documentation that matches the code.

That is the difference between documentation the team uses and something the team stops opening.

In brief

01
Documentation maintenance is a weekly review rather than a project
02
Six defined outcomes, each evidenced against something the agent has read in the repo
03
Documents that cannot be evidenced are marked uncertain, with reason and date

Facing a similar challenge?

Has your documentation stopped being true?

Get in touch →Get in touch

More case studies

Same platform · same client

The troubleshooting is done before anyone logs in

Read the case →Same method · RAID

From Azure Synapse to Databricks in three months

Read the case →