Moxie Docs / Documentation
Compares the files a PR changes against known documentation gaps and lists the pages that may need an update.
GitHub PR documentation checks
Documentation checks on every pull request
Code review catches the bug. It rarely catches the doc the change just made wrong. Moxie posts GitHub check runs on each pull request that flag documentation gaps, convention breaches, and descriptions that skip your template - before the merge, while the author still has context.
Quick Answer: Moxie Docs adds three GitHub check runs to pull requests: Moxie Docs / Documentation flags changed files tied to known documentation gaps, Moxie Docs / Conventions flags changes that diverge from the repository's detected conventions, and Moxie Docs / Description aligns the PR description with your template. They are advisory by default and never fail on their own; add the check names to branch protection to make them a required merge gate.
- Before merge. Findings land on the PR while the author still remembers why the code changed.
- Advisory by default. Checks inform without blocking, so nobody's release is held hostage on day one.
- Gate when ready. Require the check names in branch protection once the signal earns trust.
What you get
What runs on the pull request
Moxie Docs / Conventions
Flags changes that diverge from conventions detected in the repo, with a summary comment kept up to date on the PR.
Moxie Docs / Description
Aligns the PR description with your repository template and marks sections that still need human input.
Branch protection ready
Standard GitHub check runs, so any of the three can become a required status check.
Same review, before the commit
Coding agents call moxie.review_change over MCP to catch breaches and falsified docs before the PR exists.
Closes the loop on merge
After merge, drift detection re-checks the touched docs and batches fixes into a Friday Cleanup PR on Pro and Team.
How it works
From install to a gated merge
- 01
Install the GitHub App
Pick the repositories to watch. Moxie never pushes to your branches; doc changes only arrive as pull requests.
- 02
First index
Moxie maps docs, gaps, and conventions so it knows what a change could break.
- 03
Open pull requests as usual
Checks appear on the next PR, with findings in the check summary and a PR comment for convention issues.
- 04
Require them when ready
Add the check names to branch protection or a ruleset to turn advisory signal into a merge gate.
Why at the PR
The cheapest moment to fix a doc is before the merge
Every doc that goes stale was made stale by a specific pull request. A check on that pull request puts the fix in front of the one person with full context, instead of a future reader who finds the mismatch the hard way.
01 The author still has context
Updating the doc takes minutes in the same branch. Weeks later it takes an archaeology session.
02 Reviewers see it in one place
The doc finding sits next to CI and tests in the checks tab, not in a separate tool nobody opens.
03 Agent-written PRs get the same scrutiny
AI-generated changes arrive fast and in volume. The check runs on every PR regardless of who or what wrote it.
04 Docs ship with the code
When the fix lands in the same pull request, the docs and the code describe the same system from the moment they merge.
Rollout
Advisory first, required when it has earned it
A new required check that produces noise gets disabled within a week. Moxie starts advisory so the team can judge the signal before it can block anyone.
Week one: advisory
Checks post findings with a neutral conclusion. Nothing blocks. The team sees what Moxie would have caught.
Tune the signal
Dismiss findings, mute them for 7 or 30 days, or turn a detector off per repo until the checks match your bar.
Require in branch protection
Add Moxie Docs / Documentation, Conventions, or Description as required status checks on the branches that matter.
At a glance
How teams verify docs on pull requests
A checklist relies on memory and a docs linter checks syntax. Neither knows which pages a code change just made wrong.
Knows which docs a change affects
PR template checkbox
Only if the author remembers
Docs linter in CI
No - checks the docs files that changed
Moxie PR checks
Yes - maps changed files to the docs and gaps they touch
Catches convention breaches
PR template checkbox
No
Docs linter in CI
Style rules you wrote by hand
Moxie PR checks
Conventions detected from the repo itself
Setup
PR template checkbox
Edit a Markdown file
Docs linter in CI
Configure and maintain rules in CI
Moxie PR checks
Install the GitHub App; no workflow file
Can be a required check
PR template checkbox
No
Docs linter in CI
Yes
Moxie PR checks
Yes, via branch protection
Fixes drift after merge
PR template checkbox
No
Docs linter in CI
No
Moxie PR checks
Friday Cleanup PR on Pro and Team
| PR template checkbox | Docs linter in CI | Moxie PR checks | |
|---|---|---|---|
| Knows which docs a change affects | Only if the author remembers | No - checks the docs files that changed | Yes - maps changed files to the docs and gaps they touch |
| Catches convention breaches | No | Style rules you wrote by hand | Conventions detected from the repo itself |
| Setup | Edit a Markdown file | Configure and maintain rules in CI | Install the GitHub App; no workflow file |
| Can be a required check | No | Yes | Yes, via branch protection |
| Fixes drift after merge | No | No | Friday Cleanup PR on Pro and Team |
FAQ
Frequently asked questions
Get started
See what your next PR would have missed
Connect a repository and Moxie's checks run on the next pull request. Free on one repo, no card required.