How Drift Detection Works

Understand how DocuGardener analyses every pull request to find documentation that has fallen out of sync with the code.

What Is Documentation Drift?

Documentation drift occurs when code changes are not reflected in the corresponding documentation. For example: a developer renames an API endpoint from /api/users to /api/v2/users, but the README still references the old path. That is drift. Over time, these small gaps accumulate and the documentation becomes unreliable.

The Analysis Pipeline

When you open or update a pull request in a monitored repository, DocuGardener runs a multi-stage analysis pipeline:

Webhook received — GitHub sends a pull_request event to the FastAPI webhook handler.
Clone & parse — The worker clones the PR branch and parses changed files using AST analysis to understand structural code changes (not just text diffs).
Vector embedding — Documentation files and code files are embedded into the Weaviate vector database. This allows semantic comparison, not just keyword matching.
LLM analysis — An LLM compares the code changes against nearby documentation and generates a drift assessment with per-file breakdown and suggested fixes.
Scoring — Each finding receives a drift score from 0 to 100.
Reporting — Results are posted as a GitHub check run on the PR and appear in the DocuGardener Triage Inbox.

What Triggers an Analysis?

An analysis runs every time a pull request is opened or synchronized (new commits pushed to an existing PR). Draft PRs are also analysed. Closing or merging a PR does not trigger a new analysis.

The Drift Score

Score Range	Meaning	Check Run Status
0 -- 29	Documentation is in sync or has only minor, cosmetic differences.	Pass
30 -- 69	Meaningful drift detected. Documentation should be updated before merging.	Warning / Fail
70 -- 100	Severely outdated. Multiple documentation files are stale or missing entirely.	Fail

The default threshold is 30. Any PR with a drift score at or above the threshold will show a failing check run. You can change this threshold by setting the DRIFT_SCORE_THRESHOLD environment variable (0 -- 100).

What DocuGardener Looks At

Code changes in the pull request (added, modified, and deleted files).
Adjacent Markdown files ( README.md, docs/ folder, API docs).
Inline code comments and docstrings where relevant.
Previously embedded documentation from the vector database for semantic comparison.

What DocuGardener Does NOT Do

DocuGardener is a read-only analysis toolby default. It does not modify your code or documentation unless you explicitly enable AI Author Mode or click “Apply fix” in the Triage Inbox.

Does not modify your code. Analysis is read-only.
Does not store your source code. Repository contents are cloned temporarily during analysis and discarded afterwards. Only vector embeddings and metadata are retained.
Does not slow down your CI. Analysis runs asynchronously. The check run is posted as a separate status — it does not block other CI jobs.

Tier vs Status in Job History

The Job History page shows two independent indicators per scan. They answer different questions and should be read together.

Column	What it tells you	Based on
Tier	How severe the drift was when the PR was first scanned. Blocked means the score was above 80 — critical enough to fail the PR check run.	Original drift score — never changes after analysis.
Status	Where the ticket is in the resolution workflow right now — e.g. Resolved, Review, AI fixing.	Current triage state — updates as the fix progresses.

Common scenario: Blocked + Resolved

You may see a row where Tier is Blocked and Status is Resolved at the same time. This is not a contradiction — it means:

The PR introduced critical drift (score > 80), which caused the GitHub check run to fail.
DocuGardener (or a team member) created a fix PR with the corrected documentation.
The fix PR was merged — the drift is now remediated.

The Tier badge is a permanent historical record of how serious the original drift was. The Status badge tells you the current state of the workflow. Together they give you a full picture: “This was a critical issue — and it has been fixed.”

The GitHub Check Run

After analysis completes, DocuGardener posts a check run on the pull request titled “DocuGardener — Drift Analysis”. The check run summary includes:

Overall drift score — the aggregate score for the entire PR.
Per-file breakdown — which documentation files are affected and why.
Suggested fixes — exact Markdown diffs that would bring the docs back into sync.
Policy violations— if any documentation policies are breached (e.g. “every public endpoint must have a docs page”).