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.

In CI mode, read ci-mode.md first. It replaces Step 1 and the Vale run in Step 2, and sets the output format for Step 6. Steps 3 to 5 apply unchanged.

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

Run make lint_prose FILES="<files>", in the main checkout or a worktree alike. The target installs the Vale version pinned in .mise.toml into .bin/vale when it is missing, so a fresh worktree needs no setup beyond network access.

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>
make lint_prose FILES="<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 scans the whole MDX file, including text inside JSX components such as <Note> and <Tab>, and inside table cells. A clean run still does not prove compliance, because CI runs Vale at MinAlertLevel = error and only some rules are errors. The error-level rules, which block the merge, cover spaced em dashes, navigation-path arrows, vague link text, terminology, units, sentences that open with "But" or "So", and gendered language. Do not spend model judgment re-checking those.

The rest of the style guide passes CI wherever it appears, in plain prose as much as in a component. Contractions are not flagged at all, and first person, future tense, and filler are warnings or suggestions that CI never shows. Grep for them yourself over every changed line:

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 -nEi '\b(simply|just|easily|basically|obviously|very)\b' <files>  # filler

Report a hit only on a line the diff changed. A contraction inside a quoted UI string or error message, such as Can't reach the server, is a literal 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.

Step 4. Check the style guide items Vale cannot see

Read the "Style guide" section of AGENTS.md. Vale enforces the mechanical half. These are the rules that need reading:

• Passive voice where the actor is known. "Feedback is treated as a signal" hides who treats it. Skip when the actor is genuinely irrelevant or unknown.
• Filler and hedging: "Note that", "Specifically", "simply", "easily", "just", "very", "basically", "obviously". Cut the word, keep the sentence.
• A pronoun, "this", or "the above" whose antecedent the diff removed. Compression is the usual cause: the noun the sentence refers back to sat in a clause the edit cut. Name the thing again.
• A condition, default, or requirement the diff shortened away. Compare the hunk against its base rather than reading the new text alone. A sentence that got shorter by dropping when the behavior applies, or what value it applies to, is a regression, and it lints clean. Quote "Be concise: cut filler words and wordy phrases" and name the fact the cut removed.
• Product versus common noun capitalization. A capitalized feature name that appears nowhere else in the file, or that disagrees with the UI label used elsewhere on the same page, is the tell. Grep the file for the term's other casings before reporting.
• Bold in body text beyond UI labels. Match what the rest of the page does rather than an abstract standard.
• Repetition inside the diff. The same list of items enumerated twice in one short section, or a sentence restating the one above it.
• Link text that does not describe its destination, and two different labels pointing at the same anchor.
• Version minimums written with >= in prose. The convention is "v0.153.4 or later"; >= belongs only in package specifiers such as langsmith>=0.3.13.

Measure before reporting a convention violation. If you are about to say a heading form or phrasing is wrong, grep the repository for how often it already appears. A form used widely is established practice, not a defect, however much the guide seems to prohibit it. Report the count either way.

A diff can also leave a convention rather than break a new one. Lowercasing the explanation in - **Term**: Explanation., dropping a trailing period, or swapping a colon lead-in for a dash each reads as a harmless copy edit on its own. Compare the before and after of that exact form, then count both spellings across src/. When the base was following the majority, the change is the finding.

Measure the same way when the diff adopts a convention rather than breaks one, because a repeated block has three parts and matching two of them still lands wrong:

• Component. <Note> or <Warning> or plain prose.
• Wording. Byte-identical to the siblings, or subtly reworded.
• Placement. Before or after the intro paragraph, relative to imports and the first heading.

A status callout copied word for word from the one page in thirteen that puts it below the intro is a finding, and only a placement count surfaces it. Report the count for each of the three.

When the same block appears on three or more pages, say so: it belongs in src/snippets/ rather than duplicated. See add-docs-page.

Step 5. Check the mechanics the diff implies

Only when the diff triggers them:

• A new page: is it in src/docs.json, in the right product, tab, and group?
• A renamed or deleted page: are inbound links and the docs.json entry both updated?
• New internal links: root-relative, and free of /python/ or /javascript/?
• A new code block: does it carry a real language tag, and are imports sorted?
• A page or heading that changed URL: is there a redirect?
• A new JSX tag: is it a Mintlify built-in or imported on the page? Look up a tag new to src/ on Mintlify components. An invented tag renders as nothing, so report it as blocking.
• A PR target: does the description reference its Linear issue with Closes DOC-N or Refs DOC-N, when one exists? Does it end with a plain AI-disclosure sentence and carry no Generated with badge? check-pr-ai-attribution fails a PR with a badge.

The add-docs-page skill covers the page mechanics in detail. Point at it rather than restating the procedure in a finding.

Step 6. Report

Group by file. For each finding:

src/langsmith/example.mdx:42
Rule: "State requirements and constraints up front"
The admin permission requirement appears after step 3, but governs all of them.
Suggested: move it above the numbered list.

End with a one-line verdict: what blocks merge (Vale violations, missing nav entry, broken link) versus what is a suggestion.

If nothing turns up, say that plainly. "No findings" is a valid and useful result, and is more useful than a manufactured one.

In CI mode, write the findings file that ci-mode.md describes instead of this report. Do not judge whether a fact is true: a default, a version floor, an environment variable, or a UI label belongs to verify-against-source, and sentence length and rhythm belong to docs-team-voice. Both run alongside this skill. Keep each replacement to the change the cited rule requires, so it cannot carry an unchecked rewrite of a label or value along with it. Map the verdict onto severity: a merge blocker is must_fix, a missing requirement or cut condition is major, and the rest is minor. A finding from Steps 3 and 4 is auto only when it is one of the mechanical cases listed there.

Running after an authoring skill

add-docs-page invokes this skill at its verification step, in working-tree mode, on the files it just changed. Two constraints keep that useful:

• Review finished edits, not drafts. Findings on a half-written section go stale as soon as writing resumes, and reporting them trains the reader to ignore the report. Run after the edit is complete and before the commit.
• Scope to the files the authoring pass touched. Do not widen to the rest of the branch. If other files changed earlier and also want review, say so and let the user ask.