READU: Inconsistency-Driven Just-in-Time Detection and Repair of README Bugs

2026-07-17

AI Summary

This work addresses the challenge of detecting and repairing errors in README documents, which often lead to runtime failures or debugging overhead due to their mix of natural language and code snippets and their loose coupling with ground-truth sources. The authors propose READU, the first end-to-end approach that leverages inconsistency-driven mechanisms for automated README error detection and repair. READU integrates high-recall commit filtering, parallel internal and external consistency checks, false-positive discrimination, and patch generation. Evaluated on 6,000 recent commits, READU identified 244 real-world README errors with 75% precision—at an average cost of less than one minute and under $0.01 per commit—and successfully generated fixes for 217 of them. Community feedback confirmed 44 bugs and led to the manual repair of 26.

Abstract

Repository-level documentation, such as READMEs, is often the first point of contact between users and a repository. When this documentation is incorrect, users may encounter runtime errors or waste their time debugging. We call such mistakes in repository-level documentation README bugs. Addressing README bugs is challenging because documentation mixes prose with code, its connection to the source of truth is loose, and finding a bug still leaves developers to craft a repair. This paper presents READU, an inconsistency-driven technique for just-in-time detection and repair of README bugs. The key insight behind READU is that README bugs often manifest as inconsistencies between documentation and another source of truth: either repository-internal facts, such as source code, or repository-external facts, such as external dependencies. READU applies a high-recall commit filter, runs internal and external consistency checkers in parallel, uses an alert judge to remove false positives, and automatically synthesizes documentation patches. On 6,000 recent commits from six popular repositories including Linux and Spring Boot, READU detects 244 true positives with 75% precision, while consuming less than $0.01 and less than one minute per commit, on average. Of these true positives, READU correctly repairs 217. We report 66 found README bugs, of which (so far) 44 are confirmed and 26 are fixed.

Problem

• README bugs
• documentation inconsistency
• repository documentation
• software documentation
• documentation errors

Innovation

• README bugs
• inconsistency detection
• just-in-time repair
• documentation automation
• consistency checking