[DOCS] `/review <pr>` description in Commands reference does not match v2.1.202 behavior or distinguish it from `/code-review`

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/commands

Section/Topic

The /review [PR] row of the "All commands" table, and the surrounding "Before you ship" paragraph that lists /code-review and /review side by side without explaining their current relationship.

Current Documentation

From the "Before you ship" paragraph in the Commands reference:

/diff shows what changed, /code-review checks the diff for correctness bugs and cleanups and can apply the findings with --fix, /review gives a read-only review of a GitHub pull request, and /security-review checks the diff for security vulnerabilities. /code-review ultra runs a multi-agent review in the cloud.

From the /review [PR] row of the "All commands" table:

/review [PR] — Review a GitHub pull request by number. With no argument, lists open PRs to pick from. For a cloud-based review, see /code-review ultra.

For comparison, the /code-review row in the same table reads:

/code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [target] — [Skill]. Review the current diff for correctness bugs and for reuse, simplification, and efficiency cleanups. Pass --fix to apply findings to your working tree, --comment to post them as inline GitHub PR comments, or ultra to run a deep cloud review. … See Review a diff locally for effort levels and targeting

What's Wrong or Missing?

The changelog for v2.1.202 records:

Changed /review <pr> back to a fast single-pass review; use /code-review <level> <pr#> for the multi-agent review at a chosen effort level

This re-establishes an explicit division of labor between the two commands: /review <pr> is now a fast single-pass PR review, while /code-review <level> <pr#> is the multi-agent review at a chosen effort level. Nothing in the user-facing Commands reference reflects this division.

Three concrete problems fall out of that gap:

1. The /review [PR] row says only "Review a GitHub pull request by number" with no hint that this is now intentionally a fast single-pass review. A reader who used /review before the v2.1.185 change to /code-review medium, and again briefly between v2.1.185 and v2.1.202, will see the same row but get substantially different behavior. The row gives no way to learn that distinction from the reference alone.
2. The /review [PR] row does not document the <level> argument that the changelog assigns to /code-review <level> <pr#>. Conversely, the /code-review row lists level flags (low|medium|high|xhigh|max|ultra) but does not say it also accepts a PR number as target, which the v2.1.202 changelog and the Review a diff locally page both show it does.
3. The "Before you ship" paragraph puts /code-review and /review next to each other with no sentence that distinguishes them. A new user cannot tell from this paragraph which command is the multi-agent one, which is the fast one, or which one to choose for a PR.

The [DOCS] issue pre-dates v2.1.202 as well: the v2.1.185 changelog ("Changed /review <pr> to use the same review engine as /code-review medium") made /review and /code-review medium behaviorally identical for PRs, and that change was also not reflected in the Commands reference. The v2.1.202 changelog entry is the right moment to land the missing documentation.

Suggested Improvement

Update the /review [PR] and /code-review rows in the Commands reference and the "Before you ship" paragraph to clearly describe the v2.1.202 split.

For the "Before you ship" paragraph, something like:

/diff shows what changed, /code-review runs a multi-agent review at your chosen effort level (/code-review <level> <pr#> for a PR, /code-review --fix to apply findings, /code-review --comment to post as PR comments), /review <pr> gives a fast read-only single-pass review of a GitHub pull request, and /security-review checks the diff for security vulnerabilities. /code-review ultra runs a deeper multi-agent review in the cloud.

For the /review [PR] row, something like:

/review [PR] — Review a GitHub pull request by number as a fast single-pass review. With no argument, lists open PRs to pick from. For a multi-agent review at a chosen effort level, use /code-review <level> <pr#>. For a cloud-based review, see /code-review ultra.

For the /code-review row, add the PR-number argument and the v2.1.202 minimum-version note, e.g.:

/code-review [low|medium|high|xhigh|max|ultra] [--fix] [--comment] [target] — [Skill]. Run a multi-agent review at the chosen effort level on the current diff, a file path, a branch, a ref range, or a pull request number. Pass --fix to apply findings to your working tree, --comment to post them as inline GitHub PR comments, or ultra to run a deep cloud review. Use this command (with the PR number as target) for the multi-agent PR review; /review <pr> is now the fast single-pass alternative.

The dedicated Code Review page should also gain a short "Review a pull request locally" subsection that contrasts /code-review <level> <pr#> with /review <pr>, since the page currently only documents /code-review against a local diff and never mentions /review at all.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog evidence (v2.1.202):

Changed /review <pr> back to a fast single-pass review; use /code-review <level> <pr#> for the multi-agent review at a chosen effort level

Changelog evidence (v2.1.185, the prior change that was rolled back in v2.1.202):

Changed /review <pr> to use the same review engine as /code-review medium

The current Commands reference does not document either of these behavior changes; both only live in the changelog. The Code Review page's "Review a diff locally" section also only documents /code-review against a local diff and a ref range, and never mentions /review, so readers landing there cannot learn that /review <pr> is the fast option.