Designing CI documentation checks that fail only on new violations, not existing debt

Short summary

A developer shares lessons from enforcing documentation rules in CI, discovering that written rules were universally ignored. The key insight is designing CI checks that only fail on new or growing violations rather than pre-existing debt, avoiding both ignore-list sprawl and punishing contributors fixing typos. The author's own rules file failed its own check, proving the enforcement works without exceptions.

• •Written documentation rules were ignored: 47 files broke a 45-line limit, 25 of 37 folders lacked READMEs
• •Ignore lists create a second source of truth that never shrinks — avoid them
• •Design CI to fail only on new or growing violations, using git merge-base comparison

Generated with AI, which can make mistakes.