Skip to content
Readit logo Readit

Documentation Drift Detector

The Documentation Drift Detector is a pipeline-oriented workflow that uses Readit to keep your documentation aligned with your code. It automatically checks if feature documentation is drifting away from the current implementation, and flags discrepancies during CI/CD runs.

Overview

Section titled “Overview”

Documentation drift occurs when code changes but the related documentation is not updated. This leads to outdated guides, broken onboarding, and incorrect assumptions for developers.

The Drift Detector ensures that your docs remain a reliable source of truth by continuously validating them against the latest commits.

How It Works

Section titled “How It Works”

Pipeline Trigger

Section titled “Pipeline Trigger”

On every commit or pull request, the pipeline calls a dedicated Readit link for drift detection.

Context Assembly

Section titled “Context Assembly”

Readit bundles:

  • System instructions for the Drift Detector agent
  • Relevant documentation chunks (queried by feature or module, using ?q=…)
  • The changed code under review

Agent Analysis

Section titled “Agent Analysis”

The agent checks for:

  • Outdated references (code behavior no longer matches docs)
  • Missing updates (new functions/features not covered in docs)
  • Contradictory information (examples or explanations that no longer apply)

Pipeline Feedback

Section titled “Pipeline Feedback”
  • ✅ If aligned: the pipeline passes silently.
  • ⚠️ If drift is detected: a comment is added to the PR with suggested doc updates.

Example Setup

Section titled “Example Setup”
Section titled “Readit Link”
https://readit.md/${{ secrets.READIT_TOKEN }}/doc-drift?q=user-auth

System Instructions (main.md)

Section titled “System Instructions (main.md)”
# Documentation Drift Detection Agent


## Goal
Verify that documentation for the selected feature matches the current implementation.


## Rules
- Compare code behavior against documentation.
- Flag outdated or missing explanations.
- Suggest updated Markdown snippets when needed.
- If everything is aligned, return ✅ "Docs are up to date."

Pipeline Integration (GitHub Actions)

Section titled “Pipeline Integration (GitHub Actions)”
- name: Run Documentation Drift Check
  run: |
    curl -sS "https://readit.md/${{ secrets.READIT_TOKEN }}/doc-drift?q=user-auth" \
      -o context.md


    ai-reviewer \
      --context=context.md \
      --files=src/auth/*.js

Benefits

Section titled “Benefits”
  • 🚦 Continuous alignment between code and docs
  • 🔎 Feature-aware validation using Readit search filters (?q=feature)
  • 🧩 Actionable output with suggested Markdown patches
  • 📜 Reduced manual overhead for keeping docs in sync

When to Use

Section titled “When to Use”
  • CI/CD pipelines – automatic doc checks on every commit/PR
  • Feature branches – validate that feature docs match the branch implementation
  • Release workflows – ensure docs are ready before tagging a release

Next Steps

Section titled “Next Steps”