Docs Review

Review docs prose

Review documentation prose that changed in $ARGUMENTS, or in the working tree and current branch if that is empty.

Two rules govern this whole skill:

• Review the diff, not the page. Prose that was already there is not in scope, however much you would have written it differently.
• Skip rules that do not clearly apply. A short report of real findings is the goal. Do not stretch a rule to reach a finding, and do not restructure prose that is already fine.

Step 1. Resolve the target

Run git fetch origin first so main is current. Resolve in this order:

1. A number or GitHub PR URL means a PR. Get the branch with gh pr view <n> --json headRefName.
2. A branch name is used directly.
3. Empty, with uncommitted changes present means the working tree. Take the files from git status --porcelain plus git diff --name-only --diff-filter=d origin/main...HEAD. No checkout, no worktree: the files are already in front of you. This is the mode that runs after an authoring skill.
4. Empty, with a clean tree means the current HEAD against main: git diff --name-only --diff-filter=d origin/main...HEAD.

Narrow to src/**/*.mdx and src/**/*.md. If nothing changed, say so and stop. Never review anything under build/.

For modes 1 and 2, check out the target before inspecting anything. Your working tree is almost certainly on a different branch, and linting it silently reports on the wrong content.

For a PR, check the branch out in the main working tree so any edit that follows lands on the open branch:

git stash list            # confirm nothing is about to be lost
git status --porcelain    # must be clean; stop and ask if it is not
git fetch origin <branch>
git checkout <branch>     # tracks origin/<branch>

Use git checkout <branch>, not git checkout -b or a --no-track branch. A new branch is only correct when the review is of main, or when the user asks for a separate branch of their own edits. Confirm the checkout by grepping for a string the diff added.

For a review with no edits to follow, a detached worktree is also fine:

git worktree add --detach <scratch-dir>/review-wt origin/<branch>

Do all reading and linting inside it, and git worktree remove --force it when the review is done.

State the target, the resolved SHA or "working tree", and the file count before going further.

Step 2. Run Vale

In the main checkout, make lint_prose FILES="<files>" is enough. Vale's binary is gitignored, so a fresh worktree does not have it and make lint_prose there fails with .bin/vale: No such file or directory. From a worktree, call the main checkout's binary by path so it picks up .vale.ini:

cd <worktree> && <main-checkout>/.bin/vale --glob='!**/node_modules/**' <files>

Vale is deterministic and CI blocks on it, so its output is not a judgment call. Report every violation with its file and line. If invoked with --fix, correct them; otherwise list them.

Lint the merge-base version of each changed file as well, and report the difference rather than the raw count:

git show origin/main:<file> > <scratch>/base-<name>
<main-checkout>/.bin/vale <scratch>/base-<name>

A file that already failed on main carries pre-existing debt the author did not introduce. A file that was clean on main and fails now is this diff's CI blocker. Say which one it is, because attribution is the difference between a finding the author has to fix and one they can reasonably decline.

Reading the diff text is not a substitute for either run. A patch shows added lines without their column offsets or their surrounding component, which is exactly what these rules turn on.

Vale covers terminology, contractions, first person, future tense, Oxford commas, spaced em dashes, navigation-path arrows, and heading case. Do not spend model judgment re-checking what Vale already checks, with one exception: Vale does not scan every part of an MDX file, so a clean run is not proof of compliance. It misses content inside JSX components (<Note>, <Tip>, <Tab>, <Step>, <Accordion>) and inside table cells. A page can pass Vale with four spaced em dashes in it.

Grep the mechanical rules yourself over any file whose diff touches those places:

grep -nE ' — | – ' <files>                      # spaced em dashes
grep -nEi "\b(don't|can't|won't|isn't|it's|you'll)\b" <files>   # contractions
grep -nE '\b(we|our|us|I)\b|\bwill [a-z]+\b' <files>          # first person, future tense
grep -n '→' <files>                              # navigation arrows

Report a hit inside a component the same way you would report a Vale error: it would be one if Vale could see it. A — used as an empty table-cell marker is fine and is not a finding.

Step 3. Check structure against the style guide

Read the "Structure conventions" section of AGENTS.md in the repository root, then check the changed hunks against it. For each finding, quote the rule you are applying.

Look for these, and nothing else:

• A new section or page that does not open with a one-sentence definition of what the thing is or does, followed by the benefit, then the task. Skip when the section continues directly from the one above it.
• Steps introduced without a colon lead-in, or steps that are not imperative. Skip for a list that is not a procedure.
• Three or more options, parameters, or permissions written as prose where - **Term**: Explanation. would carry them. Skip for fewer than three.
• A feature or class linked on repeat mentions, or a first mention that is not linked. Skip when the repeat is far enough down the page to be a genuine re-entry.
• A permission, plan tier, or preview requirement stated after the steps it governs rather than before them.
• A hard constraint hedged ("it is generally not possible to change this") where the guide calls for a flat fact ("Once set, it cannot be changed.").

Pointer phrasing is deliberately absent from that list. Both the long form ("For more information, see [Page]") and the short form ("See [Page]") are established. Do not convert between them in either direction.