Drift detection and PR automation

This page shows you how to review drift findings in Moxie Docs, understand severities, and safely generate or review pull requests (PRs) that keep your documentation in sync with your code.

You will learn where to find documentation opportunities, how to mute or dismiss items, and how to control automation per repository.

What Moxie flags as drift

Moxie watches your connected GitHub repository and compares the codebase to your docs. When something no longer lines up, you’ll see a documentation opportunity. Moxie classifies these by type and severity.

• Drift types: stale, thin, orphaned, undocumented‑API, convention‑mismatch
• Severity levels:
  • Breaking: likely to confuse or mislead readers because behavior or interfaces changed
  • Behavioral: behavior changed or expanded, but not fully breaking
  • Cosmetic: wording, tone, or minor format differences that don’t affect meaning (Moxie never opens PRs for cosmetic drift)

Where to review drift

You can review drift and potential updates in two places:

• Dashboard → Documentation opportunities: Cards list findings with type and severity. Use these cards to review, dismiss, or mute items.
• Dashboard → Docs PR opportunities: Suggested and open PRs that Moxie can create or has created to update, align, or remove docs.

Review and act on documentation opportunities

Use this flow to decide what to change now and what to ignore for later.

1. Open Dashboard → Documentation opportunities.
2. Scan the cards for severity labels (Breaking, Behavioral, Cosmetic) and drift types (stale, thin, orphaned, undocumented‑API, convention‑mismatch).
3. Click a card to view details, including what changed and which docs are affected.
4. Choose an action from the card’s overflow menu (three dots):
   • Dismiss: remove the item from your queue now.
   • Mute: hide the item for a while so it doesn’t create noise.
5. Decide whether to let Moxie generate a PR or handle it later. Cosmetic items never generate PRs.

Generate or review PRs that update docs

When drift is significant, Moxie can open a scoped PR to fix or remove outdated docs.

1. Open Dashboard → Docs PR opportunities.
2. Select a suggested PR to preview the proposed doc changes.
3. Review the summary and changed files to ensure they match the current code behavior.
4. Click Create PR (or similar action) to open the pull request in your connected GitHub repository.
5. Follow your normal review process in GitHub to approve and merge. Moxie tracks the change in your workspace changelog.

Notes:

• Moxie never opens PRs for cosmetic drift.
• PRs are scoped to the docs affected by the specific drift finding.

Tune automation per repository

Control how much Moxie automates for each repo so your team sees the right level of change.

1. Open Account/Repository settings.
2. Locate Automation settings for the selected repository.
3. Toggle detectors on or off for drift types you care about (stale, thin, orphaned, undocumented‑API, convention‑mismatch).
4. Choose whether Moxie should propose PRs automatically for non‑cosmetic drift, or require manual review first.
5. Save your changes.

Tips for a smooth review process

• Start with Breaking items, then Behavioral. Leave Cosmetic for routine cleanup.
• Use Mute on noisy patterns you plan to address later; use Dismiss when the finding is not relevant.
• Keep detectors enabled only for the drift types that matter to your docs today.
• Check Docs PR opportunities regularly to keep your docs current with minimal effort.