Review drift cards and open focused doc PRs

Overview Use Moxie Docs to spot when your docs have fallen behind your code and quickly open focused pull requests (PRs) to fix them. You’ll review “PR opportunities” cards, open a proposed PR, and choose to apply, edit, dismiss, or mute findings. Admins can also turn specific detectors on or off per repository.

What you’ll need

• Access to your team’s Moxie Docs workspace
• Your GitHub repository connected via the Moxie GitHub App
• Workspace admin role to dismiss/mute findings or change automation settings (owners/admins only)

Understand drift and PR opportunities

• Drift means your docs no longer match the code. Examples include stale or thin docs, undocumented APIs, orphaned pages, or convention mismatches. Cosmetic changes are suppressed.
• Moxie surfaces these as PR opportunities on the Docs dashboard. Each opportunity appears as a card with a short summary and actions.
• When you open a PR from a card, Moxie includes helpful guidance in the PR description and posts a single, deduplicated convention review comment on GitHub as findings change.

Find and review drift cards

1. Go to Docs dashboard in your Moxie workspace.
2. Scroll to the PR opportunities section. You’ll see cards grouped by repository.
3. Select a card to expand details. Review:
   • What changed or is missing
   • Suggested doc updates Moxie can open as a PR
   • Repository name and any related notes

Open a proposed PR from a card

1. On the card, select Open proposed PR. Moxie creates a focused documentation PR in GitHub.
2. In GitHub, review the PR description. Moxie aligns the description to your repo’s conventions.
3. Check the single “convention review” comment from Moxie. It updates automatically if findings change, so you won’t get duplicates.
4. If everything looks good, proceed as you normally would: request review, make edits, and merge when ready.

Apply or edit the suggested changes

• Apply as-is: Merge the PR after your normal review.
• Edit first: Use Edit on GitHub to adjust files or the PR description. Moxie’s convention guidance stays in the same PR comment thread.

Dismiss or mute a finding (admins) Use this when a card isn’t useful or should be hidden for a while.

1. On the card, open the overflow menu (· · ·).
2. Choose one of:
   • Dismiss: Hide this finding permanently.
   • Mute for 7 days: Hide until 7 days pass.
   • Mute for 30 days: Hide until 30 days pass.
   • Undo: Re-show a previously dismissed or muted finding. Notes

• Only workspace owners/admins can dismiss or mute.
• Dismissed or muted items disappear from PR opportunities until the mute window ends or you undo.

Turn specific detectors on or off per repository (admins)

1. Go to Account in your Moxie workspace.
2. Open the Repository automation tab.
3. In Detectors, use the checkboxes to enable or disable kinds of drift to flag for this repository (for example: stale docs, thin docs, undocumented APIs, orphaned pages, convention mismatches). Changes take effect for future findings.

Tips

• Start with high-signal cards: undocumented APIs and orphaned pages often deliver quick wins.
• If you see repeated low-value signals, mute for 7 or 30 days and adjust detector checkboxes later.
• Keep PRs focused. Smaller, targeted doc fixes are easier to review and merge.

Troubleshooting

• I don’t see PR opportunities: Confirm the repository is connected and you’re viewing the correct workspace. If you’re an admin, check detector settings on the Repository automation tab.
• I can’t dismiss or mute: Ask a workspace owner/admin to adjust or grant the right role.
• The PR shows multiple convention comments: Moxie posts a single deduplicated comment. If you see more than one, refresh—earlier duplicates are consolidated as updates roll in.

What happens in GitHub

• PR description alignment: Moxie guides authors to follow your repo’s description conventions.
• Convention review comment: A single comment updates as findings change, reducing noise while you iterate on the PR.